{"id":30196296,"url":"https://github.com/crowrish/neople-sdk-js","last_synced_at":"2026-04-13T12:01:55.053Z","repository":{"id":309311225,"uuid":"1035719235","full_name":"crowrish/neople-sdk-js","owner":"crowrish","description":"TypeScript/JavaScript SDK for 네오플 Open API","archived":false,"fork":false,"pushed_at":"2025-08-31T03:15:57.000Z","size":423,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-02T04:22:24.131Z","etag":null,"topics":["cyphers","dungeon-and-fighter","javascript","neople","npm","sdk","typscript"],"latest_commit_sha":null,"homepage":"https://crowrish.github.io/neople-sdk-js-docs/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/crowrish.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-11T01:40:06.000Z","updated_at":"2025-08-31T03:16:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"8a5b2693-b247-43b4-b6e1-4278613b4bae","html_url":"https://github.com/crowrish/neople-sdk-js","commit_stats":null,"previous_names":["crowrish/neople-sdk-js"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/crowrish/neople-sdk-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowrish%2Fneople-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowrish%2Fneople-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowrish%2Fneople-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowrish%2Fneople-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crowrish","download_url":"https://codeload.github.com/crowrish/neople-sdk-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crowrish%2Fneople-sdk-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31751705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T09:16:15.125Z","status":"ssl_error","status_checked_at":"2026-04-13T09:16:05.023Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cyphers","dungeon-and-fighter","javascript","neople","npm","sdk","typscript"],"created_at":"2025-08-13T05:17:42.561Z","updated_at":"2026-04-13T12:01:55.046Z","avatar_url":"https://github.com/crowrish.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# neople-sdk-js\n\n[![Korean](https://img.shields.io/badge/README-한국어-red)](./README.md)\n[![Documentation](https://img.shields.io/badge/Documentation-GitHub%20Pages-green)](https://crowrish.github.io/neople-sdk-js-docs/)\n[![npm version](https://img.shields.io/npm/v/neople-sdk-js)](https://www.npmjs.com/package/neople-sdk-js)\n\n\u003cimg width=\"1200\" height=\"400\" alt=\"Frame 2\" src=\"https://github.com/user-attachments/assets/49ffab27-7b04-45c6-9daa-e53ca605b1f2\" /\u003e\n\nTypeScript SDK for Neople Open API\n\n\u003e **Note**: This documentation is written as of August 19, 2025.\n\nThis SDK is a TypeScript/JavaScript client for Neople Open API.\nYou must comply with [Neople Open API Terms of Service](https://developers.neople.co.kr/contents/policy).\n\n## Documentation\n[https://crowrish.github.io/neople-sdk-js-docs](https://crowrish.github.io/neople-sdk-js-docs)\n\n## Installation\n\n```bash\nnpm install neople-sdk-js\n```\n\n## Quick Start\n\n### Dungeon Fighter Online\n\n```typescript\nimport { NeopleDFClient } from 'neople-sdk-js';\n\nconst dfClient = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);\n\n// Search characters\nconst characters = await dfClient.searchCharacter('character_name');\n\n// Get character details\nconst character = await dfClient.getCharacter('cain', 'characterId');\n\n// Get character equipment\nconst equipment = await dfClient.getCharacterEquipment('cain', 'characterId');\n```\n\n### Cyphers\n\n```typescript\nimport { NeopleCyphersClient } from 'neople-sdk-js';\n\nconst cyphersClient = new NeopleCyphersClient(process.env.NEOPLE_CYPHERS_API_KEY);\n\n// Search players\nconst players = await cyphersClient.searchPlayer('player_nickname');\n\n// Get player information\nconst playerInfo = await cyphersClient.getPlayerInfo('playerId');\n\n// Get player match records\nconst matches = await cyphersClient.getPlayerMatches('playerId', { gameTypeId: 'rating' });\n```\n\n## Features\n\n- TypeScript support with type safety\n- **Uses Node.js built-in fetch by default (no dependencies)**\n- Multiple HTTP client support (Axios, Fetch, Got, node-fetch)\n- Node.js backend and Next.js environment support\n- Comprehensive error handling\n- Rich JSDoc documentation\n- Separate API keys support for Dungeon Fighter and Cyphers\n- Dedicated URL builder classes for URL-only usage\n- **Neople Open API full support (34 Dungeon Fighter + 11 Cyphers = 45 total APIs)**\n- **99.57% test coverage with 202 comprehensive tests for reliability**\n\n## Supported APIs\n\n### Dungeon Fighter Online APIs (34 APIs)\n- **Basic Information**\n  - `getServers()` - Server list\n  - `getJobs()` - Job/class list\n- **Characters**\n  - `searchCharacter()` - Character search\n  - `getCharacter()` - Character basic information\n  - `getCharacterStatus()` - Character status information\n  - `getCharacterEquipment()` - Character equipment information\n  - `getCharacterAvatar()` - Character avatar information\n  - `getCharacterCreature()` - Character creature information\n  - `getCharacterFlag()` - Character flag information\n  - `getCharacterTalisman()` - Character talisman information\n  - `getCharacterSkill()` - Character skill information\n  - `getCharacterBuff()` - Character buff information\n  - `getCharacterTimeline()` - Character timeline\n  - `getCharactersByFame()` - Search characters by fame\n- **Skills**\n  - `getCharacterSkillStyle()` - Character skill style\n  - `getCharacterBuffSkillEquipment()` - Buff skill equipment enhancement\n  - `getCharacterBuffSkillAvatar()` - Buff skill avatar enhancement\n  - `getCharacterBuffSkillCreature()` - Buff skill creature enhancement\n  - `getSkillsByJob()` - Skills by job/class\n  - `getSkillDetail()` - Skill detail information\n  - `getMultiSkills()` - Multiple skills information\n- **Items**\n  - `searchItems()` - Item search\n  - `getItem()` - Item detail information\n  - `getSetItem()` - Set item information\n  - `searchSetItems()` - Set item search\n  - `getMultiItems()` - Multiple items information\n  - `getMultiSetItems()` - Multiple set items information\n  - `getItemShop()` - Item shop information\n- **Auction**\n  - `searchAuction()` - Auction search\n  - `getAuctionSold()` - Auction sold history\n  - `getAuctionItem()` - Auction item detail\n- **Avatar Market**\n  - `getAvatarMarketSale()` - Avatar market sales\n  - `getAvatarMarketSold()` - Avatar market sold items\n  - `getAvatarMarketItem()` - Avatar market item detail\n  - `getAvatarMarketSoldItem()` - Avatar market sold item detail\n- **Hashtags**\n  - `getAvatarMarketHashtags()` - Avatar market hashtags\n  - `getItemHashtags()` - Item hashtags\n\n### Cyphers APIs (11 APIs)\n- **Players**\n  - `searchPlayer()` - Player search\n  - `getPlayerInfo()` - Player information\n  - `getPlayerMatches()` - Player match history\n- **Matches**\n  - `getMatchDetail()` - Match detail information\n- **Rankings**\n  - `getOverallRanking()` - Overall ranking\n  - `getCharacterRanking()` - Character-specific ranking\n  - `getTsjRanking()` - TSJ (Tournament of Souls and Justice) ranking\n- **Items \u0026 Characters**\n  - `searchCyphersItems()` - Cyphers item search\n  - `getCyphersItemDetail()` - Cyphers item detail information\n  - `getCyphersMultiItems()` - Multiple Cyphers items information\n  - `getCyphersInfo()` - Cyphers character information\n\n## Supported Environments\n\n### Supported Environments\n- Backend Node.js (Express, Fastify, Koa, etc.)\n- Next.js API Routes (Pages Router, App Router)\n- Next.js Server Actions (App Router 13+)\n- Serverless Functions (Vercel, Netlify)\n- AWS Lambda\n- Discord/Telegram bots\n\n### Not Supported\n- Browser environments (due to CORS policy restrictions)\n\n## API Key Setup\n\nDungeon Fighter and Cyphers use separate API keys:\n\n```bash\n# .env file\nNEOPLE_DF_API_KEY=your_dungeon_fighter_api_key\nNEOPLE_CYPHERS_API_KEY=your_cyphers_api_key\n```\n\n## Usage Examples\n\n### Express.js Server\n\n```typescript\nimport express from 'express';\nimport { NeopleDFClient } from 'neople-sdk-js';\n\nconst app = express();\nconst dfClient = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);\n\napp.get('/api/character/:name', async (req, res) =\u003e {\n  try {\n    const result = await dfClient.searchCharacter(req.params.name);\n    res.json(result);\n  } catch (error) {\n    res.status(500).json({ error: error.message });\n  }\n});\n```\n\n### Next.js API Route\n\n```typescript\n// app/api/character/[name]/route.ts\nimport { NeopleDFClient } from 'neople-sdk-js';\n\nconst dfClient = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);\n\nexport async function GET(\n  request: Request,\n  { params }: { params: { name: string } }\n) {\n  try {\n    const result = await dfClient.searchCharacter(params.name);\n    return Response.json(result);\n  } catch (error) {\n    return Response.json({ error: error.message }, { status: 500 });\n  }\n}\n```\n\n## URL-Only Usage\n\nFor users who want to control HTTP clients directly or only need URLs, we provide dedicated builder classes.\n\n### Dungeon Fighter URL Generation\n\n```typescript\nimport { NeopleDFUrlBuilder } from 'neople-sdk-js';\n\nconst urlBuilder = new NeopleDFUrlBuilder(process.env.NEOPLE_DF_API_KEY);\n\n// Generate URLs\nconst characterUrl = urlBuilder.searchCharacter('character_name', 'cain');\nconst equipmentUrl = urlBuilder.getCharacterEquipment('cain', 'characterId');\nconst auctionUrl = urlBuilder.searchAuction({ itemName: 'weapon', limit: 10 });\n\n// Use with your preferred HTTP client\nconst response = await fetch(characterUrl);\nconst data = await response.json();\n```\n\n### Cyphers URL Generation\n\n```typescript\nimport { NeopleCyphersUrlBuilder } from 'neople-sdk-js';\n\nconst urlBuilder = new NeopleCyphersUrlBuilder(process.env.NEOPLE_CYPHERS_API_KEY);\n\n// Generate URLs\nconst playerUrl = urlBuilder.searchPlayer('player_nickname');\nconst matchUrl = urlBuilder.getPlayerMatches('playerId', { gameTypeId: 'rating' });\nconst rankingUrl = urlBuilder.getOverallRanking({ limit: 10 });\n\n// Use with axios or other HTTP clients\nconst response = await axios.get(playerUrl);\n```\n\n### Batch URL Generation\n\n```typescript\nconst urls = urlBuilder.batch([\n  builder =\u003e builder.searchCharacter('player1'),\n  builder =\u003e builder.searchCharacter('player2'),\n  builder =\u003e builder.searchAuction({ itemName: 'weapon' })\n]);\n\n// Process multiple URLs concurrently\nconst promises = urls.map(url =\u003e fetch(url));\nconst responses = await Promise.all(promises);\n```\n\n## Supported HTTP Clients\n\nThe SDK **uses Node.js built-in fetch by default (no dependencies)** and supports multiple HTTP client libraries through the adapter pattern:\n\n### FetchAdapter (Default)\n**Uses Node.js 18+ built-in fetch with no additional dependencies.**\n\n```typescript\nimport { NeopleDFClient, FetchAdapter } from 'neople-sdk-js';\n\n// Default adapter (uses built-in fetch, no dependencies)\nconst client = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);\n\n// Or explicitly use FetchAdapter\nconst clientWithFetch = new NeopleDFClient(\n  process.env.NEOPLE_DF_API_KEY,\n  new FetchAdapter()\n);\n\n// API call example - internally uses Node.js built-in fetch\nconst result = await client.searchCharacter('character_name');\nconsole.log(result);\n```\n\n### AxiosAdapter\nUses axios library\n\n```typescript\nimport { NeopleDFClient, AxiosAdapter } from 'neople-sdk-js';\nimport axios from 'axios';\n\nconst client = new NeopleDFClient(\n  process.env.NEOPLE_DF_API_KEY,\n  new AxiosAdapter(axios.create({ \n    timeout: 5000,\n    retry: 3 \n  }))\n);\n\n// API call example\nconst result = await client.searchCharacter('character_name');\nconsole.log(result);\n```\n\n### NodeFetchAdapter\nFor older Node.js versions (uses node-fetch library)\n\n```typescript\nimport { NeopleDFClient, NodeFetchAdapter } from 'neople-sdk-js';\nimport fetch from 'node-fetch';\n\nconst client = new NeopleDFClient(\n  process.env.NEOPLE_DF_API_KEY,\n  new NodeFetchAdapter(fetch)\n);\n\n// API call example\nconst result = await client.searchCharacter('character_name');\nconsole.log(result);\n```\n\n### GotAdapter\nUses Got library (Node.js optimized)\n\n```typescript\nimport { NeopleDFClient, GotAdapter } from 'neople-sdk-js';\nimport got from 'got';\n\nconst client = new NeopleDFClient(\n  process.env.NEOPLE_DF_API_KEY,\n  new GotAdapter(got.extend({\n    timeout: { request: 5000 },\n    retry: { limit: 2 }\n  }))\n);\n\n// API call example\nconst result = await client.searchCharacter('character_name');\nconsole.log(result);\n```\n\n## Error Handling\n\nAll HTTP adapters unify errors from various libraries into `NeopleApiError`.\n\n```typescript\nimport { NeopleDFClient, NeopleApiError } from 'neople-sdk-js';\n\nconst client = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);\n\ntry {\n  const result = await client.searchCharacter('nonexistent-character');\n} catch (error) {\n  if (error instanceof NeopleApiError) {\n    console.log(`API Error: ${error.status} - ${error.message}`);\n    // error.response contains original response data\n  } else {\n    console.log('Network Error:', error.message);\n  }\n}\n```\n\n### Unified Error Handling Across Adapters\n\nEach HTTP library's different error formats are handled consistently:\n\n```typescript\n// Using FetchAdapter\nconst fetchClient = new NeopleDFClient(apiKey, new FetchAdapter());\n\n// Using AxiosAdapter  \nconst axiosClient = new NeopleDFClient(apiKey, new AxiosAdapter(axios.create()));\n\n// Using GotAdapter\nconst gotClient = new NeopleDFClient(apiKey, new GotAdapter(got.extend()));\n\n// Identical error handling for all clients\n[fetchClient, axiosClient, gotClient].forEach(async (client) =\u003e {\n  try {\n    await client.searchCharacter('invalid-request');\n  } catch (error) {\n    if (error instanceof NeopleApiError) {\n      // Always same error type regardless of adapter\n      console.log(`Status Code: ${error.status}`);\n      console.log(`Error Message: ${error.message}`);\n    }\n  }\n});\n```\n\n**Main Error Types:**\n- **HTTP Errors** (`status \u003e 0`): API server response errors (404, 500, etc.)\n- **Network Errors** (`status = 0`): Network connection issues\n\n## License\n\nMIT\n\n## Contributing\n\nBug reports, feature requests, and Pull Requests are welcome!\n\n## References\n\n- [Neople Open API Developer Site](https://developers.neople.co.kr/) - Official Neople API developer portal\n- [Documentation](https://crowrish.github.io/neople-sdk-js-docs/) - Complete SDK documentation\n- [npm Package](https://www.npmjs.com/package/neople-sdk-js) - neople-sdk-js npm package page\n- [neople-openapi-types](https://github.com/leegeunhyeok/neople-openapi-types) - Neople Open API type definitions package","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowrish%2Fneople-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrowrish%2Fneople-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrowrish%2Fneople-sdk-js/lists"}