maplestory-openapi 3.4.0 → 3.5.0

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/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

@@ -78,7 +78,7 @@ class CharacterBasicDto extends characterBasic.CharacterBasicDto {
         this.characterExpRate = character_exp_rate;
         this.characterGuildName = character_guild_name;
         this.characterImage = character_image;
-        this.characterDateCreate = new Date(character_date_create);
+        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

@@ -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.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/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

@@ -146,6 +146,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 +164,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: path } = basic;
         const action = imageOptions?.action ?? characterImage.CharacterImageAction.Stand1;
         const emotion = imageOptions?.emotion ?? characterImage.CharacterImageEmotion.Default;
         const wmotion = imageOptions?.wmotion ?? characterImage.CharacterImageWeaponMotion.Default;
@@ -232,6 +239,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 +271,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 +303,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 +335,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 +367,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 +399,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 +431,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 +463,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 +495,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 +527,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 +559,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 +591,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 +625,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 +657,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 +689,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 +721,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 +753,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 +785,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 +817,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 +849,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 +883,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 +915,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 +935,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 +947,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 +968,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 +980,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 +1006,9 @@ class MapleStoryApi extends mapleStoryApi.MapleStoryApi {
                 world_name: worldName,
             },
         });
+        if (this.isEmptyResponse(data)) {
+            return null;
+        }
         return new guild.GuildDto(data);
     }
     /**
@@ -956,6 +1038,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 +1209,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

@@ -78,7 +78,7 @@ class CharacterBasicDto extends characterBasic.CharacterBasicDto {
         this.characterExpRate = character_exp_rate;
         this.characterGuildName = character_guild_name;
         this.characterImage = character_image;
-        this.characterDateCreate = new Date(character_date_create);
+        this.characterDateCreate = character_date_create ? new Date(character_date_create) : null;
         this.accessFlag = access_flag;
         this.liberationQuestClearFlag = liberation_quest_clear_flag;
     }