kms-open-api

Nexon MapleStory Open API TypeScript 클라이언트

설치

# npm
npm install kms-open-api

# pnpm
pnpm add kms-open-api

# yarn
yarn add kms-open-api

빠른 시작

import { MapleStoryClient } from "kms-open-api";

const client = new MapleStoryClient({
  apiKey: "your-api-key",
});

// 캐릭터 OCID 조회
const { ocid } = await client.character.getId({
  characterName: "캐릭터명",
});

// 캐릭터 기본 정보 조회
const basic = await client.character.getBasic({ ocid });
console.log(basic.character_name);    // 캐릭터명
console.log(basic.character_level);   // 레벨
console.log(basic.character_class);   // 직업

// 특정 날짜 기준 조회 (Date 객체 또는 문자열)
const statYesterday = await client.character.getStat({
  ocid,
  date: new Date("2024-12-24"),
});

API 목록

Character (캐릭터)

client.character.getId({ characterName })     // OCID 조회
client.character.getList()                    // 계정 캐릭터 목록
client.character.getBasic({ ocid, date? })    // 기본 정보
client.character.getStat({ ocid, date? })     // 종합 능력치
client.character.getHyperStat({ ocid, date? }) // 하이퍼스탯
client.character.getAbility({ ocid, date? })  // 어빌리티
client.character.getItemEquipment({ ocid, date? })  // 장비
client.character.getSkill({ ocid, skillGrade, date? })  // 스킬
client.character.getSymbolEquipment({ ocid, date? })  // 심볼
client.character.getVmatrix({ ocid, date? })  // V매트릭스
client.character.getHexamatrix({ ocid, date? })  // HEXA 코어
// ... 외 다수

Guild (길드)

client.guild.getId({ guildName, worldName })  // 길드 OGID 조회
client.guild.getBasic({ ogid, date? })        // 길드 기본 정보

Union (유니온)

client.union.getUnion({ ocid, date? })        // 유니온 정보
client.union.getUnionRaider({ ocid, date? })  // 유니온 공격대
client.union.getUnionArtifact({ ocid, date? }) // 아티팩트
client.union.getUnionChampion({ ocid, date? }) // 챔피언

Ranking (랭킹)

client.ranking.getOverall({ date, worldName?, ... })  // 종합 랭킹
client.ranking.getUnion({ date, worldName?, ... })    // 유니온 랭킹
client.ranking.getGuild({ date, rankingType, ... })   // 길드 랭킹
client.ranking.getDojang({ date, difficulty, ... })   // 무릉도장 랭킹
client.ranking.getTheseed({ date, worldName?, ... })  // 더시드 랭킹
client.ranking.getAchievement({ date, ... })          // 업적 랭킹

History (확률 정보)

client.history.getStarforce({ count, date? })   // 스타포스 내역
client.history.getCube({ count, date? })        // 큐브 내역
client.history.getPotential({ count, date? })   // 잠재능력 재설정 내역

Notice (공지)

client.notice.getNotice()           // 공지사항 목록
client.notice.getNoticeDetail({ noticeId })  // 공지사항 상세
client.notice.getUpdateNotice()     // 업데이트 공지
client.notice.getEventNotice()      // 이벤트 공지
client.notice.getCashshopNotice()   // 캐시샵 공지

에러 핸들링

import { MapleStoryClient, MapleApiError, MapleNetworkError } from "kms-open-api";

try {
  const basic = await client.character.getBasic({ ocid });
} catch (error) {
  if (error instanceof MapleApiError) {
    console.error(`API 에러: ${error.code} - ${error.message}`);
    console.error(`HTTP 상태: ${error.httpStatus}`);

    if (error.isRateLimitError()) {
      // Rate limit 에러 (429)
      console.log(`재시도까지: ${error.retryAfter}초`);
    } else if (error.isAuthError()) {
      // 인증 에러 (403)
      console.log("API 키를 확인하세요");
    }
  } else if (error instanceof MapleNetworkError) {
    console.error("네트워크 에러:", error.message);
    if (error.isTimeout) {
      console.log("요청 시간 초과");
    }
  }
}

타입 지원

모든 요청/응답에 대한 TypeScript 타입이 제공됩니다.

import type {
  CharacterBasicResponse,
  CharacterStatResponse,
  GetCharacterIdParams,
  RankingOverallResponse,
} from "kms-open-api";

API 키 발급

1. Nexon Open API 접속
2. 로그인 후 애플리케이션 등록
3. MapleStory API 선택
4. 발급받은 API 키 사용

Rate Limits

| 환경 | 초당 요청 | 일일 요청 | |------|----------|----------| | Development | 5 req/sec | 1,000 req/day | | Production | 500 req/sec | 20,000,000 req/day |

라이선스

MIT

프로젝트 구조

src/
├── client.ts      # MapleStoryClient 메인 클래스
├── api/           # 카테고리별 API 클래스
├── types/         # 자동 생성된 타입 정의
└── errors.ts      # 에러 클래스

개발 환경 설정

pnpm install
pnpm build
pnpm test

코드 생성 파이프라인

src/ 코드는 JSON 스키마에서 자동 생성됩니다. 직접 수정하지 마세요.

# API 문서 크롤링 → JSON 스키마 생성
pnpm crawl --detailed

# JSON 스키마 → TypeScript 코드 생성
pnpm generate

크롤러 CLI 옵션

| 옵션 | 설명 | |------|------| | --category, -c | 크롤링할 카테고리 (복수 가능) | | --detailed, -d | 상세 모드 | | --output, -o | 출력 디렉토리 | | --no-headless | 브라우저 창 표시 | | --dry-run | 시뮬레이션 모드 |

지원 카테고리

| 카테고리 | ID | 설명 | |----------|----|----| | character | 14 | 캐릭터 정보 | | union | 15 | 유니온 정보 | | guild | 16 | 길드 정보 | | history | 17 | 확률 정보 | | ranking | 18 | 랭킹 정보 | | notice | 24 | 공지 정보 |