MapleHands

MapleStory(PC)와 MapleStory M의 캐릭터, 길드, 유니온 데이터를 Nexon Open API로부터 조회하는 Node.js API 서버입니다.

Features

• PC 메이플스토리 캐릭터 종합 정보 조회 (스탯, 장비, 스킬, 유니온 등 21개 항목)
• 메이플스토리 M 캐릭터 정보 조회 (21개 항목)
• MapleStorySEA / MapleStoryTW 캐릭터 정보 조회
• 길드 정보 및 전체 멤버 데이터 일괄 조회
• 이미지 URL을 base64로 변환하는 프록시
• 개별 API 실패 시에도 나머지 데이터를 반환하는 부분 실패 내성

Prerequisites

• Node.js v20+
• Nexon Open API 키 (PC, M, SEA, TW 각각)

Installation

git clone https://github.com/asdfghjkkl11/MapleHands.git
cd MapleHands
npm install

Configuration

프로젝트 루트에 key.js 파일을 생성하고 API 키를 설정합니다:

export const mapleApikey = "YOUR_MAPLESTORY_API_KEY";
export const mapleMApikey = "YOUR_MAPLESTORY_M_API_KEY";
export const mapleSEAApikey = "YOUR_MAPLESTORY_SEA_API_KEY";
export const mapleTWApikey = "YOUR_MAPLESTORY_TW_API_KEY";

key.js는 .gitignore에 포함되어 있습니다.

Usage

# 개발 서버 (nodemon, 파일 변경 시 자동 재시작)
npm run dev

# 운영 서버 (PM2, ecosystem.config.cjs 필요)
npm start

# 테스트 실행
npm test

서버는 http://localhost:5678에서 실행됩니다.

API Reference

Health Check

GET /

Response:

{ "hello": "world" }

---

PC 캐릭터 정보 조회

POST /maple/getInfo

Param	Type	Required	Description
ID	string	O	캐릭터명

Response: 21개 항목을 포함하는 JSON 객체 (Promise.allSettled 형태)

{
  "basic": { ... },
  "stat": { ... },
  "item-equipment": { ... },
  "union": { ... },
  ...
}

반환 키: basic, popularity, stat, hyper-stat, propensity, ability, item-equipment, cashitem-equipment, symbol-equipment, set-effect, beauty-equipment, android-equipment, pet-equipment, link-skill, vmatrix, hexamatrix, hexamatrix-stat, dojang, union, union-raider, union-artifact

---

메이플M 캐릭터 정보 조회

POST /maple/mobile/getInfo

Param	Type	Required	Description
ID	string	O	캐릭터명
server	string	O	월드명

Response: PC와 동일한 21개 항목

---

MapleStorySEA 캐릭터 정보 조회

POST /maple/sea/getInfo

Param	Type	Required	Description
ID	string	O	캐릭터명

Response: PC와 동일한 21개 항목

---

MapleStoryTW 캐릭터 정보 조회

POST /maple/tw/getInfo

Param	Type	Required	Description
ID	string	O	캐릭터명

Response: PC와 동일한 21개 항목

---

길드 정보 조회

POST /maple/getGuildInfo

Param	Type	Required	Description
guild	string	O	길드명
server	string	O	월드명

Response:

{
  "guild": { ... },
  "member_list": {
    "캐릭터명": {
      "basic": { ... },
      "stat": { ... },
      "dojang": { ... },
      "union": { ... }
    }
  }
}

---

이미지 프록시

POST /maple/getUrl

Param	Type	Required	Description
url	string	O	이미지 URL

Response: data:image/png;base64,... 형식의 문자열

Project Structure

MapleHands/
├── server.js              # 서버 진입점 (config + listen)
├── buildApp.js            # Fastify 앱 팩토리 (테스트/운영 공용)
├── routes/
│   └── maple.js           # API 라우트 (PC, Mobile, SEA, TW, 길드, 이미지)
├── js/
│   ├── config.js          # 서버 설정 (포트, API URL)
│   ├── mapleApi.js        # Nexon API 클라이언트 (fetchParallel)
│   ├── common.js          # 유틸리티 함수
│   ├── common.test.js     # 유틸리티 테스트
│   └── mapleApi.test.js   # API 클라이언트 테스트
├── tests/                 # 라우트 통합 + 스모크 테스트
├── scripts/               # 개발용 유틸리티 스크립트
├── key.js                 # API 키 (gitignored)
└── package.json

Tech Stack

• Fastify v5
• Axios
• Vitest (testing)
• PM2 (production)