neople-sdk-js
Advanced tools
네오플 오픈 API를 위한 TypeScript SDK
이 SDK는 네오플 오픈 API를 위한 TypeScript/JavaScript 클라이언트입니다. 네오플 오픈 API 서비스 이용약관을 반드시 준수해야 합니다.
참고: 이 문서는 2025년 8월 19일 기준으로 작성되었습니다.
https://crowrish.github.io/neople-sdk-js-docs
npm install neople-sdk-js
import { NeopleDFClient } from 'neople-sdk-js';
const dfClient = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);
// 캐릭터 검색
const characters = await dfClient.searchCharacter('홍길동');
// 캐릭터 정보 조회
const character = await dfClient.getCharacter('cain', 'characterId');
// 캐릭터 장비 정보 조회
const equipment = await dfClient.getCharacterEquipment('cain', 'characterId');
import { NeopleCyphersClient } from 'neople-sdk-js';
const cyphersClient = new NeopleCyphersClient(process.env.NEOPLE_CYPHERS_API_KEY);
// 플레이어 검색
const players = await cyphersClient.searchPlayer('플레이어닉네임');
// 플레이어 정보 조회
const playerInfo = await cyphersClient.getPlayerInfo('playerId');
// 플레이어 매치 기록 조회
const matches = await cyphersClient.getPlayerMatches('playerId', { gameTypeId: 'rating' });
getServers() - 서버 목록 조회getJobs() - 직업 목록 조회searchCharacter() - 캐릭터 검색getCharacter() - 캐릭터 기본 정보 조회getCharacterStatus() - 캐릭터 능력치 정보 조회getCharacterEquipment() - 캐릭터 장비 정보 조회getCharacterAvatar() - 캐릭터 아바타 정보 조회getCharacterCreature() - 캐릭터 크리처 정보 조회getCharacterFlag() - 캐릭터 휘장 정보 조회getCharacterTalisman() - 캐릭터 탈리스만 정보 조회getCharacterSkill() - 캐릭터 스킬 정보 조회getCharacterBuff() - 캐릭터 버프 정보 조회getCharacterTimeline() - 캐릭터 타임라인 조회getCharactersByFame() - 명성별 캐릭터 검색getCharacterSkillStyle() - 캐릭터 스킬 스타일 조회getCharacterBuffSkillEquipment() - 버프 스킬 강화 장비 조회getCharacterBuffSkillAvatar() - 버프 스킬 강화 아바타 조회getCharacterBuffSkillCreature() - 버프 스킬 강화 크리처 조회getSkillsByJob() - 직업별 스킬 목록 조회getSkillDetail() - 스킬 상세 정보 조회getMultiSkills() - 다중 스킬 조회searchItems() - 아이템 검색getItem() - 아이템 상세 정보 조회getSetItem() - 세트 아이템 정보 조회searchSetItems() - 세트 아이템 검색getMultiItems() - 다중 아이템 조회getMultiSetItems() - 다중 세트 아이템 조회getItemShop() - 아이템 상점 정보 조회searchAuction() - 경매장 검색getAuctionSold() - 경매장 판매 완료 내역 조회getAuctionItem() - 경매 아이템 상세 정보 조회getAvatarMarketSale() - 아바타 마켓 판매 상품 조회getAvatarMarketSold() - 아바타 마켓 판매 완료 상품 조회getAvatarMarketItem() - 아바타 마켓 특정 상품 조회getAvatarMarketSoldItem() - 아바타 마켓 판매 완료 상품 상세 조회getAvatarMarketHashtags() - 아바타 마켓 해시태그 목록 조회getItemHashtags() - 아이템 해시태그 목록 조회searchPlayer() - 플레이어 검색getPlayerInfo() - 플레이어 정보 조회getPlayerMatches() - 플레이어 매치 기록 조회getMatchDetail() - 매치 상세 정보 조회getOverallRanking() - 전체 랭킹 조회getCharacterRanking() - 캐릭터별 랭킹 조회getTsjRanking() - 투신전 랭킹 조회searchCyphersItems() - 아이템 검색getCyphersItemDetail() - 아이템 상세 정보 조회getCyphersMultiItems() - 다중 아이템 조회getCyphersInfo() - 사이퍼 정보 조회던전앤파이터와 사이퍼즈는 각각 다른 API 키를 사용합니다:
# .env 파일
NEOPLE_DF_API_KEY=your_dungeon_fighter_api_key
NEOPLE_CYPHERS_API_KEY=your_cyphers_api_key
import express from 'express';
import { NeopleDFClient } from 'neople-sdk-js';
const app = express();
const dfClient = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);
app.get('/api/character/:name', async (req, res) => {
try {
const result = await dfClient.searchCharacter(req.params.name);
res.json(result);
} catch (error) {
res.status(500).json({ error: error.message });
}
});
// app/api/character/[name]/route.ts
import { NeopleDFClient } from 'neople-sdk-js';
const dfClient = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);
export async function GET(
request: Request,
{ params }: { params: { name: string } }
) {
try {
const result = await dfClient.searchCharacter(params.name);
return Response.json(result);
} catch (error) {
return Response.json({ error: error.message }, { status: 500 });
}
}
HTTP 클라이언트를 직접 제어하거나, URL만 필요한 경우를 위한 전용 클래스를 제공합니다.
import { NeopleDFUrlBuilder } from 'neople-sdk-js';
const urlBuilder = new NeopleDFUrlBuilder(process.env.NEOPLE_DF_API_KEY);
// URL 생성
const characterUrl = urlBuilder.searchCharacter('홍길동', 'cain');
const equipmentUrl = urlBuilder.getCharacterEquipment('cain', 'characterId');
const auctionUrl = urlBuilder.searchAuction({ itemName: '해방무기', limit: 10 });
// 원하는 HTTP 클라이언트로 직접 호출
const response = await fetch(characterUrl);
const data = await response.json();
import { NeopleCyphersUrlBuilder } from 'neople-sdk-js';
const urlBuilder = new NeopleCyphersUrlBuilder(process.env.NEOPLE_CYPHERS_API_KEY);
// URL 생성
const playerUrl = urlBuilder.searchPlayer('플레이어닉네임');
const matchUrl = urlBuilder.getPlayerMatches('playerId', { gameTypeId: 'rating' });
const rankingUrl = urlBuilder.getOverallRanking({ limit: 10 });
// axios나 다른 HTTP 클라이언트 사용
const response = await axios.get(playerUrl);
const urls = urlBuilder.batch([
builder => builder.searchCharacter('플레이어1'),
builder => builder.searchCharacter('플레이어2'),
builder => builder.searchAuction({ itemName: '무기' })
]);
// 여러 URL을 동시에 처리
const promises = urls.map(url => fetch(url));
const responses = await Promise.all(promises);
SDK는 기본적으로 Node.js 내장 fetch를 사용하며, 어댑터 패턴을 통해 다양한 HTTP 클라이언트 라이브러리를 지원합니다:
별도 의존성 없이 Node.js 18+ 내장 fetch를 사용합니다.
import { NeopleDFClient, FetchAdapter } from 'neople-sdk-js';
// 기본 어댑터 (내장 fetch 사용, 의존성 없음)
const client = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);
// 또는 명시적으로 FetchAdapter 사용
const clientWithFetch = new NeopleDFClient(
process.env.NEOPLE_DF_API_KEY,
new FetchAdapter()
);
// API 호출 예제 - 내부적으로 Node.js 내장 fetch 사용
const result = await client.searchCharacter('홍길동');
console.log(result);
axios 라이브러리 사용
import { NeopleDFClient, AxiosAdapter } from 'neople-sdk-js';
import axios from 'axios';
const client = new NeopleDFClient(
process.env.NEOPLE_DF_API_KEY,
new AxiosAdapter(axios.create({
timeout: 5000,
retry: 3
}))
);
// API 호출 예제
const result = await client.searchCharacter('홍길동');
console.log(result);
구버전 Node.js 지원용 (node-fetch 라이브러리 사용)
import { NeopleDFClient, NodeFetchAdapter } from 'neople-sdk-js';
import fetch from 'node-fetch';
const client = new NeopleDFClient(
process.env.NEOPLE_DF_API_KEY,
new NodeFetchAdapter(fetch)
);
// API 호출 예제
const result = await client.searchCharacter('홍길동');
console.log(result);
Got 라이브러리 사용 (Node.js 최적화)
import { NeopleDFClient, GotAdapter } from 'neople-sdk-js';
import got from 'got';
const client = new NeopleDFClient(
process.env.NEOPLE_DF_API_KEY,
new GotAdapter(got.extend({
timeout: { request: 5000 },
retry: { limit: 2 }
}))
);
// API 호출 예제
const result = await client.searchCharacter('홍길동');
console.log(result);
모든 HTTP 어댑터는 다양한 라이브러리의 에러를 NeopleApiError로 통일합니다.
import { NeopleDFClient, NeopleApiError } from 'neople-sdk-js';
const client = new NeopleDFClient(process.env.NEOPLE_DF_API_KEY);
try {
const result = await client.searchCharacter('존재하지않는캐릭터');
} catch (error) {
if (error instanceof NeopleApiError) {
console.log(`API 오류: ${error.status} - ${error.message}`);
// error.response에서 원본 응답 데이터 확인 가능
} else {
console.log('네트워크 오류:', error.message);
}
}
각 HTTP 라이브러리마다 다른 에러 형태를 동일하게 처리합니다:
// FetchAdapter 사용 시
const fetchClient = new NeopleDFClient(apiKey, new FetchAdapter());
// AxiosAdapter 사용 시
const axiosClient = new NeopleDFClient(apiKey, new AxiosAdapter(axios.create()));
// GotAdapter 사용 시
const gotClient = new NeopleDFClient(apiKey, new GotAdapter(got.extend()));
// 모든 클라이언트에서 동일한 에러 처리
[fetchClient, axiosClient, gotClient].forEach(async (client) => {
try {
await client.searchCharacter('잘못된요청');
} catch (error) {
if (error instanceof NeopleApiError) {
// 어댑터와 관계없이 항상 동일한 에러 타입
console.log(`상태 코드: ${error.status}`);
console.log(`에러 메시지: ${error.message}`);
}
}
});
주요 에러 타입:
status > 0): API 서버 응답 에러 (404, 500 등)status = 0): 네트워크 연결 문제MIT
버그 리포트, 기능 요청, Pull Request를 환영합니다!
FAQs
TypeScript SDK for Neople Open API
We found that neople-sdk-js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.