maplestory-openapi 3.4.1 → 3.5.1

package/README.md

@@ -10,12 +10,13 @@ Packages written in other languages can be found [HERE](https://github.com/Spira
 English | [한국어](./README-ko.md)
 
 ## Notice
-
->🌏 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/).
+>💡 Notice 1: Migration is required when updating to version 3.5.0. Please refer to the documentation for [Migration](https://github.com/SpiralMoon/maplestory.openapi/tree/master/js/docs/migration-en.md).
+>
+>🌏 Notice 2: 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/).
 >
->🌏 Notice 2: Starting from version 3.0.0, support for msea region has been added.
+>🌏 Notice 3: 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).
+>💡 Notice 4: 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
 
@@ -99,12 +100,12 @@ 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)
+- [Character Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/kms/characterApi.test.ts)
+- [Union Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/kms/unionApi.test.ts)
+- [Guild Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/kms/guildApi.test.ts)
+- [History Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/kms/historyApi.test.ts)
+- [Ranking Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/kms/rankingApi.test.ts)
+- [Notice Information Retrieval](https://github.com/SpiralMoon/maplestory.openapi/blob/master/js/test/kms/noticeApi.test.ts)
 
 ### Features
 This library supports all apis published in the MapleStory OpenAPI official docs.

package/dist/cjs/maplestory/api/common/lib.js

@@ -22,5 +22,21 @@ const potentialOptionGradeFromString = (text) => {
     }
     return grade;
 };
+/**
+ * URL에서 Query를 제거합니다.
+ * @param url URL
+ * @example
+ * ```
+ * removeQuery('https://example.com/path?query=123&test=abc') // returns 'https://example.com/path'
+ * ```
+ */
+const removeQuery = (url) => {
+    if (!url) {
+        return url;
+    }
+    const queryIndex = url.indexOf('?');
+    return queryIndex >= 0 ? url.substring(0, queryIndex) : url;
+};
 
 exports.potentialOptionGradeFromString = potentialOptionGradeFromString;
+exports.removeQuery = removeQuery;

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

@@ -116,6 +116,31 @@ class MapleStoryApi {
         return str;
     }
     ;
+    /**
+     * API 응답 데이터가 비어있는지 확인 합니다.<br/>
+     * API 요청 시 날짜에 해당하는 데이터가 없을 경우 date 필드만 값이 존재하는 상황을 검증할 때 사용 합니다.<br/>
+     * 일반적으로 API 지원 시작일과 캐릭터 생성일 사이의 날짜를 조회할 때 발생 합니다.
+     * @example
+     * ```
+     * isEmptyResponse({ date: '2024-01-01', popularity: null }) // true
+     * isEmptyResponse({ date: '2024-01-01', popularity: 10 }) // false
+     * ```
+     */
+    isEmptyResponse(body) {
+        for (const [key, value] of Object.entries(body)) {
+            if (key === 'date') {
+                continue;
+            }
+            if (value === null || value === undefined) {
+                continue;
+            }
+            if (Array.isArray(value) && value.length === 0) {
+                continue;
+            }
+            return false;
+        }
+        return true;
+    }
 }
 
 exports.MapleStoryApi = MapleStoryApi;

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

@@ -98,7 +98,7 @@ class CharacterAndroidEquipmentDto extends characterAndroidEquipment.CharacterAn
             ? new CharacterAndroidEquipmentSkinDto(android_skin)
             : null;
         this.androidCashItemEquipment = android_cash_item_equipment.map((equipment) => new CharacterAndroidCashItemEquipmentDto(equipment));
