nexon-open-api

Type-safe Nexon Open API & Neople API SDK for TypeScript/JavaScript

Nexon Open API와 Neople API를 TypeScript로 감싼 SDK입니다. 외부 의존성 없이 네이티브 fetch만 사용하며, CJS/ESM 듀얼 출력을 지원합니다.

설치

npm install nexon-open-api
# or
yarn add nexon-open-api
# or
pnpm add nexon-open-api

빠른 시작

Nexon Open API (메이플스토리, FC Online 등)

import { NexonClient } from 'nexon-open-api';

const client = new NexonClient({ apiKey: 'YOUR_NEXON_API_KEY' });

// 메이플스토리
const ocid = await client.maplestory.getOcid('캐릭터명');
const basic = await client.maplestory.character.getBasic({ ocid });
console.log(`${basic.character_name} Lv.${basic.character_level}`);

// FC Online
const ouid = await client.fcOnline.getOuid('닉네임');
const user = await client.fcOnline.getBasic(ouid);
console.log(`${user.nickname} (Lv.${user.level})`);

Neople API (던전앤파이터, 사이퍼즈)

던전앤파이터와 사이퍼즈는 Nexon Open API가 아닌 Neople Open API를 사용합니다. API 키도 별도로 발급받아야 합니다.

import { NeoPleClient } from 'nexon-open-api';

const client = new NeoPleClient({ apiKey: 'YOUR_NEOPLE_API_KEY' });

// 던전앤파이터
const servers = await client.dnf.getServers();

API 키 발급

| API | 발급처 | 비고 | |---|---|---| | Nexon Open API | openapi.nexon.com | 메이플스토리, FC Online 등 | | Neople Open API | developers.neople.co.kr | 던전앤파이터, 사이퍼즈 |

두 API는 서로 독립된 시스템이므로 API 키가 호환되지 않습니다. 던파/사이퍼즈를 사용하려면 Neople 개발자센터에서 별도로 앱을 등록하고 API 키를 발급받으세요.

주요 특징

• Type-safe — 모든 API 응답에 대한 완전한 TypeScript 타입 정의
• Branded Types — OCID, OUID, GuildId, NexonDate 브랜드 타입으로 컴파일 타임 안전성
• 자동 재시도 — 429 (Rate Limit) / 503 응답 시 지수 백오프 자동 재시도
• 에러 분류 — RateLimitError, AuthError 등 instanceof로 에러 분기 (Nexon/Neople 공용)
• 외부 의존성 0 — Node.js 18+ 네이티브 fetch 사용
• 멀티 API 지원 — NexonClient (Nexon Open API) + NeoPleClient (Neople API) 분리 설계

지원 게임

Nexon Open API (NexonClient)

Neople API (NeoPleClient)

에러 처리

SDK는 API 에러 코드를 구체적인 에러 클래스로 분류합니다. Nexon Open API와 Neople API 모두 동일한 에러 클래스를 공유하며, 각 API의 에러 코드 체계에 맞춰 자동 분류됩니다.

import {
  ApiError,
  RateLimitError,
  AuthError,
  NotFoundError,
  BadRequestError,
  DataNotReadyError,
  ServerError,
} from 'nexon-open-api';

try {
  const basic = await client.maplestory.character.getBasic({ ocid });
} catch (err) {
  if (err instanceof RateLimitError) {
    // 요청 한도 초과 (SDK가 자동으로 3회 재시도 후 throw)
    console.log(`재시도 대기: ${err.retryAfterMs}ms`);
  }
  if (err instanceof AuthError) {
    // API 키 오류 또는 권한 없음
  }
  if (err instanceof NotFoundError) {
    // 캐릭터/길드를 찾을 수 없음
  }
  if (err instanceof DataNotReadyError) {
    // 해당 날짜 데이터 미준비 (매일 오전 1시 KST 이후 갱신)
  }
  if (err instanceof ApiError) {
    // 모든 SDK 에러의 기본 클래스
    console.log(err.code, err.message);
  }
}

