kms-open-api 1.0.0

package/dist/index.mjs

@@ -0,0 +1,765 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/types/common.ts
+function formatDate(input) {
+  if (typeof input === "string") {
+    return input;
+  }
+  return input.toISOString().split("T")[0];
+}
+function getYesterdayDate() {
+  const yesterday = /* @__PURE__ */ new Date();
+  yesterday.setDate(yesterday.getDate() - 1);
+  return formatDate(yesterday);
+}
+
+// src/api/base.ts
+import ky from "ky";
+
+// src/errors.ts
+var MapleApiError = class _MapleApiError extends Error {
+  constructor(options) {
+    super(options.message);
+    /** Error code from Nexon API (e.g., "OPENAPI00001") */
+    __publicField(this, "code");
+    /** HTTP status code (400, 403, 429, 500, etc.) */
+    __publicField(this, "httpStatus");
+    /** Original error for debugging purposes */
+    __publicField(this, "originalError");
+    /** Retry-After header value in seconds (for rate limit errors) */
+    __publicField(this, "retryAfter");
+    this.name = options.name;
+    this.code = options.code;
+    this.httpStatus = options.httpStatus;
+    this.originalError = options.originalError;
+    this.retryAfter = options.retryAfter;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MapleApiError);
+    }
+  }
+  /**
+   * Check if this is an authentication error (403)
+   */
+  isAuthError() {
+    return this.httpStatus === 403;
+  }
+  /**
+   * Check if this is a rate limit error (429)
+   */
+  isRateLimitError() {
+    return this.httpStatus === 429;
+  }
+  /**
+   * Check if this is a bad request error (400)
+   */
+  isBadRequestError() {
+    return this.httpStatus === 400;
+  }
+  /**
+   * Check if this is a server error (5xx)
+   */
+  isServerError() {
+    return this.httpStatus >= 500 && this.httpStatus < 600;
+  }
+  /**
+   * Creates a string representation of the error
+   */
+  toString() {
+    return `MapleApiError: [${this.code}] ${this.message} (HTTP ${this.httpStatus})`;
+  }
+};
+var MapleNetworkError = class _MapleNetworkError extends Error {
+  constructor(options) {
+    super(options.message);
+    /** Original error for debugging */
+    __publicField(this, "originalError");
+    /** Whether this is a timeout error */
+    __publicField(this, "isTimeout");
+    this.name = "MapleNetworkError";
+    this.originalError = options.originalError;
+    this.isTimeout = options.isTimeout ?? false;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _MapleNetworkError);
+    }
+  }
+};
+
+// src/api/base.ts
+var BaseApi = class {
+  constructor(apiKey) {
+    __publicField(this, "client");
+    this.client = ky.create({
+      prefixUrl: "https://open.api.nexon.com",
+      headers: {
+        "x-nxopen-api-key": apiKey
+      },
+      hooks: {
+        afterResponse: [
+          async (_request, _options, response) => {
+            if (!response.ok) {
+              await this.handleErrorResponse(response);
+            }
+            return response;
+          }
+        ]
+      }
+    });
+  }
+  /**
+   * Handles error responses and throws appropriate error types
+   */
+  async handleErrorResponse(response) {
+    let errorData = null;
+    try {
+      errorData = await response.json();
+    } catch {
+    }
+    const retryAfter = response.headers.get("Retry-After");
+    throw new MapleApiError({
+      name: errorData?.error?.name ?? "UNKNOWN_ERROR",
+      message: errorData?.error?.message ?? `HTTP ${response.status} Error`,
+      code: errorData?.error?.name ?? "UNKNOWN",
+      httpStatus: response.status,
+      retryAfter: retryAfter ? Number.parseInt(retryAfter, 10) : void 0
+    });
+  }
+  /**
+   * Makes a GET request with proper error handling
+   */
+  async get(endpoint, searchParams, options) {
+    try {
+      const filteredParams = {};
+      if (searchParams) {
+        for (const [key, value] of Object.entries(searchParams)) {
+          if (value !== void 0) {
+            filteredParams[key] = value;
+          }
+        }
+      }
+      const kyOptions = {
+        searchParams: Object.keys(filteredParams).length > 0 ? filteredParams : void 0
+      };
+      if (options?.signal) {
+        kyOptions.signal = options.signal;
+      }
+      const normalizedEndpoint = endpoint.startsWith("/") ? endpoint.slice(1) : endpoint;
+      return await this.client.get(normalizedEndpoint, kyOptions).json();
+    } catch (error) {
+      if (error instanceof MapleApiError) {
+        throw error;
+      }
+      if (error instanceof TypeError && error.message.includes("fetch")) {
+        throw new MapleNetworkError({
+          message: "Network error: Unable to connect to API",
+          originalError: error
+        });
+      }
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw new MapleNetworkError({
+          message: "Request was aborted",
+          originalError: error,
+          isTimeout: true
+        });
+      }
+      throw error;
+    }
+  }
+};
+
+// src/api/character.ts
+var CharacterApi = class extends BaseApi {
+  /**
+   * 캐릭터 목록 조회
+   */
+  async getList(options) {
+    return this.get("/maplestory/v1/character/list", void 0, options);
+  }
+  /**
+   * 업적 정보 조회
+   */
+  async getAchievement(options) {
+    return this.get("/maplestory/v1/user/achievement", void 0, options);
+  }
+  /**
+   * 캐릭터 식별자(ocid) 조회
+   */
+  async getId(params, options) {
+    const searchParams = {};
+    searchParams.character_name = String(params.characterName);
+    return this.get("/maplestory/v1/id", searchParams, options);
+  }
+  /**
+   * 기본 정보 조회
+   */
+  async getBasic(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/basic", searchParams, options);
+  }
+  /**
+   * 인기도 정보 조회
+   */
+  async getPopularity(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/popularity", searchParams, options);
+  }
+  /**
+   * 종합 능력치 정보 조회
+   */
+  async getStat(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/stat", searchParams, options);
+  }
+  /**
+   * 하이퍼스탯 정보 조회
+   */
+  async getHyperstat(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/hyper-stat", searchParams, options);
+  }
+  /**
+   * 성향 정보 조회
+   */
+  async getPropensity(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/propensity", searchParams, options);
+  }
+  /**
+   * 어빌리티 정보 조회
+   */
+  async getAbility(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/ability", searchParams, options);
+  }
+  /**
+   * 장착 장비 정보 조회 (캐시 장비 제외)
+   */
+  async getItemequipment(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/item-equipment", searchParams, options);
+  }
+  /**
+   * 장착 캐시 장비 정보 조회
+   */
+  async getCashitemequipment(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/cashitem-equipment", searchParams, options);
+  }
+  /**
+   * 장착 심볼 정보 조회
+   */
+  async getSymbolequipment(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/symbol-equipment", searchParams, options);
+  }
+  /**
+   * 적용 세트 효과 정보 조회
+   */
+  async getSeteffect(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/set-effect", searchParams, options);
+  }
+  /**
+   * 장착 헤어, 성형, 피부 정보 조회
+   */
+  async getBeautyequipment(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/beauty-equipment", searchParams, options);
+  }
+  /**
+   * 장착 안드로이드 정보 조회
+   */
+  async getAndroidequipment(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/android-equipment", searchParams, options);
+  }
+  /**
+   * 장착 펫 정보 조회
+   */
+  async getPetequipment(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/pet-equipment", searchParams, options);
+  }
+  /**
+   * 스킬 정보 조회
+   */
+  async getSkill(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    searchParams.character_skill_grade = String(params.characterSkillGrade);
+    return this.get("/maplestory/v1/character/skill", searchParams, options);
+  }
+  /**
+   * 장착 링크 스킬 정보 조회
+   */
+  async getLinkskill(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/link-skill", searchParams, options);
+  }
+  /**
+   * V매트릭스 정보 조회
+   */
+  async getVmatrix(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/vmatrix", searchParams, options);
+  }
+  /**
+   * HEXA 코어 정보 조회
+   */
+  async getHexamatrix(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/hexamatrix", searchParams, options);
+  }
+  /**
+   * HEXA 매트릭스 설정 HEXA 스탯 정보 조회
+   */
+  async getHexamatrixstat(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/hexamatrix-stat", searchParams, options);
+  }
+  /**
+   * 무릉도장 최고 기록 정보 조회
+   */
+  async getDojang(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/dojang", searchParams, options);
+  }
+  /**
+   * 기타 능력치 영향 요소 정보 조회
+   */
+  async getOtherstat(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/other-stat", searchParams, options);
+  }
+  /**
+   * 링 익스체인지 스킬 등록 장비 조회
+   */
+  async getRingexchangeskillequipment(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/character/ring-exchange-skill-equipment", searchParams, options);
+  }
+};
+
+// src/api/guild.ts
+var GuildApi = class extends BaseApi {
+  /**
+   * 길드 식별자(oguild_id) 정보 조회
+   */
+  async getId(params, options) {
+    const searchParams = {};
+    searchParams.guild_name = String(params.guildName);
+    searchParams.world_name = String(params.worldName);
+    return this.get("/maplestory/v1/guild/id", searchParams, options);
+  }
+  /**
+   * 기본 정보 조회
+   */
+  async getBasic(params, options) {
+    const searchParams = {};
+    searchParams.oguild_id = String(params.oguildId);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/guild/basic", searchParams, options);
+  }
+};
+
+// src/api/history.ts
+var HistoryApi = class extends BaseApi {
+  /**
+   * 계정 식별자(ouid) 조회 (구 API KEY 사용)
+   */
+  async getLegacyouid(options) {
+    return this.get("/maplestory/legacy/ouid", void 0, options);
+  }
+  /**
+   * 계정 식별자(ouid) 조회
+   */
+  async getOuid(options) {
+    return this.get("/maplestory/v1/ouid", void 0, options);
+  }
+  /**
+   * 스타포스 강화 결과 조회
+   */
+  async getStarforce(params, options) {
+    const searchParams = {};
+    searchParams.count = String(params.count);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    if (params.cursor !== void 0) {
+      searchParams.cursor = String(params.cursor);
+    }
+    return this.get("/maplestory/v1/history/starforce", searchParams, options);
+  }
+  /**
+   * 잠재능력 재설정 이용 결과 조회
+   */
+  async getPotential(params, options) {
+    const searchParams = {};
+    searchParams.count = String(params.count);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    if (params.cursor !== void 0) {
+      searchParams.cursor = String(params.cursor);
+    }
+    return this.get("/maplestory/v1/history/potential", searchParams, options);
+  }
+  /**
+   * 큐브 사용 결과 조회
+   */
+  async getCube(params, options) {
+    const searchParams = {};
+    searchParams.count = String(params.count);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    if (params.cursor !== void 0) {
+      searchParams.cursor = String(params.cursor);
+    }
+    return this.get("/maplestory/v1/history/cube", searchParams, options);
+  }
+};
+
+// src/api/notice.ts
+var NoticeApi = class extends BaseApi {
+  /**
+   * 공지사항 목록 조회
+   */
+  async getNotice(options) {
+    return this.get("/maplestory/v1/notice", void 0, options);
+  }
+  /**
+   * 공지사항 상세 조회
+   */
+  async getDetail(params, options) {
+    const searchParams = {};
+    searchParams.notice_id = String(params.noticeId);
+    return this.get("/maplestory/v1/notice/detail", searchParams, options);
+  }
+  /**
+   * 업데이트 목록 조회
+   */
+  async getNoticeupdate(options) {
+    return this.get("/maplestory/v1/notice-update", void 0, options);
+  }
+  /**
+   * 업데이트 상세 조회
+   */
+  async getUpdatedetail(params, options) {
+    const searchParams = {};
+    searchParams.notice_id = String(params.noticeId);
+    return this.get("/maplestory/v1/notice-update/detail", searchParams, options);
+  }
+  /**
+   * 진행 중 이벤트 목록 조회
+   */
+  async getNoticeevent(options) {
+    return this.get("/maplestory/v1/notice-event", void 0, options);
+  }
+  /**
+   * 진행 중 이벤트 상세 조회
+   */
+  async getEventdetail(params, options) {
+    const searchParams = {};
+    searchParams.notice_id = String(params.noticeId);
+    return this.get("/maplestory/v1/notice-event/detail", searchParams, options);
+  }
+  /**
+   * 캐시샵 공지 목록 조회
+   */
+  async getNoticecashshop(options) {
+    return this.get("/maplestory/v1/notice-cashshop", void 0, options);
+  }
+  /**
+   * 캐시샵 공지 상세 조회
+   */
+  async getCashshopdetail(params, options) {
+    const searchParams = {};
+    searchParams.notice_id = String(params.noticeId);
+    return this.get("/maplestory/v1/notice-cashshop/detail", searchParams, options);
+  }
+};
+
+// src/api/ranking.ts
+var RankingApi = class extends BaseApi {
+  /**
+   * 종합 랭킹 정보 조회
+   */
+  async getOverall(params, options) {
+    const searchParams = {};
+    searchParams.date = formatDate(params.date);
+    if (params.worldName !== void 0) {
+      searchParams.world_name = String(params.worldName);
+    }
+    if (params.worldType !== void 0) {
+      searchParams.world_type = String(params.worldType);
+    }
+    if (params.class !== void 0) {
+      searchParams.class = String(params.class);
+    }
+    if (params.ocid !== void 0) {
+      searchParams.ocid = String(params.ocid);
+    }
+    if (params.page !== void 0) {
+      searchParams.page = String(params.page);
+    }
+    return this.get("/maplestory/v1/ranking/overall", searchParams, options);
+  }
+  /**
+   * 유니온 랭킹 정보 조회
+   */
+  async getUnion(params, options) {
+    const searchParams = {};
+    searchParams.date = formatDate(params.date);
+    if (params.worldName !== void 0) {
+      searchParams.world_name = String(params.worldName);
+    }
+    if (params.ocid !== void 0) {
+      searchParams.ocid = String(params.ocid);
+    }
+    if (params.page !== void 0) {
+      searchParams.page = String(params.page);
+    }
+    return this.get("/maplestory/v1/ranking/union", searchParams, options);
+  }
+  /**
+   * 길드 랭킹 정보 조회
+   */
+  async getGuild(params, options) {
+    const searchParams = {};
+    searchParams.date = formatDate(params.date);
+    if (params.worldName !== void 0) {
+      searchParams.world_name = String(params.worldName);
+    }
+    searchParams.ranking_type = String(params.rankingType);
+    if (params.guildName !== void 0) {
+      searchParams.guild_name = String(params.guildName);
+    }
+    if (params.page !== void 0) {
+      searchParams.page = String(params.page);
+    }
+    return this.get("/maplestory/v1/ranking/guild", searchParams, options);
+  }
+  /**
+   * 무릉도장 랭킹 정보 조회
+   */
+  async getDojang(params, options) {
+    const searchParams = {};
+    searchParams.date = formatDate(params.date);
+    if (params.worldName !== void 0) {
+      searchParams.world_name = String(params.worldName);
+    }
+    searchParams.difficulty = String(params.difficulty);
+    if (params.class !== void 0) {
+      searchParams.class = String(params.class);
+    }
+    if (params.ocid !== void 0) {
+      searchParams.ocid = String(params.ocid);
+    }
+    if (params.page !== void 0) {
+      searchParams.page = String(params.page);
+    }
+    return this.get("/maplestory/v1/ranking/dojang", searchParams, options);
+  }
+  /**
+   * 더 시드 랭킹 정보 조회
+   */
+  async getTheseed(params, options) {
+    const searchParams = {};
+    searchParams.date = formatDate(params.date);
+    if (params.worldName !== void 0) {
+      searchParams.world_name = String(params.worldName);
+    }
+    if (params.ocid !== void 0) {
+      searchParams.ocid = String(params.ocid);
+    }
+    if (params.page !== void 0) {
+      searchParams.page = String(params.page);
+    }
+    return this.get("/maplestory/v1/ranking/theseed", searchParams, options);
+  }
+  /**
+   * 업적 랭킹 정보 조회
+   */
+  async getAchievement(params, options) {
+    const searchParams = {};
+    searchParams.date = formatDate(params.date);
+    if (params.ocid !== void 0) {
+      searchParams.ocid = String(params.ocid);
+    }
+    if (params.page !== void 0) {
+      searchParams.page = String(params.page);
+    }
+    return this.get("/maplestory/v1/ranking/achievement", searchParams, options);
+  }
+};
+
+// src/api/union.ts
+var UnionApi = class extends BaseApi {
+  /**
+   * 유니온 정보 조회
+   */
+  async getUnion(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/user/union", searchParams, options);
+  }
+  /**
+   * 유니온 공격대 정보 조회
+   */
+  async getUnionraider(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/user/union-raider", searchParams, options);
+  }
+  /**
+   * 유니온 아티팩트 정보 조회
+   */
+  async getUnionartifact(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/user/union-artifact", searchParams, options);
+  }
+  /**
+   * 유니온 챔피언 정보 조회
+   */
+  async getUnionchampion(params, options) {
+    const searchParams = {};
+    searchParams.ocid = String(params.ocid);
+    if (params.date !== void 0) {
+      searchParams.date = formatDate(params.date);
+    }
+    return this.get("/maplestory/v1/user/union-champion", searchParams, options);
+  }
+};
+
+// src/client.ts
+var MapleStoryClient = class {
+  constructor(options) {
+    __publicField(this, "character");
+    __publicField(this, "guild");
+    __publicField(this, "history");
+    __publicField(this, "notice");
+    __publicField(this, "ranking");
+    __publicField(this, "union");
+    if (!options.apiKey) {
+      throw new Error("API key is required");
+    }
+    this.character = new CharacterApi(options.apiKey);
+    this.guild = new GuildApi(options.apiKey);
+    this.history = new HistoryApi(options.apiKey);
+    this.notice = new NoticeApi(options.apiKey);
+    this.ranking = new RankingApi(options.apiKey);
+    this.union = new UnionApi(options.apiKey);
+  }
+};
+export {
+  BaseApi,
+  CharacterApi,
+  GuildApi,
+  HistoryApi,
+  MapleApiError,
+  MapleNetworkError,
+  MapleStoryClient,
+  NoticeApi,
+  RankingApi,
+  UnionApi,
+  formatDate,
+  getYesterdayDate
+};
+//# sourceMappingURL=index.mjs.map