dnf-api 1.0.7 → 1.1.1

package/src/api/characters.skill.ts

@@ -13,7 +13,7 @@ export const style = (serverId: staticUtil.server, characterId: string) => {
       "characters",
       characterId,
       "skill",
-      "style"
+      "style",
     )}`,
   };
   return query.Request(opt);
@@ -35,7 +35,7 @@ export const equipment = (serverId: staticUtil.server, characterId: string) => {
       "skill",
       "buff",
       "equip",
-      "equipment"
+      "equipment",
     )}`,
   };
   return query.Request(opt);
@@ -57,7 +57,7 @@ export const avatar = (serverId: staticUtil.server, characterId: string) => {
       "skill",
       "buff",
       "equip",
-      "avatar"
+      "avatar",
     )}`,
   };
   return query.Request(opt);
@@ -79,7 +79,7 @@ export const creature = (serverId: staticUtil.server, characterId: string) => {
       "skill",
       "buff",
       "equip",
-      "creature"
+      "creature",
     )}`,
   };
   return query.Request(opt);

package/src/api/characters.ts

@@ -11,7 +11,7 @@ import { type params, query, staticUtil } from "../util";
 export const characterName = (
   serverId: staticUtil.server,
   characterName: string,
-  params: params.ICharParams = {}
+  params: params.ICharParams = {},
 ) => {
   // if (params === undefined) params = {};
   params.characterName = characterName;
@@ -30,14 +30,14 @@ export const characterName = (
  */
 export const characterId = (
   serverId: staticUtil.server,
-  characterId: string
+  characterId: string,
 ) => {
   const opt = {
     base: query.UriBuilder(
       staticUtil.baseUri.Servers,
       serverId,
       "characters",
-      characterId
+      characterId,
     ),
   };
   return query.Request<model.char.IInfo>(opt);
@@ -53,7 +53,7 @@ export const characterId = (
 export const timeline = (
   serverId: staticUtil.server,
   characterId: string,
-  params: params.ITimeLine = {}
+  params: params.ITimeLine = {},
 ) => {
   const opt = {
     base: query.UriBuilder(
@@ -61,7 +61,7 @@ export const timeline = (
       serverId,
       "characters",
       characterId,
-      "timeline"
+      "timeline",
     ),
     params: {
       ...params,
@@ -84,7 +84,7 @@ export const status = (serverId: staticUtil.server, characterId: string) => {
       serverId,
       "characters",
       characterId,
-      "status"
+      "status",
     ),
   };
   return query.Request<model.char.ICharacterStatus>(opt);

package/src/model/setitem.ts

@@ -15,7 +15,7 @@ export interface IDetail {
       itemId: string;
       itemName: string;
       itemRarity: string;
-    }
+    },
   ];
   setItemOption: [
     {
@@ -26,8 +26,8 @@ export interface IDetail {
         {
           name: string;
           value: number;
-        }
+        },
       ];
-    }
+    },
   ];
 }

package/src/util/config.ts

@@ -1,14 +1,17 @@
+// 설정 인터페이스
 export interface IConfig {
-  key: string | undefined;
+  key: string;
   hideOnErrorApiKey: boolean;
   hideKeyText: string;
   timeout: number;
   returnJSON: boolean;
   responseHeader: boolean;
   showURL: boolean;
+  maxRequestsPerSecond: number;
 }
-// biome-ignore lint/style/useConst: <explanation>
-let defaultConfig: IConfig = {
+
+// 기본 설정값
+const defaultConfig: IConfig = {
   key: "",
   hideOnErrorApiKey: true,
   hideKeyText: "{HIDE_KEY}",
@@ -16,5 +19,25 @@ let defaultConfig: IConfig = {
   returnJSON: false,
   responseHeader: false,
   showURL: false,
+  maxRequestsPerSecond: 1000,
 };
-export default defaultConfig;
+
+// 현재 설정 (복사본)
+export const config: IConfig = { ...defaultConfig };
+
+/**
+ * 설정을 업데이트합니다.
+ * @param newConfig 업데이트할 설정 값
+ */
+export function setConfig(newConfig: Partial<IConfig>): void {
+  Object.assign(config, newConfig);
+}
+
+/**
+ * 설정을 기본값으로 초기화합니다.
+ */
+export function resetConfig(): void {
+  Object.assign(config, defaultConfig);
+}
+
+export default config;

package/src/util/index.ts

@@ -1,6 +1,17 @@
-import config from "./config";
+import config, { setConfig, resetConfig } from "./config";
 import * as params from "./params";
 import query from "./query";
+import { requestQueue } from "./queue";
+import { createRequest } from "./request-helper";
 import * as staticUtil from "./static";
 
-export { config, query, staticUtil, params };
+export {
+  config,
+  setConfig,
+  resetConfig,
+  query,
+  staticUtil,
+  params,
+  createRequest,
+  requestQueue,
+};

package/src/util/params.ts

@@ -1,9 +1,19 @@
 import type * as staticUtil from "./static";
-export interface QueryOptions<T = any> {
+
+// 기본 파라미터 타입
+export type ParamValue = string | number | boolean | undefined;
+
+// 인덱스 시그니처가 있는 기본 인터페이스
+export interface BaseParams {
+  [key: string]: ParamValue | ParamValue[] | object | undefined;
+}
+
+export interface QueryOptions<T = BaseParams> {
   base: string;
   params?: T;
 }
-export interface ICharParams {
+
+export interface ICharParams extends BaseParams {
   characterName?: string;
   jobId?: string;
   jobGrowId?: string;
@@ -12,7 +22,7 @@ export interface ICharParams {
   limit?: number;
 }
 
-export interface ITimeLine {
+export interface ITimeLine extends BaseParams {
   serverId?: staticUtil.server;
   characterId?: string;
   startDate?: Date;
@@ -22,7 +32,7 @@ export interface ITimeLine {
   next?: string;
 }
 
-export interface IAuction {
+export interface IAuction extends BaseParams {
   limit?: number;
   sort?: IAuctionSort;
   itemId?: string;
@@ -31,11 +41,13 @@ export interface IAuction {
   wordShort?: boolean;
   q?: IAuctionQuery;
 }
+
 export interface IAuctionSort {
   unitPrice?: staticUtil.sort;
   reinforce?: staticUtil.sort;
   auctionNo?: staticUtil.sort;
 }
+
 export interface IAuctionQuery {
   minLevel?: number;
   maxLevel?: number;
@@ -49,7 +61,7 @@ export interface IAuctionQuery {
   maxFame?: number;
 }
 
-export interface IActionSoldOption {
+export interface IActionSoldOption extends BaseParams {
   limit?: number;
   wordType?: staticUtil.auctionWordType;
   wordShort?: boolean;
@@ -58,25 +70,26 @@ export interface IActionSoldOption {
   sort?: IAuctionSort;
 }
 
-export interface IItem {
+export interface IItem extends BaseParams {
   limit?: number;
   itemName?: string;
   hashtag?: string[];
   wordType?: staticUtil.auctionWordType;
   q?: IItemQuery;
 }
+
 export interface IItemQuery {
   minLevel?: number;
   maxLevel?: number;
   rarity?: staticUtil.rarity;
-  // trade?: boolean;
 }
 
-export interface ISetItem {
+export interface ISetItem extends BaseParams {
   setItemName?: string;
   limit?: number;
   wordType?: staticUtil.auctionWordType;
 }
-export interface ISkill {
+
+export interface ISkill extends BaseParams {
   jobGrowId: string;
 }

package/src/util/query.ts

@@ -1,95 +1,147 @@
 import consola from "consola";
-import querystring from "query-string";
-import { request } from "undici";
 
 import type * as model from "../model";
 import * as Util from "./";
+import type { BaseParams } from "./params";
+import { requestQueue } from "./queue";
 
-const apiUrl = new URL("https://api.neople.co.kr");
-// const client = new Client("https://api.neople.co.kr", {
-//   connectTimeout: Util.Config.timeout,
-//   // allowH2: true,
-// });
-
-const sender = async <T>(path: string, method: "GET" | "POST", query: any) => {
-  apiUrl.pathname = path;
-  apiUrl.search = querystring.stringify(query);
-  const res = await request<model.IDnfResponse<T>>(apiUrl.href, {
-    method,
-  });
-  return res;
+// 요청 옵션 인터페이스
+export interface RequestOptions {
+  base: string;
+  params?: BaseParams;
+  url?: string;
+}
+
+const API_BASE_URL = "https://api.neople.co.kr";
+
+// 파라미터를 URLSearchParams로 변환 (중첩 객체는 JSON으로 직렬화)
+const toSearchParams = (params: BaseParams): URLSearchParams => {
+  const entries: [string, string][] = [];
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined) continue;
+    if (typeof value === "object" && !Array.isArray(value)) {
+      entries.push([key, JSON.stringify(value)]);
+    } else if (Array.isArray(value)) {
+      entries.push([key, value.join(",")]);
+    } else {
+      entries.push([key, String(value)]);
+    }
+  }
+  return new URLSearchParams(entries);
+};
+
+// HTTP 요청 전송 함수
+const sender = async <T>(
+  path: string,
+  method: "GET" | "POST",
+  query: BaseParams
+): Promise<{
+  ok: boolean;
+  status: number;
+  data: T | model.IDnfResponse<T>;
+}> => {
+  const url = new URL(path, API_BASE_URL);
+  url.search = toSearchParams(query).toString();
+
+  const res = await fetch(url.toString(), { method });
+  const data = (await res.json()) as T | model.IDnfResponse<T>;
+
+  return {
+    ok: res.ok,
+    status: res.status,
+    data,
+  };
 };
 
+// URL에서 API 키 숨김 처리
 const showUrl = (url: string): string => {
   if (Util.config.key) {
     return url?.replace(Util.config.key, Util.config.hideKeyText);
-  } else {
-    return url;
   }
+  return url;
 };
 
-// biome-ignore lint/complexity/noStaticOnlyClass: <explanation>
-export default class Request {
-  public static UriBuilder(...args: any[]): string {
-    return args.join("/");
+/**
+ * URI 경로를 빌드합니다.
+ * @param args 경로 세그먼트들
+ * @returns 결합된 URI 경로
+ */
+export function UriBuilder(...args: (string | number)[]): string {
+  return args.join("/");
+}
+
+/**
+ * 쿼리 문자열을 빌드합니다.
+ * @param query 쿼리 배열
+ * @returns 쿼리 문자열
+ */
+export function QueryBuilder(query: (string | number)[]): string {
+  const qString: string[] = [];
+  for (const key in query) {
+    qString.push(`${key}:${query[key]},`);
   }
-  public static QueryBuilder(query: string[] | number[]): string {
-    const qString: string[] = [];
-    for (const key in query) {
-      qString.push(`${key}:${query[key]},`);
-    }
-    return qString.join(",");
+  return qString.join(",");
+}
+
+/**
+ * 던전앤파이터 API 서버에 요청을 보내는 함수입니다.
+ * @param opt 요청 옵션
+ * @param method HTTP 메서드
+ * @returns API 응답
+ */
+export async function Request<T>(
+  opt: RequestOptions = { base: "" },
+  method: "GET" | "POST" = "GET"
+): Promise<model.IDnfResponse<T>> {
+  if (!Util.config.key) {
+    throw new Error(
+      "API key is required. Set config.key before making requests."
+    );
   }
 
-  /**
-   *  던전앤파이터 API 서버에 응답을 요청하는 함수 입니다.
-   * 해당 함수를 직접 호출 하는것을 권장하지 않습니다.
-   *
-   * @param {object} opt (요청을 보낼 Parameter값)
-   * @returns
-   */
-  public static async Request<T>(
-    opt: any = {},
-    method: "GET" | "POST" = "GET"
-  ): Promise<model.IDnfResponse<T>> {
-    if (!Util.config.key || Util.config.key === "") {
-      consola.error("Please change to your api key. ");
-    }
+  const params: BaseParams = { ...opt.params };
 
-    if (opt.params === undefined) opt.params = {};
-    if (opt.params.q) opt.params.q = Request.QueryBuilder(opt.params.q);
-    if (opt.params.sort)
-      opt.params.sort = Request.QueryBuilder(opt.params.sort);
-
-    opt.params.apikey = Util.config.key;
-
-    if (Util.config.showURL)
-      consola.log(
-        "request url:",
-        showUrl(`${opt.base}?${querystring.stringify(opt.params)}`)
-      );
-
-    const res = await sender<T>(opt.base, method, opt.params);
-    if (res.statusCode !== 200) {
-      const resBody = (await res.body.json()) as model.IDnfResponse<T>;
-      const error: model.IDnfErrorResponse = {
-        url: showUrl(opt.url ?? ""),
-        status: res.statusCode || 0,
-        statusText: "",
-        code: resBody.error?.code || "",
-        message: resBody.error?.message || "",
-      };
-      return { error };
-    } else {
-      const resBody = (await res.body.json()) as T;
-      return {
-        data: resBody,
-      };
-    }
+  if (params.q && Array.isArray(params.q)) {
+    params.q = QueryBuilder(params.q as (string | number)[]);
   }
+  if (params.sort && Array.isArray(params.sort)) {
+    params.sort = QueryBuilder(params.sort as (string | number)[]);
+  }
+
+  params.apikey = Util.config.key;
 
-  public static makeItemQuery(query: any) {
-    //  return JSON.stringify(query).replace(/\"|\{|\}/gi, "");
-    return encodeURI(query);
+  if (Util.config.showURL) {
+    consola.log(
+      "request url:",
+      showUrl(`${opt.base}?${toSearchParams(params)}`)
+    );
   }
+
+  const res = await requestQueue.add(() => sender<T>(opt.base, method, params));
+
+  if (!res.ok) {
+    const resBody = res.data as model.IDnfResponse<T>;
+    const error: model.IDnfErrorResponse = {
+      url: showUrl(opt.url ?? ""),
+      status: res.status || 0,
+      statusText: "",
+      code: resBody.error?.code || "",
+      message: resBody.error?.message || "",
+    };
+    return { error };
+  }
+
+  return { data: res.data as T };
 }
+
+/**
+ * 아이템 쿼리를 생성합니다.
+ * @param query 쿼리 문자열
+ * @returns 인코딩된 쿼리
+ */
+export function makeItemQuery(query: string): string {
+  return encodeURI(query);
+}
+
+// 기존 호환성을 위한 default export
+export default { UriBuilder, QueryBuilder, Request, makeItemQuery };

package/src/util/queue.ts

@@ -0,0 +1,104 @@
+import config from "./config";
+
+/**
+ * Rate limiting 요청 큐
+ * 1초당 최대 요청 수를 제한합니다.
+ */
+
+interface QueueItem<T> {
+  task: () => Promise<T>;
+  resolve: (value: T) => void;
+  reject: (error: Error) => void;
+}
+
+export class RequestQueue {
+  private queue: QueueItem<unknown>[] = [];
+  private processing = false;
+  private requestCount = 0;
+  private lastResetTime = Date.now();
+
+  /**
+   * 큐에 요청을 추가합니다.
+   * @param task 실행할 비동기 작업
+   * @returns 작업 결과 Promise
+   */
+  async add<T>(task: () => Promise<T>): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      this.queue.push({
+        task,
+        resolve: resolve as (value: unknown) => void,
+        reject,
+      });
+      this.processQueue();
+    });
+  }
+
+  /**
+   * 큐를 처리합니다.
+   */
+  private async processQueue(): Promise<void> {
+    if (this.processing) return;
+    this.processing = true;
+
+    while (this.queue.length > 0) {
+      // 1초마다 카운터 리셋
+      const now = Date.now();
+      if (now - this.lastResetTime >= 1000) {
+        this.requestCount = 0;
+        this.lastResetTime = now;
+      }
+
+      // 제한에 도달하면 대기 (config에서 실시간으로 가져옴)
+      if (this.requestCount >= config.maxRequestsPerSecond) {
+        const waitTime = 1000 - (now - this.lastResetTime);
+        if (waitTime > 0) {
+          await this.sleep(waitTime);
+        }
+        this.requestCount = 0;
+        this.lastResetTime = Date.now();
+      }
+
+      const item = this.queue.shift();
+      if (!item) break;
+
+      this.requestCount++;
+
+      try {
+        const result = await item.task();
+        item.resolve(result);
+      } catch (error) {
+        item.reject(error as Error);
+      }
+    }
+
+    this.processing = false;
+  }
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * 현재 큐 상태를 반환합니다.
+   */
+  get status() {
+    return {
+      queueLength: this.queue.length,
+      requestCount: this.requestCount,
+      maxRequestsPerSecond: config.maxRequestsPerSecond,
+    };
+  }
+
+  /**
+   * 큐를 초기화합니다.
+   */
+  clear(): void {
+    this.queue = [];
+    this.requestCount = 0;
+  }
+}
+
+// 기본 큐 인스턴스 (제한 수치는 config를 따름)
+export const requestQueue = new RequestQueue();
+
+export default requestQueue;

package/src/util/request-helper.ts

@@ -0,0 +1,19 @@
+import type * as model from "../model";
+import type { BaseParams } from "./params";
+import { Request, UriBuilder } from "./query";
+
+/**
+ * API 요청을 생성하는 헬퍼 함수
+ * @param baseParts URI 경로 세그먼트들
+ * @param params 요청 파라미터
+ * @returns API 응답 Promise
+ */
+export function createRequest<T>(
+  baseParts: (string | number)[],
+  params?: BaseParams,
+): Promise<model.IDnfResponse<T>> {
+  return Request<T>({
+    base: UriBuilder(...baseParts),
+    params,
+  });
+}

package/dist/test.d.ts

@@ -1 +0,0 @@
-import "dotenv/config";