-        this.androidEarSensorClipFlag = android_ear_sensor_clip_flag ?? null;
+        this.androidEarSensorClipFlag = android_ear_sensor_clip_flag;
         this.androidGender = android_gender;
         this.androidGrade = android_grade;
         this.androidNonHumanoidFlag = android_non_humanoid_flag;

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

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var characterBasic = require('../../../common/dto/character/characterBasic.js');
+var lib = require('../../../common/lib.js');
 
 /**
  * 캐릭터 기본 정보
@@ -77,8 +78,8 @@ class CharacterBasicDto extends characterBasic.CharacterBasicDto {
         this.characterExp = character_exp;
         this.characterExpRate = character_exp_rate;
         this.characterGuildName = character_guild_name;
-        this.characterImage = character_image;
-        this.characterDateCreate = new Date(character_date_create);
+        this.characterImage = lib.removeQuery(character_image);
+        this.characterDateCreate = character_date_create ? new Date(character_date_create) : null;
         this.accessFlag = access_flag;
         this.liberationQuestClear = liberation_quest_clear;
     }

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

@@ -33,7 +33,7 @@ class CharacterRingExchangeSkillEquipmentDto {
     constructor(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.characterClass = character_class;
         this.specialRingExchangeName = special_ring_exchange_name ?? null;
         this.specialRingExchangeLevel = special_ring_exchange_level ?? null;
         this.specialRingExchangeIcon = special_ring_exchange_icon ?? null;

package/dist/cjs/maplestory/api/kms/dto/history/starforceHistory.js

@@ -94,7 +94,7 @@ class StarforceHistoryDto {
         this.dateCreate = new Date(date_create);
         this.starforceEventList =
             starforce_event_list?.map((event) => new StarforceEventDto(event)) ??
-                null;
+                [];
     }
 }
 /**

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

@@ -56,6 +56,7 @@ var achievement = require('./dto/user/achievement.js');
 var characterList = require('./dto/user/characterList.js');
 var characterImage = require('../common/enum/characterImage.js');
 var mapleStoryApi = require('../common/mapleStoryApi.js');
+var lib = require('../common/lib.js');
 var index = require('../../../_virtual/index.js_commonjs-exports.js');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
@@ -146,6 +147,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterBasic.CharacterBasicDto(data);
     }
     /**
@@ -161,7 +165,11 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
      * @param dateOptions 조회 기준일 (KST)
      */
     async getCharacterImage(ocid, imageOptions, dateOptions) {
-        const { date, characterImage: path } = await this.getCharacterBasic(ocid, dateOptions);
+        const basic = await this.getCharacterBasic(ocid, dateOptions);
+        if (!basic) {
+            return null;
+        }
+        const { date, characterImage: characterImage$2 } = basic;
         const action = imageOptions?.action ?? characterImage.CharacterImageAction.Stand1;
         const emotion = imageOptions?.emotion ?? characterImage.CharacterImageEmotion.Default;
         const wmotion = imageOptions?.wmotion ?? characterImage.CharacterImageWeaponMotion.Default;
@@ -171,6 +179,7 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const height = 300;
         const x = 150;
         const y = 200;
+        const path = lib.removeQuery(characterImage$2);
         const query = {
             action: `${action}.${actionFrame}`,
             emotion: `${emotion}.${emotionFrame}`,
@@ -232,6 +241,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterPopularity.CharacterPopularityDto(data);
     }
     /**
@@ -261,6 +273,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterStat.CharacterStatDto(data);
     }
     /**
@@ -290,6 +305,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterHyperStat.CharacterHyperStatDto(data);
     }
     /**
@@ -319,6 +337,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterPropensity.CharacterPropensityDto(data);
     }
     /**
@@ -348,6 +369,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterAbility.CharacterAbilityDto(data);
     }
     /**
@@ -377,6 +401,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterItemEquipment.CharacterItemEquipmentDto(data);
     }
     /**
@@ -406,6 +433,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterCashItemEquipment.CharacterCashItemEquipmentDto(data);
     }
     /**
@@ -435,6 +465,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterSymbolEquipment.CharacterSymbolEquipmentDto(data);
     }
     /**
@@ -464,6 +497,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterSetEffect.CharacterSetEffectDto(data);
     }
     /**
@@ -493,6 +529,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterBeautyEquipment.CharacterBeautyEquipmentDto(data);
     }
     /**
@@ -522,6 +561,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterAndroidEquipment.CharacterAndroidEquipmentDto(data);
     }
     /**
@@ -551,6 +593,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterPetEquipment.CharacterPetEquipmentDto(data);
     }
     /**
@@ -582,6 +627,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterSkill.CharacterSkillDto(data);
     }
     /**
@@ -611,6 +659,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterLinkSkill.CharacterLinkSkillDto(data);
     }
     /**
@@ -640,6 +691,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterVMatrix.CharacterVMatrixDto(data);
     }
     /**
@@ -669,6 +723,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterHexaMatrix.CharacterHexaMatrixDto(data);
     }
     /**
@@ -698,6 +755,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterHexaMatrixStat.CharacterHexaMatrixStatDto(data);
     }
     /**
@@ -727,6 +787,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterDojang.CharacterDojangDto(data);
     }
     /**
@@ -756,6 +819,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterOtherStat.CharacterOtherStatDto(data);
     }
     /**
@@ -785,6 +851,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new characterRingExchangeSkillEquipment.CharacterRingExchangeSkillEquipmentDto(data);
     }
     //#endregion
@@ -816,6 +885,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new union.UnionDto(data);
     }
     /**
@@ -845,12 +917,15 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new unionRaider.UnionRaiderDto(data);
     }
     /**
      * 유니온 아티팩트 정보를 조회합니다.
      * - 메이플스토리 게임 데이터는 평균 15분 후 확인 가능합니다.
-     * - 2023년 12월 21일 데이터부터 조회할 수 있습니다.
+     * - 2024년 1월 18일 데이터부터 조회할 수 있습니다.
      * - 과거 데이터는 원하는 일자를 입력해 조회할 수 있으며, 전일 데이터는 다음날 오전 2시부터 확인할 수 있습니다. (12월 22일 데이터 조회 시, 22일 00시부터 23일 00시 사이 데이터가 조회 됩니다.)
      * - 게임 콘텐츠 변경으로 ocid가 변경될 수 있습니다. ocid 기반 서비스 갱신 시 유의해 주시길 바랍니다.
      * - 해당 API는 메이플스토리 한국의 데이터가 제공됩니다.
@@ -862,9 +937,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const path = `${this.subUrl}/v1/user/union-artifact`;
         const date = dateOptions
             ? this.toDateString(dateOptions, {
-                year: 2023,
-                month: 12,
-                day: 21,
+                year: 2024,
+                month: 1,
+                day: 18,
             })
             : undefined;
         const query = {
@@ -874,13 +949,16 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new unionArtifact.UnionArtifactDto(data);
     }
     /**
      * 유니온 챔피언 정보를 조회합니다.<br>
      * 유니온 챔피언 정보는 2025년 2월 20일 메이플스토리 점검 이후 데이터부터 조회 가능합니다.<br>
      * - 메이플스토리 게임 데이터는 평균 15분 후 확인 가능합니다.
-     * - 2023년 12월 21일 데이터부터 조회할 수 있습니다.
+     * - 2025년 2월 20일 데이터부터 조회할 수 있습니다.
      * - 과거 데이터는 원하는 일자를 입력해 조회할 수 있으며, 전일 데이터는 다음날 오전 2시부터 확인할 수 있습니다. (12월 22일 데이터 조회 시, 22일 00시부터 23일 00시 사이 데이터가 조회 됩니다.)
      * - 게임 콘텐츠 변경으로 ocid가 변경될 수 있습니다. ocid 기반 서비스 갱신 시 유의해 주시길 바랍니다.
      * - 해당 API는 메이플스토리 한국의 데이터가 제공됩니다.
@@ -892,9 +970,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const path = `${this.subUrl}/v1/user/union-champion`;
         const date = dateOptions
             ? this.toDateString(dateOptions, {
-                year: 2023,
-                month: 12,
-                day: 21,
+                year: 2025,
+                month: 2,
+                day: 20,
             })
             : undefined;
         const query = {
@@ -904,6 +982,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new unionChampion.UnionChampionDto(data);
     }
     //#endregion
@@ -927,6 +1008,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
                 world_name: worldName,
             },
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new guild.GuildDto(data);
     }
     /**
@@ -956,6 +1040,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
         const { data } = await this.client.get(path, {
             params: query,
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new guildBasic.GuildBasicDto(data);
     }
     async getStarforceHistory(count, parameter) {
@@ -1124,10 +1211,10 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
             ranking_type: 0,
         };
         if (filterOptions) {
-            const { worldName, rankingType, ocid, page } = filterOptions;
+            const { worldName, rankingType, guildName, page } = filterOptions;
             query.world_name = worldName;
             query.ranking_type = rankingType;
-            query.ocid = ocid;
+            query.guild_name = guildName;
             query.page = page;
         }
         const { data } = await this.client.get(path, {

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

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var characterBasic = require('../../../common/dto/character/characterBasic.js');
+var lib = require('../../../common/lib.js');
 
 /**
  * Character basic information
@@ -77,8 +78,8 @@ class CharacterBasicDto extends characterBasic.CharacterBasicDto {
         this.characterExp = character_exp;
         this.characterExpRate = character_exp_rate;
         this.characterGuildName = character_guild_name;
-        this.characterImage = character_image;
-        this.characterDateCreate = new Date(character_date_create);
+        this.characterImage = lib.removeQuery(character_image);
+        this.characterDateCreate = character_date_create ? new Date(character_date_create) : null;
         this.accessFlag = access_flag;
         this.liberationQuestClearFlag = liberation_quest_clear_flag;
     }