maplestory-openapi 3.3.0 → 3.4.1

package/README.md

@@ -3,21 +3,23 @@
 [![npm](https://img.shields.io/npm/v/maplestory-openapi)](https://www.npmjs.com/package/maplestory-openapi)
 [![JS](https://github.com/SpiralMoon/maplestory.openapi/actions/workflows/js_test.yaml/badge.svg)](https://github.com/SpiralMoon/maplestory.openapi/actions/workflows/js_test.yaml)
 
-넥슨의 MapleStory OpenAPI를 Javascript 환경에서 사용할 수 있게 해주는 라이브러리입니다.
+This JavaScript library enables the use of the MapleStory OpenAPI of Nexon.
 
-다른 언어로 작성된 패키지는 [여기](https://github.com/SpiralMoon/maplestory.openapi)에서 확인할 수 있습니다.
+Packages written in other languages can be found [HERE](https://github.com/SpiralMoon/maplestory.openapi).
 
-(English document is [HERE](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/README-en.md))
+English | [한국어](./README-ko.md)
 
 ## Notice
 
->🌏 알림1: 3.0.0 버전부터 여러 서비스 지역에 대한 지원이 추가 되었습니다. 현재 [KMS](https://maplestory.nexon.com/), [MSEA](http://www.maplesea.com/index/)의 데이터를 조회 가능합니다.
+>🌏 Notice 1: Starting from version 3.4.0, support for tms region has been added. You can now retrieve data from [KMS](https://maplestory.nexon.com/), [TMS](https://maplestory.beanfun.com/), [MSEA](http://www.maplesea.com/index/).
 >
->💡 알림2: Version 2.x.x → 3.0.0 업데이트 과정에서 마이그레이션이 필요합니다. [Migration](https://github.com/SpiralMoon/maplestory.openapi/tree/master/js/docs/migration-ko.md) 항목을 참고 해주세요.
+>🌏 Notice 2: Starting from version 3.0.0, support for msea region has been added.
+>
+>💡 Notice 3: Migration is required when updating from version 2.x.x to 3.0.0. Please refer to the documentation for [Migration](https://github.com/SpiralMoon/maplestory.openapi/tree/master/js/docs/migration-en.md).
 
 ## Installation
 
-npm 기반 프로젝트에 아래 정보를 입력하여 패키지를 추가하세요:
+Install the latest version of the JavaScript/TypeScript library in your npm project:
 
 ```bash
 npm install maplestory-openapi
@@ -27,13 +29,13 @@ npm install maplestory-openapi
 
 ### API Key
 
-라이브러리를 사용하기 전에 [Nexon Open API 콘솔](https://openapi.nexon.com/my-application/)에서 애플리케이션을 등록하고 **api key**를 발급 받으세요.
+Before using the library, register your application and obtain an **api key** from the [Nexon Open API Console](https://openapi.nexon.com/my-application/).
 
-애플리케이션은 지역별로 따로 등록해야 합니다. (KMS의 api key로 MSEA의 데이터를 요청할 수 없음)
+Applications must be registered separately for each region. (For example, an API key issued for KMS cannot be used to request data from MSEA.)
 
 ### Region
 
-현재 KMS, MSEA 지역에 대한 데이터 조회를 지원 합니다. 조회를 원하는 지역별로 패키지 경로를 다르게 설정 합니다.
+Currently, this library supports data retrieval from the KMS, TMS, MSEA regions. To access data from a specific region, import the corresponding package path.
 
 ```typescript
 import { MapleStoryApi } from 'maplestory-openapi/kms'; // data from KMS
@@ -41,13 +43,13 @@ import { MapleStoryApi } from 'maplestory-openapi/kms'; // data from KMS
 import { MapleStoryApi } from 'maplestory-openapi/msea'; // data from MSEA
 ```
 
-지역이 달라도 동일한 인터페이스를 상속하기 때문에 API의 사용 경험은 기본적으로 동일 합니다.
+Even though the regions differ, each package inherits the same interface, ensuring a consistent API usage experience across all regions.
 
 ### Supports
 
-1. **TypeScript 지원**: 타입 정의가 포함되어 있으므로 타입스크립트 환경에서도 사용 가능합니다.
+1. **TypeScript Support**: TypeScript is fully supported. Type definitions are included.
 
-2. **CommonJS, ESM 지원**: 이 라이브러리는 CommonJS 와 ESM 방식을 모두 지원합니다.
+2. **CommonJS, ESM Support**: The library supports both CommonJS and ESM usage.
 
 ```javascript
 const { MapleStoryApi } = require('maplestory-openapi/kms'); // CommonJS
@@ -56,7 +58,7 @@ const { MapleStoryApi } = require('maplestory-openapi/kms'); // CommonJS
 import { MapleStoryApi } from 'maplestory-openapi/kms'; // ESM
 ```
 
-3. **TS2307 Cannot find module** 오류 대응: `moduleResolution`이 `node`인 경우 패키지를 못 찾을 수 있습니다. `node16`, `nodenext`, `bundler` 등으로 설정 합니다.
+3. **TS2307 Cannot find module**: it may be due to the `moduleResolution` option being set to `node`. In such cases, update it to `node16`, `nodenext`, or `bundler` as shown below
 
 ```json
 {
@@ -68,7 +70,7 @@ import { MapleStoryApi } from 'maplestory-openapi/kms'; // ESM
 
 ### Sample Code
 
-아래 코드는 KMS 서버에서 닉네임을 바탕으로 특정 캐릭터의 식별자를 조회한 후 캐릭터의 기본 정보를 조회하는 예시입니다.
+Below is an example that retrieves the identifier of a specific character from the KMS server based on the nickname, and then fetches that character’s basic information.
 
 ```javascript
 const { MapleStoryApi } = require('maplestory-openapi/kms');
@@ -79,14 +81,14 @@ const api = new MapleStoryApi(apiKey);
 
 try {
   // run your code
-  
+
   const character = await api.getCharacter('{Your Character Name}');
   const characterBasic = await api.getCharacterBasic(character.ocid);
-  
+
   console.log(characterBasic);
 } catch (e) {
   // exception handling
-  
+
   if (e instanceof MapleStoryApiError) {
     // handle MapleStoryApiError
   } else {
@@ -95,32 +97,41 @@ try {
 }
 ```
 
-더 많은 예시는 아래 링크의 테스트 케이스에서 확인할 수 있습니다.
+You can find more examples in the test cases at the following link.
+
+- [Character Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/characterApi.test.ts)
+- [Union Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/unionApi.test.ts)
+- [Guild Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/guildApi.test.ts)
+- [History Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/historyApi.test.ts)
+- [Ranking Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/rankingApi.test.ts)
+- [Notice Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/noticeApi.test.ts)
+
+### Features
+This library supports all apis published in the MapleStory OpenAPI official docs.
+
+Some features are supported only in specific regions. Please refer to the official documentation for each region for details.
 
-- [캐릭터 정보 조회](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/characterApi.test.ts)
-- [유니온 정보 조회](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/unionApi.test.ts)
-- [길드 정보 조회](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/guildApi.test.ts)
-- [확률 정보 조회](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/historyApi.test.ts)
-- [랭킹 정보 조회](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/rankingApi.test.ts)
-- [공지 정보 조회](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/noticeApi.test.ts)
+- KMS: [https://openapi.nexon.com/game/maplestory](https://openapi.nexon.com/game/maplestory)
+- TMS: [https://openapi.nexon.com/game/maplestorytw](https://openapi.nexon.com/game/maplestorytw)
+- MSEA: [https://openapi.nexon.com/game/maplestorysea](https://openapi.nexon.com/game/maplestorysea)
 
 ### Exception Handling
 
-[MapleStory OpenAPI 가이드](https://openapi.nexon.com/guide/request-api/)에 서술된 에러 사유를 `MapleStoryApiError`를 통해 예외 처리 해야합니다.
+Handle `MapleStoryApiError` to safely make calls, ensuring that specific Status defined in the [MapleStory OpenAPI Guide](https://openapi.nexon.com/guide/request-api) are not encountered.
 
-`MapleStoryApi`는 특정 상태의 예외를 발생시키지 않도록 설계되었으나, 라이브러리를 사용하는 개발자의 실수로 인해 여전히 일부 상태의 예외가 발생할 수 있습니다.
+While `MapleStoryApi` is designed to prevent the occurrence of certain Status, exceptions may arise due to developer mistakes.
 
-따라서 아래 표에 설명된 `MapleStoryApiErrorCode` 목록을 기반으로 `MapleStoryApiError`를 예외 처리하시기 바랍니다.
+Therefore, it's recommended to use `MapleStoryApiError` for exception handling based on the `MapleStoryApiErrorCode` list described in the table below.
 
-| ErrorCode    | Description        |
-|--------------|--------------------|
-| OPENAPI00001 | 서버 내부 오류           |
-| OPENAPI00002 | 권한이 없는 경우          |
-| OPENAPI00003 | 유효하지 않은 식별자        |
-| OPENAPI00004 | 파라미터 누락 또는 유효하지 않음 |
-| OPENAPI00005 | 유효하지 않은 API KEY    |
-| OPENAPI00006 | 유효하지 않은 API PATH   |
-| OPENAPI00007 | API 호출량 초과         |
-| OPENAPI00009 | 데이터 준비 중           |
-| OPENAPI00010 | 게임 점검 중            |
-| OPENAPI00011 | API 점검 중           |
+| ErrorCode    | Description                                      |
+|--------------|--------------------------------------------------|
+| OPENAPI00001 | Internal server error                            |
+| OPENAPI00002 | Access denied                                    |
+| OPENAPI00003 | Invalid identifier                               |
+| OPENAPI00004 | Request format error (incorrect parameter input) |
+| OPENAPI00005 | Invalid api key                                  |
+| OPENAPI00006 | Invalid api path                                 |
+| OPENAPI00007 | Request allowance (Rate Limit) exceeded          |
+| OPENAPI00009 | Not prepared data                                |
+| OPENAPI00010 | Game server maintenance                          |
+| OPENAPI00011 | API server maintenance                           |

package/dist/cjs/maplestory/api/kms/dto/character/characterItemEquipment.js

@@ -1026,6 +1026,14 @@ class CharacterItemEquipmentInfoDto extends characterItemEquipment.CharacterItem
      * 장비 기본 옵션
      */
     itemBaseOption;
+    /**
+     * 잠재능력 봉인 여부 (true 봉인, false 봉인 없음)
+     */
+    potentialOptionFlag;
+    /**
+     * 에디셔널 잠재능력 봉인 여부 (true 봉인, false 봉인 없음)
+     */
+    additionalPotentialOptionFlag;
     /**
      * 잠재능력 등급
      */
@@ -1140,7 +1148,7 @@ class CharacterItemEquipmentInfoDto extends characterItemEquipment.CharacterItem
     freestyleFlag;
     constructor(obj) {
         super();
-        const { item_equipment_part, item_equipment_slot, item_name, item_icon, item_description, item_shape_name, item_shape_icon, item_gender, item_total_option, item_base_option, potential_option_grade, additional_potential_option_grade, potential_option_1, potential_option_2, potential_option_3, additional_potential_option_1, additional_potential_option_2, additional_potential_option_3, equipment_level_increase, item_exceptional_option, item_add_option, growth_exp, growth_level, scroll_upgrade, cuttable_count, golden_hammer_flag, scroll_resilience_count, scroll_upgradeable_count, soul_name, soul_option, item_etc_option, starforce, starforce_scroll_flag, item_starforce_option, special_ring_level, date_expire, freestyle_flag, } = obj;
+        const { item_equipment_part, item_equipment_slot, item_name, item_icon, item_description, item_shape_name, item_shape_icon, item_gender, item_total_option, item_base_option, potential_option_flag, additional_potential_option_flag, potential_option_grade, additional_potential_option_grade, potential_option_1, potential_option_2, potential_option_3, additional_potential_option_1, additional_potential_option_2, additional_potential_option_3, equipment_level_increase, item_exceptional_option, item_add_option, growth_exp, growth_level, scroll_upgrade, cuttable_count, golden_hammer_flag, scroll_resilience_count, scroll_upgradeable_count, soul_name, soul_option, item_etc_option, starforce, starforce_scroll_flag, item_starforce_option, special_ring_level, date_expire, freestyle_flag, } = obj;
         this.itemEquipmentPart = item_equipment_part;
         this.itemEquipmentSlot = item_equipment_slot;
         this.itemName = item_name;
@@ -1151,6 +1159,8 @@ class CharacterItemEquipmentInfoDto extends characterItemEquipment.CharacterItem
         this.itemGender = item_gender;
         this.itemTotalOption = new CharacterItemEquipmentTotalOptionDto(item_total_option);
         this.itemBaseOption = new CharacterItemEquipmentBaseOptionDto(item_base_option);
+        this.potentialOptionFlag = potential_option_flag;
+        this.additionalPotentialOptionFlag = additional_potential_option_flag;
         this.potentialOptionGrade = potential_option_grade;
         this.additionalPotentialOptionGrade = additional_potential_option_grade;
         this.potentialOption1 = potential_option_1;

package/dist/cjs/maplestory/api/kms/dto/character/characterRingExchangeSkillEquipment.js

@@ -22,12 +22,22 @@ class CharacterRingExchangeSkillEquipmentDto {
      * 링 익스체인지에 등록된 특수 반지 레벨
      */
     specialRingExchangeLevel;
+    /**
+     * 링 익스체인지에 등록된 특수 반지 아이콘
+     */
+    specialRingExchangeIcon;
+    /**
+     * 링 익스체인지에 등록된 특수 반지 설명
+     */
+    specialRingExchangeDescription;
     constructor(obj) {
-        const { date, character_class, special_ring_exchange_name, special_ring_exchange_level } = obj;
+        const { date, character_class, special_ring_exchange_name, special_ring_exchange_level, special_ring_exchange_icon, special_ring_exchange_description } = obj;
         this.date = date ? new Date(date) : null;
         this.characterClass = character_class ?? '';
         this.specialRingExchangeName = special_ring_exchange_name ?? null;
         this.specialRingExchangeLevel = special_ring_exchange_level ?? null;
+        this.specialRingExchangeIcon = special_ring_exchange_icon ?? null;
+        this.specialRingExchangeDescription = special_ring_exchange_description ?? null;
     }
 }
 

package/dist/cjs/maplestory/api/kms/mapleStoryApi.js

@@ -917,7 +917,7 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
      * - 해당 API는 메이플스토리 한국의 데이터가 제공됩니다.
      *
      * @param guildName 길드 명
-     * @param worldName 월드 명
+     * @param worldName 월드 명 <a href="https://openapi.nexon.com/game/maplestory/?id=16">Available values</a>
      */
     async getGuild(guildName, worldName) {
         const path = `${this.subUrl}/v1/guild/id`;

package/dist/cjs/maplestory/api/msea/dto/character/characterItemEquipment.js

@@ -944,6 +944,14 @@ class CharacterItemEquipmentInfoDto extends characterItemEquipment.CharacterItem
      * Basic equipment option information
      */
     itemBaseOption;
+    /**
+     * Potential seal status (true:sealed, false:not sealed)
+     */
+    potentialOptionFlag;
+    /**
+     * Additional potential seal status (true:sealed, false:not sealed)
+     */
+    additionalPotentialOptionFlag;
     /**
      * Potential grade
      */
@@ -1054,7 +1062,7 @@ class CharacterItemEquipmentInfoDto extends characterItemEquipment.CharacterItem
     isExpired = null;
     constructor(obj) {
         super();
-        const { item_equipment_part, item_equipment_slot, item_name, item_icon, item_description, item_shape_name, item_shape_icon, item_gender, item_total_option, item_base_option, potential_option_grade, additional_potential_option_grade, potential_option_1, potential_option_2, potential_option_3, additional_potential_option_1, additional_potential_option_2, additional_potential_option_3, equipment_level_increase, item_exceptional_option, item_add_option, growth_exp, growth_level, scroll_upgrade, cuttable_count, golden_hammer_flag, scroll_resilience_count, scroll_upgradeable_count, soul_name, soul_option, item_etc_option, starforce, starforce_scroll_flag, item_starforce_option, special_ring_level, date_expire, } = obj;
+        const { item_equipment_part, item_equipment_slot, item_name, item_icon, item_description, item_shape_name, item_shape_icon, item_gender, item_total_option, item_base_option, potential_option_flag, additional_potential_option_flag, potential_option_grade, additional_potential_option_grade, potential_option_1, potential_option_2, potential_option_3, additional_potential_option_1, additional_potential_option_2, additional_potential_option_3, equipment_level_increase, item_exceptional_option, item_add_option, growth_exp, growth_level, scroll_upgrade, cuttable_count, golden_hammer_flag, scroll_resilience_count, scroll_upgradeable_count, soul_name, soul_option, item_etc_option, starforce, starforce_scroll_flag, item_starforce_option, special_ring_level, date_expire, } = obj;
         this.itemEquipmentPart = item_equipment_part;
         this.itemEquipmentSlot = item_equipment_slot;
         this.itemName = item_name;
@@ -1065,6 +1073,8 @@ class CharacterItemEquipmentInfoDto extends characterItemEquipment.CharacterItem
         this.itemGender = item_gender;
         this.itemTotalOption = new CharacterItemEquipmentTotalOptionDto(item_total_option);
         this.itemBaseOption = new CharacterItemEquipmentBaseOptionDto(item_base_option);
+        this.potentialOptionFlag = potential_option_flag;
+        this.additionalPotentialOptionFlag = additional_potential_option_flag;
         this.potentialOptionGrade = potential_option_grade;
         this.additionalPotentialOptionGrade = additional_potential_option_grade;
         this.potentialOption1 = potential_option_1;

package/dist/cjs/maplestory/api/msea/mapleStoryApi.js

@@ -757,7 +757,7 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
      * - Due to game content changes, the ocid may be updated. Please pay attention to this when updating services based on ocid.
      * - This API provides data for MapleStory SEA.
      * @param guildName Guild name
-     * @param worldName World name
+     * @param worldName World name <a href="https://openapi.nexon.com/game/maplestorysea/?id=47">Available values</a>
      */
     async getGuild(guildName, worldName) {
         const path = `${this.subUrl}/v1/guild/id`;

package/dist/cjs/maplestory/api/tms/dto/character/character.js

@@ -0,0 +1,22 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var character = require('../../../common/dto/character/character.js');
+
+/**
+ * 角色辨識器資訊
+ */
+class CharacterDto extends character.CharacterDto {
+    /**
+     * 角色辨識器
+     */
+    ocid;
+    constructor(obj) {
+        super();
+        const { ocid } = obj;
+        this.ocid = ocid;
+    }
+}
+
+exports.CharacterDto = CharacterDto;

package/dist/cjs/maplestory/api/tms/dto/character/characterAbility.js

@@ -0,0 +1,108 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var characterAbility = require('../../../common/dto/character/characterAbility.js');
+
+/**
+ * 角色能力資訊
+ */
+class CharacterAbilityDto extends characterAbility.CharacterAbilityDto {
+    /**
+     * 要搜尋的日期 (TST，每日資料中的小時與分鐘將顯示為 0)
+     */
+    date;
+    /**
+     * 能力階級
+     */
+    abilityGrade;
+    /**
+     * 能力資訊
+     */
+    abilityInfo;
+    /**
+     * 名聲值
+     */
+    remainFame;
+    /**
+     * 目前套用的能力預設編號
+     */
+    presetNo;
+    /**
+     * 能力 1 預設完整資訊
+     */
+    abilityPreset1;
+    /**
+     * 能力 2 預設完整資訊
+     */
+    abilityPreset2;
+    /**
+     * 能力 3 預設完整資訊
+     */
+    abilityPreset3;
+    constructor(obj) {
+        super();
+        const { date, ability_grade, ability_info, remain_fame, preset_no, ability_preset_1, ability_preset_2, ability_preset_3, } = obj;
+        this.date = date ? new Date(date) : null;
+        this.abilityGrade = ability_grade;
+        this.abilityInfo = ability_info.map((info) => new CharacterAbilityInfoDto(info));
+        this.remainFame = remain_fame;
+        this.presetNo = preset_no;
+        this.abilityPreset1 = ability_preset_1
+            ? new CharacterAbilityPresetDto(ability_preset_1)
+            : null;
+        this.abilityPreset2 = ability_preset_2
+            ? new CharacterAbilityPresetDto(ability_preset_2)
+            : null;
+        this.abilityPreset3 = ability_preset_3
+            ? new CharacterAbilityPresetDto(ability_preset_3)
+            : null;
+    }
+}
+/**
+ * 能力資訊
+ */
+class CharacterAbilityInfoDto extends characterAbility.CharacterAbilityInfoDto {
+    /**
+     * 能力編號
+     */
+    abilityNo;
+    /**
+     * 能力階級
+     */
+    abilityGrade;
+    /**
+     * 能力選項與數值
+     */
+    abilityValue;
+    constructor(obj) {
+        super();
+        const { ability_no, ability_grade, ability_value } = obj;
+        this.abilityNo = ability_no;
+        this.abilityGrade = ability_grade;
+        this.abilityValue = ability_value;
+    }
+}
+/**
+ * 能力預設完整資訊
+ */
+class CharacterAbilityPresetDto extends characterAbility.CharacterAbilityPresetDto {
+    /**
+     * 能力預設能力階級
+     */
+    abilityPresetGrade;
+    /**
+     * 能力預設資訊
+     */
+    abilityInfo;
+    constructor(obj) {
+        super();
+        const { ability_preset_grade, ability_info } = obj;
+        this.abilityPresetGrade = ability_preset_grade;
+        this.abilityInfo = ability_info.map((info) => new CharacterAbilityInfoDto(info));
+    }
+}
+
+exports.CharacterAbilityDto = CharacterAbilityDto;
+exports.CharacterAbilityInfoDto = CharacterAbilityInfoDto;
+exports.CharacterAbilityPresetDto = CharacterAbilityPresetDto;