하위 호환성: 기존 NexonRateLimitError, NexonAuthError 등의 이름도 deprecated alias로 계속 사용 가능합니다.

에러 클래스 계층

| 에러 클래스 | 설명 | Nexon 코드 | Neople 코드 | |---|---|---|---| | ApiError | 모든 SDK 에러의 기본 클래스 | — | — | | RateLimitError | 요청 한도 초과 | OPENAPI00007 | API002, API008 | | AuthError | API 키 오류 / 권한 없음 | OPENAPI00002, 00005 | API000, API003~API005 | | NotFoundError | 리소스를 찾을 수 없음 | OPENAPI00003 | DNF001~DNF007, CY001~CY007 | | BadRequestError | 잘못된 요청 파라미터 | OPENAPI00004, 00006 | API901~API999, DNF008~DNF010 | | DataNotReadyError | 데이터 미준비 | OPENAPI00009, 00010 | — | | ServerError | API 서버 오류 / 점검 | OPENAPI00001, 00008, 00011 | API001, DNF900, CY900 |

설정 옵션

NexonClient와 NeoPleClient 모두 동일한 설정을 지원합니다.

const client = new NexonClient({
  apiKey: 'YOUR_API_KEY',
  timeoutMs: 10_000, // 요청 타임아웃 (기본: 10초)
  maxRetries: 3, // 429/503 재시도 횟수 (기본: 3)
  retryBaseDelayMs: 500, // 재시도 기본 대기시간 (기본: 500ms)
  debug: true, // 콘솔 디버그 로그 활성화
});

커스텀 로거

const client = new NexonClient({
  apiKey: 'YOUR_API_KEY',
  logger: {
    onRequest: (info) => console.log(`→ ${info.method} ${info.url}`),
    onResponse: (info) => console.log(`← ${info.status} (${info.durationMs}ms)`),
    onRetry: (info) => console.warn(`↩ retry #${info.attempt} after ${info.waitMs}ms`),
  },
});

Sub-path Import

특정 게임 코드만 번들에 포함하고 싶다면 sub-path import를 사용하세요.

import { MapleStoryClient } from 'nexon-open-api/maplestory';
import { MapleStoryMClient } from 'nexon-open-api/maplestory-m';
import { MapleStorySEAClient } from 'nexon-open-api/maplestory-sea';
import { FcOnlineClient } from 'nexon-open-api/fconline';

상세 문서

| 게임 | 문서 | 엔드포인트 | | ------------- | -------------------------------------- | ----------------------------------------------- | | 메이플스토리 | API 레퍼런스 | 캐릭터, 유니온, 길드, 랭킹, 확률/이력, 공지사항 | | 메이플스토리M | API 레퍼런스 | 캐릭터, 유니온, 길드, 랭킹, 공지사항 | | MapleStorySEA | API 레퍼런스 | 캐릭터, 유니온, 길드 | | FC Online | API 레퍼런스 | 계정 정보, 매치, 랭커, 메타데이터, 이미지 URL |

요구사항

• Node.js 18+
• TypeScript 5.0+ (타입 사용 시)

면책 조항

이 프로젝트는 넥슨(NEXON Korea Corporation) 및 네오플(Neople Inc.)이 제휴, 승인, 후원하지 않는 비공식 서드파티 라이브러리입니다.

• 이 SDK에서 사용하는 모든 게임명, 로고 및 관련 상표의 권리는 넥슨에 있습니다 (이용약관 제6조 ①).
• 이 SDK는 NEXON Open API 및 Neople Open API를 통해 데이터를 제공받습니다.
• API 사용 시 각 플랫폼의 이용약관을 준수해 주세요.

라이선스

이 SDK의 소스 코드는 MIT 라이선스를 따릅니다. 단, API를 통해 제공되는 데이터의 저작권은 넥슨 및 네오플에 있으며, 데이터의 무단 복제/재배포/영리적 이용은 이용약관에 의해 제한됩니다.