@uniai-fe/util-api 0.1.0

package/README.md

@@ -0,0 +1,23 @@
+# @uniai-fe/util-api
+
+API contract types and request/runtime helpers for framework-agnostic integration.
+
+## Scope
+
+- API response 공통 타입
+- API request/runtime helper
+- framework 비종속(React/Next 의존성 없음)
+
+## Install
+
+```bash
+pnpm add @uniai-fe/util-api
+```
+
+## Usage
+
+```ts
+import type { API_Res_Base } from "@uniai-fe/util-api";
+
+type API_Res_User = API_Res_Base<{ user_id: number } | null>;
+```

package/dist/index.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+var utilFunctions = require('@uniai-fe/util-functions');
+
+// src/request/module.ts
+var getQueryString = (searchParams) => {
+  const serialized = utilFunctions.convertObjectToSearchParams(searchParams).toString();
+  return serialized ? `?${serialized}` : "";
+};
+var nextAPILog = (method, routeUrl, queryUrl, ...messages) => {
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
+  const date = /* @__PURE__ */ new Date();
+  const dateText = date.toISOString().split("T")[0] ?? "";
+  const timeText = `${date.toLocaleTimeString("en-US", { hour12: false })}.${date.getMilliseconds()}`;
+  const requestMethod = method.split("-")[0]?.toUpperCase() || "-";
+  const responseMethod = method.split("-")[1]?.toUpperCase() || requestMethod;
+  return console.log(
+    `
+`,
+    `[Next Server API] \u23F1 ${dateText} ( ${timeText} )`,
+    `
+  \u03BB [${requestMethod}] FE route`,
+    `
+   ${routeUrl}`,
+    ...queryUrl ? [`
+  \u2550\u23F5 \u03A9 [${responseMethod}] BE url`, `
+   ${queryUrl}`, `
+`] : [],
+    ...messages?.[0] ? [` \u25C7-`, ...messages] : [],
+    `
+`
+  );
+};
+var generateQueryUrl = ({
+  method = "GET",
+  domain,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  log,
+  logDisabled
+}) => {
+  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;
+  if (!logDisabled) {
+    nextAPILog(method, routeUrl, url, {
+      ...log ?? {},
+      ...searchParams ?? {}
+    });
+  }
+  return url;
+};
+var getFetchOptions = ({
+  method,
+  headers,
+  body
+}) => ({
+  method,
+  ...typeof headers === "undefined" ? {} : { headers },
+  ...typeof body === "undefined" ? {} : { body }
+});
+var fetchWithBody = async ({
+  domain,
+  method,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  headers,
+  body,
+  bodyData,
+  isRawResponse,
+  alternateResponse,
+  debug,
+  disabled,
+  disabledLog
+}) => {
+  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;
+  const option = getFetchOptions({ method, headers, body });
+  if (!body && typeof bodyData !== "undefined") {
+    const bodyParams = utilFunctions.convertObjectToSearchParams(bodyData).toString();
+    if (bodyParams === "") {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: "ERROR (BODY - DATA)",
+        error: "\uB370\uC774\uD130\uAC00 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+        bodyData,
+        ...debug ?? {}
+      });
+      return alternateResponse;
+    }
+    option.body = bodyData;
+  }
+  if (!disabledLog) {
+    nextAPILog(method.toLowerCase(), routeUrl, url, {
+      state: "READY",
+      ...option,
+      ...debug ?? {}
+    });
+  }
+  if (disabled) {
+    nextAPILog(method.toLowerCase(), routeUrl, url, {
+      state: "FETCH DISABLED",
+      message: "API \uC694\uCCAD\uC81C\uD55C \uD65C\uC131\uD654\uB428."
+    });
+    return alternateResponse;
+  }
+  try {
+    const responseRaw = await fetch(url, option);
+    const responseCode = responseRaw.status;
+    if (!disabledLog) {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: responseCode === 200 ? "SUCCESS" : "FAIL",
+        code: responseCode
+      });
+    }
+    if (isRawResponse) {
+      return responseRaw;
+    }
+    return await responseRaw.json();
+  } catch (error) {
+    if (!disabledLog) {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: "ERROR (RESPONSE)",
+        error,
+        ...debug ?? {}
+      });
+    }
+    return alternateResponse;
+  }
+};
+
+exports.fetchWithBody = fetchWithBody;
+exports.generateQueryUrl = generateQueryUrl;
+exports.getFetchOptions = getFetchOptions;
+exports.getQueryString = getQueryString;
+exports.nextAPILog = nextAPILog;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/request/module.ts"],"names":["convertObjectToSearchParams"],"mappings":"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","file":"index.cjs","sourcesContent":["import { convertObjectToSearchParams } from \"@uniai-fe/util-functions\";\nimport type {\n  API_FetchWithBodyParams,\n  API_GetFetchOptionsParams,\n  API_GenerateQueryUrlParams,\n} from \"./types\";\n\n/**\n * API Request Utils; 쿼리스트링 생성\n * @param {unknown} [searchParams] 쿼리스트링 변환 대상\n * @returns {string} 직렬화된 쿼리스트링\n * @example\n * const query = getQueryString({ farm_id: 1 });\n */\nexport const getQueryString = (searchParams?: unknown): string => {\n  // 변경: util-functions 공통 유틸을 재사용해 query 변환 규칙을 단일화한다.\n  const serialized = convertObjectToSearchParams(searchParams).toString();\n  return serialized ? `?${serialized}` : \"\";\n};\n\n/**\n * API Request Utils; Next.js route 디버깅 로그 출력\n * @param {string} method HTTP method 문자열\n * @param {string} routeUrl frontend route URL\n * @param {string} [queryUrl] backend query URL\n * @param {unknown[]} messages 로그 메시지\n */\nexport const nextAPILog = (\n  method: string,\n  routeUrl: string,\n  queryUrl?: string,\n  ...messages: unknown[]\n) => {\n  if (process.env.NODE_ENV === \"production\") {\n    return;\n  }\n\n  // 변경: util-api 단독 동작을 위해 날짜 포맷 의존성을 내부 계산으로 대체한다.\n  const date = new Date();\n  const dateText = date.toISOString().split(\"T\")[0] ?? \"\";\n  const timeText = `${date.toLocaleTimeString(\"en-US\", { hour12: false })}.${date.getMilliseconds()}`;\n  const requestMethod = method.split(\"-\")[0]?.toUpperCase() || \"-\";\n  const responseMethod = method.split(\"-\")[1]?.toUpperCase() || requestMethod;\n\n  return console.log(\n    `\\n`,\n    `[Next Server API] ⏱ ${dateText} ( ${timeText} )`,\n    `\\n  λ [${requestMethod}] FE route`,\n    `\\n   ${routeUrl}`,\n    ...(queryUrl\n      ? [`\\n  ═⏵ Ω [${responseMethod}] BE url`, `\\n   ${queryUrl}`, `\\n`]\n      : []),\n    ...(messages?.[0] ? [` ◇-`, ...messages] : []),\n    `\\n`,\n  );\n};\n\n/**\n * API Request Utils; GET API 요청 URL 생성\n * @param {API_GenerateQueryUrlParams} params URL 생성 파라미터\n * @property {string} [params.method] fetch HTTP method\n * @property {string} params.domain API 도메인\n * @property {string} params.routeUrl frontend route URL\n * @property {string} params.queryUrl backend query URL\n * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본\n * @property {object} [params.log] 디버깅 로그 객체\n * @property {boolean} [params.logDisabled] 로그 비활성화 여부\n * @returns {string} 완성된 요청 URL\n * @example\n * const url = generateQueryUrl({ domain, routeUrl, queryUrl });\n */\nexport const generateQueryUrl = ({\n  method = \"GET\",\n  domain,\n  routeUrl,\n  queryUrl,\n  searchParams,\n  log,\n  logDisabled,\n}: API_GenerateQueryUrlParams): string => {\n  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;\n\n  if (!logDisabled) {\n    nextAPILog(method, routeUrl, url, {\n      ...(log ?? {}),\n      ...(searchParams ?? {}),\n    });\n  }\n\n  return url;\n};\n\n/**\n * API Request Utils; fetch 요청 옵션 생성\n * @param {API_GetFetchOptionsParams} params 요청 옵션 파라미터\n * @property {string} params.method HTTP method 문자열\n * @property {HeadersInit} [params.headers] 요청 헤더\n * @property {BodyInit | null} [params.body] 요청 body\n * @returns {RequestInit} fetch 요청 옵션 객체\n * @example\n * const option = getFetchOptions({\n *   method: \"POST\",\n *   headers: { \"Content-Type\": \"application/json\" },\n *   body: JSON.stringify({ farm_id: 1 }),\n * });\n */\nexport const getFetchOptions = ({\n  method,\n  headers,\n  body,\n}: API_GetFetchOptionsParams): RequestInit => ({\n  method,\n  ...(typeof headers === \"undefined\" ? {} : { headers }),\n  ...(typeof body === \"undefined\" ? {} : { body }),\n});\n\n/**\n * API Request Utils; body 기반 fetch 요청\n * @template BodyDataType\n * @template ResponseType\n * @param {API_FetchWithBodyParams<BodyDataType, ResponseType>} params 요청 파라미터\n * @property {string} params.domain API 도메인\n * @property {string} params.method HTTP method 문자열\n * @property {string} params.routeUrl frontend route URL\n * @property {string} params.queryUrl backend query URL\n * @property {ResponseType} params.alternateResponse 실패 시 대체 응답\n * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본\n * @property {HeadersInit} [params.headers] fetch headers\n * @property {BodyInit | null} [params.body] fetch body\n * @property {BodyDataType} [params.bodyData] body 데이터\n * @property {boolean} [params.isRawResponse] raw response 반환 여부\n * @property {object} [params.debug] 디버그 로그 객체\n * @property {boolean} [params.disabled] fetch 비활성화 여부\n * @property {boolean} [params.disabledLog] 로그 비활성화 여부\n * @returns {Promise<ResponseType>} 응답 데이터 또는 alternateResponse\n * @example\n * const response = await fetchWithBody({ domain, method: \"POST\", routeUrl, queryUrl, alternateResponse });\n */\nexport const fetchWithBody = async <\n  BodyDataType = object,\n  ResponseType extends object | Response = Response,\n>({\n  domain,\n  method,\n  routeUrl,\n  queryUrl,\n  searchParams,\n  headers,\n  body,\n  bodyData,\n  isRawResponse,\n  alternateResponse,\n  debug,\n  disabled,\n  disabledLog,\n}: API_FetchWithBodyParams<\n  BodyDataType,\n  ResponseType\n>): Promise<ResponseType> => {\n  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;\n  const option = getFetchOptions({ method, headers, body });\n\n  if (!body && typeof bodyData !== \"undefined\") {\n    // 변경: util-functions 공통 유틸을 재사용해 body 직렬화 규칙을 단일화한다.\n    const bodyParams = convertObjectToSearchParams(bodyData).toString();\n    if (bodyParams === \"\") {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: \"ERROR (BODY - DATA)\",\n        error: \"데이터가 유효하지 않습니다.\",\n        bodyData,\n        ...(debug ?? {}),\n      });\n      return alternateResponse;\n    }\n    option.body = bodyData as BodyInit;\n  }\n\n  if (!disabledLog) {\n    nextAPILog(method.toLowerCase(), routeUrl, url, {\n      state: \"READY\",\n      ...option,\n      ...(debug ?? {}),\n    });\n  }\n\n  if (disabled) {\n    nextAPILog(method.toLowerCase(), routeUrl, url, {\n      state: \"FETCH DISABLED\",\n      message: \"API 요청제한 활성화됨.\",\n    });\n    return alternateResponse;\n  }\n\n  try {\n    const responseRaw = await fetch(url, option);\n    const responseCode = responseRaw.status;\n\n    if (!disabledLog) {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: responseCode === 200 ? \"SUCCESS\" : \"FAIL\",\n        code: responseCode,\n      });\n    }\n\n    if (isRawResponse) {\n      return responseRaw as ResponseType;\n    }\n    return (await responseRaw.json()) as ResponseType;\n  } catch (error: unknown) {\n    if (!disabledLog) {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: \"ERROR (RESPONSE)\",\n        error,\n        ...(debug ?? {}),\n      });\n    }\n    return alternateResponse;\n  }\n};\n"]}

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+export { API_Res_Base, API_Res_Error, API_Res_Pagination, API_Res_Status } from './response/index.cjs';
+export { API_FetchWithBodyParams, API_FetchWithBodyResponseFallback, API_GenerateQueryUrlParams, API_GetFetchOptionsParams, fetchWithBody, generateQueryUrl, getFetchOptions, getQueryString, nextAPILog } from './request/index.cjs';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { API_Res_Base, API_Res_Error, API_Res_Pagination, API_Res_Status } from './response/index.js';
+export { API_FetchWithBodyParams, API_FetchWithBodyResponseFallback, API_GenerateQueryUrlParams, API_GetFetchOptionsParams, fetchWithBody, generateQueryUrl, getFetchOptions, getQueryString, nextAPILog } from './request/index.js';

package/dist/index.mjs

@@ -0,0 +1,132 @@
+import { convertObjectToSearchParams } from '@uniai-fe/util-functions';
+
+// src/request/module.ts
+var getQueryString = (searchParams) => {
+  const serialized = convertObjectToSearchParams(searchParams).toString();
+  return serialized ? `?${serialized}` : "";
+};
+var nextAPILog = (method, routeUrl, queryUrl, ...messages) => {
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
+  const date = /* @__PURE__ */ new Date();
+  const dateText = date.toISOString().split("T")[0] ?? "";
+  const timeText = `${date.toLocaleTimeString("en-US", { hour12: false })}.${date.getMilliseconds()}`;
+  const requestMethod = method.split("-")[0]?.toUpperCase() || "-";
+  const responseMethod = method.split("-")[1]?.toUpperCase() || requestMethod;
+  return console.log(
+    `
+`,
+    `[Next Server API] \u23F1 ${dateText} ( ${timeText} )`,
+    `
+  \u03BB [${requestMethod}] FE route`,
+    `
+   ${routeUrl}`,
+    ...queryUrl ? [`
+  \u2550\u23F5 \u03A9 [${responseMethod}] BE url`, `
+   ${queryUrl}`, `
+`] : [],
+    ...messages?.[0] ? [` \u25C7-`, ...messages] : [],
+    `
+`
+  );
+};
+var generateQueryUrl = ({
+  method = "GET",
+  domain,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  log,
+  logDisabled
+}) => {
+  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;
+  if (!logDisabled) {
+    nextAPILog(method, routeUrl, url, {
+      ...log ?? {},
+      ...searchParams ?? {}
+    });
+  }
+  return url;
+};
+var getFetchOptions = ({
+  method,
+  headers,
+  body
+}) => ({
+  method,
+  ...typeof headers === "undefined" ? {} : { headers },
+  ...typeof body === "undefined" ? {} : { body }
+});
+var fetchWithBody = async ({
+  domain,
+  method,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  headers,
+  body,
+  bodyData,
+  isRawResponse,
+  alternateResponse,
+  debug,
+  disabled,
+  disabledLog
+}) => {
+  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;
+  const option = getFetchOptions({ method, headers, body });
+  if (!body && typeof bodyData !== "undefined") {
+    const bodyParams = convertObjectToSearchParams(bodyData).toString();
+    if (bodyParams === "") {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: "ERROR (BODY - DATA)",
+        error: "\uB370\uC774\uD130\uAC00 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+        bodyData,
+        ...debug ?? {}
+      });
+      return alternateResponse;
+    }
+    option.body = bodyData;
+  }
+  if (!disabledLog) {
+    nextAPILog(method.toLowerCase(), routeUrl, url, {
+      state: "READY",
+      ...option,
+      ...debug ?? {}
+    });
+  }
+  if (disabled) {
+    nextAPILog(method.toLowerCase(), routeUrl, url, {
+      state: "FETCH DISABLED",
+      message: "API \uC694\uCCAD\uC81C\uD55C \uD65C\uC131\uD654\uB428."
+    });
+    return alternateResponse;
+  }
+  try {
+    const responseRaw = await fetch(url, option);
+    const responseCode = responseRaw.status;
+    if (!disabledLog) {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: responseCode === 200 ? "SUCCESS" : "FAIL",
+        code: responseCode
+      });
+    }
+    if (isRawResponse) {
+      return responseRaw;
+    }
+    return await responseRaw.json();
+  } catch (error) {
+    if (!disabledLog) {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: "ERROR (RESPONSE)",
+        error,
+        ...debug ?? {}
+      });
+    }
+    return alternateResponse;
+  }
+};
+
+export { fetchWithBody, generateQueryUrl, getFetchOptions, getQueryString, nextAPILog };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/request/module.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import { convertObjectToSearchParams } from \"@uniai-fe/util-functions\";\nimport type {\n  API_FetchWithBodyParams,\n  API_GetFetchOptionsParams,\n  API_GenerateQueryUrlParams,\n} from \"./types\";\n\n/**\n * API Request Utils; 쿼리스트링 생성\n * @param {unknown} [searchParams] 쿼리스트링 변환 대상\n * @returns {string} 직렬화된 쿼리스트링\n * @example\n * const query = getQueryString({ farm_id: 1 });\n */\nexport const getQueryString = (searchParams?: unknown): string => {\n  // 변경: util-functions 공통 유틸을 재사용해 query 변환 규칙을 단일화한다.\n  const serialized = convertObjectToSearchParams(searchParams).toString();\n  return serialized ? `?${serialized}` : \"\";\n};\n\n/**\n * API Request Utils; Next.js route 디버깅 로그 출력\n * @param {string} method HTTP method 문자열\n * @param {string} routeUrl frontend route URL\n * @param {string} [queryUrl] backend query URL\n * @param {unknown[]} messages 로그 메시지\n */\nexport const nextAPILog = (\n  method: string,\n  routeUrl: string,\n  queryUrl?: string,\n  ...messages: unknown[]\n) => {\n  if (process.env.NODE_ENV === \"production\") {\n    return;\n  }\n\n  // 변경: util-api 단독 동작을 위해 날짜 포맷 의존성을 내부 계산으로 대체한다.\n  const date = new Date();\n  const dateText = date.toISOString().split(\"T\")[0] ?? \"\";\n  const timeText = `${date.toLocaleTimeString(\"en-US\", { hour12: false })}.${date.getMilliseconds()}`;\n  const requestMethod = method.split(\"-\")[0]?.toUpperCase() || \"-\";\n  const responseMethod = method.split(\"-\")[1]?.toUpperCase() || requestMethod;\n\n  return console.log(\n    `\\n`,\n    `[Next Server API] ⏱ ${dateText} ( ${timeText} )`,\n    `\\n  λ [${requestMethod}] FE route`,\n    `\\n   ${routeUrl}`,\n    ...(queryUrl\n      ? [`\\n  ═⏵ Ω [${responseMethod}] BE url`, `\\n   ${queryUrl}`, `\\n`]\n      : []),\n    ...(messages?.[0] ? [` ◇-`, ...messages] : []),\n    `\\n`,\n  );\n};\n\n/**\n * API Request Utils; GET API 요청 URL 생성\n * @param {API_GenerateQueryUrlParams} params URL 생성 파라미터\n * @property {string} [params.method] fetch HTTP method\n * @property {string} params.domain API 도메인\n * @property {string} params.routeUrl frontend route URL\n * @property {string} params.queryUrl backend query URL\n * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본\n * @property {object} [params.log] 디버깅 로그 객체\n * @property {boolean} [params.logDisabled] 로그 비활성화 여부\n * @returns {string} 완성된 요청 URL\n * @example\n * const url = generateQueryUrl({ domain, routeUrl, queryUrl });\n */\nexport const generateQueryUrl = ({\n  method = \"GET\",\n  domain,\n  routeUrl,\n  queryUrl,\n  searchParams,\n  log,\n  logDisabled,\n}: API_GenerateQueryUrlParams): string => {\n  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;\n\n  if (!logDisabled) {\n    nextAPILog(method, routeUrl, url, {\n      ...(log ?? {}),\n      ...(searchParams ?? {}),\n    });\n  }\n\n  return url;\n};\n\n/**\n * API Request Utils; fetch 요청 옵션 생성\n * @param {API_GetFetchOptionsParams} params 요청 옵션 파라미터\n * @property {string} params.method HTTP method 문자열\n * @property {HeadersInit} [params.headers] 요청 헤더\n * @property {BodyInit | null} [params.body] 요청 body\n * @returns {RequestInit} fetch 요청 옵션 객체\n * @example\n * const option = getFetchOptions({\n *   method: \"POST\",\n *   headers: { \"Content-Type\": \"application/json\" },\n *   body: JSON.stringify({ farm_id: 1 }),\n * });\n */\nexport const getFetchOptions = ({\n  method,\n  headers,\n  body,\n}: API_GetFetchOptionsParams): RequestInit => ({\n  method,\n  ...(typeof headers === \"undefined\" ? {} : { headers }),\n  ...(typeof body === \"undefined\" ? {} : { body }),\n});\n\n/**\n * API Request Utils; body 기반 fetch 요청\n * @template BodyDataType\n * @template ResponseType\n * @param {API_FetchWithBodyParams<BodyDataType, ResponseType>} params 요청 파라미터\n * @property {string} params.domain API 도메인\n * @property {string} params.method HTTP method 문자열\n * @property {string} params.routeUrl frontend route URL\n * @property {string} params.queryUrl backend query URL\n * @property {ResponseType} params.alternateResponse 실패 시 대체 응답\n * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본\n * @property {HeadersInit} [params.headers] fetch headers\n * @property {BodyInit | null} [params.body] fetch body\n * @property {BodyDataType} [params.bodyData] body 데이터\n * @property {boolean} [params.isRawResponse] raw response 반환 여부\n * @property {object} [params.debug] 디버그 로그 객체\n * @property {boolean} [params.disabled] fetch 비활성화 여부\n * @property {boolean} [params.disabledLog] 로그 비활성화 여부\n * @returns {Promise<ResponseType>} 응답 데이터 또는 alternateResponse\n * @example\n * const response = await fetchWithBody({ domain, method: \"POST\", routeUrl, queryUrl, alternateResponse });\n */\nexport const fetchWithBody = async <\n  BodyDataType = object,\n  ResponseType extends object | Response = Response,\n>({\n  domain,\n  method,\n  routeUrl,\n  queryUrl,\n  searchParams,\n  headers,\n  body,\n  bodyData,\n  isRawResponse,\n  alternateResponse,\n  debug,\n  disabled,\n  disabledLog,\n}: API_FetchWithBodyParams<\n  BodyDataType,\n  ResponseType\n>): Promise<ResponseType> => {\n  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;\n  const option = getFetchOptions({ method, headers, body });\n\n  if (!body && typeof bodyData !== \"undefined\") {\n    // 변경: util-functions 공통 유틸을 재사용해 body 직렬화 규칙을 단일화한다.\n    const bodyParams = convertObjectToSearchParams(bodyData).toString();\n    if (bodyParams === \"\") {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: \"ERROR (BODY - DATA)\",\n        error: \"데이터가 유효하지 않습니다.\",\n        bodyData,\n        ...(debug ?? {}),\n      });\n      return alternateResponse;\n    }\n    option.body = bodyData as BodyInit;\n  }\n\n  if (!disabledLog) {\n    nextAPILog(method.toLowerCase(), routeUrl, url, {\n      state: \"READY\",\n      ...option,\n      ...(debug ?? {}),\n    });\n  }\n\n  if (disabled) {\n    nextAPILog(method.toLowerCase(), routeUrl, url, {\n      state: \"FETCH DISABLED\",\n      message: \"API 요청제한 활성화됨.\",\n    });\n    return alternateResponse;\n  }\n\n  try {\n    const responseRaw = await fetch(url, option);\n    const responseCode = responseRaw.status;\n\n    if (!disabledLog) {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: responseCode === 200 ? \"SUCCESS\" : \"FAIL\",\n        code: responseCode,\n      });\n    }\n\n    if (isRawResponse) {\n      return responseRaw as ResponseType;\n    }\n    return (await responseRaw.json()) as ResponseType;\n  } catch (error: unknown) {\n    if (!disabledLog) {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: \"ERROR (RESPONSE)\",\n        error,\n        ...(debug ?? {}),\n      });\n    }\n    return alternateResponse;\n  }\n};\n"]}

package/dist/request/index.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+var utilFunctions = require('@uniai-fe/util-functions');
+
+// src/request/module.ts
+var getQueryString = (searchParams) => {
+  const serialized = utilFunctions.convertObjectToSearchParams(searchParams).toString();
+  return serialized ? `?${serialized}` : "";
+};
+var nextAPILog = (method, routeUrl, queryUrl, ...messages) => {
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
+  const date = /* @__PURE__ */ new Date();
+  const dateText = date.toISOString().split("T")[0] ?? "";
+  const timeText = `${date.toLocaleTimeString("en-US", { hour12: false })}.${date.getMilliseconds()}`;
+  const requestMethod = method.split("-")[0]?.toUpperCase() || "-";
+  const responseMethod = method.split("-")[1]?.toUpperCase() || requestMethod;
+  return console.log(
+    `
+`,
+    `[Next Server API] \u23F1 ${dateText} ( ${timeText} )`,
+    `
+  \u03BB [${requestMethod}] FE route`,
+    `
+   ${routeUrl}`,
+    ...queryUrl ? [`
+  \u2550\u23F5 \u03A9 [${responseMethod}] BE url`, `
+   ${queryUrl}`, `
+`] : [],
+    ...messages?.[0] ? [` \u25C7-`, ...messages] : [],
+    `
+`
+  );
+};
+var generateQueryUrl = ({
+  method = "GET",
+  domain,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  log,
+  logDisabled
+}) => {
+  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;
+  if (!logDisabled) {
+    nextAPILog(method, routeUrl, url, {
+      ...log ?? {},
+      ...searchParams ?? {}
+    });
+  }
+  return url;
+};
+var getFetchOptions = ({
+  method,
+  headers,
+  body
+}) => ({
+  method,
+  ...typeof headers === "undefined" ? {} : { headers },
+  ...typeof body === "undefined" ? {} : { body }
+});
+var fetchWithBody = async ({
+  domain,
+  method,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  headers,
+  body,
+  bodyData,
+  isRawResponse,
+  alternateResponse,
+  debug,
+  disabled,
+  disabledLog
+}) => {
+  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;
+  const option = getFetchOptions({ method, headers, body });
+  if (!body && typeof bodyData !== "undefined") {
+    const bodyParams = utilFunctions.convertObjectToSearchParams(bodyData).toString();
+    if (bodyParams === "") {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: "ERROR (BODY - DATA)",
+        error: "\uB370\uC774\uD130\uAC00 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+        bodyData,
+        ...debug ?? {}
+      });
+      return alternateResponse;
+    }
+    option.body = bodyData;
+  }
+  if (!disabledLog) {
+    nextAPILog(method.toLowerCase(), routeUrl, url, {
+      state: "READY",
+      ...option,
+      ...debug ?? {}
+    });
+  }
+  if (disabled) {
+    nextAPILog(method.toLowerCase(), routeUrl, url, {
+      state: "FETCH DISABLED",
+      message: "API \uC694\uCCAD\uC81C\uD55C \uD65C\uC131\uD654\uB428."
+    });
+    return alternateResponse;
+  }
+  try {
+    const responseRaw = await fetch(url, option);
+    const responseCode = responseRaw.status;
+    if (!disabledLog) {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: responseCode === 200 ? "SUCCESS" : "FAIL",
+        code: responseCode
+      });
+    }
+    if (isRawResponse) {
+      return responseRaw;
+    }
+    return await responseRaw.json();
+  } catch (error) {
+    if (!disabledLog) {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: "ERROR (RESPONSE)",
+        error,
+        ...debug ?? {}
+      });
+    }
+    return alternateResponse;
+  }
+};
+
+exports.fetchWithBody = fetchWithBody;
+exports.generateQueryUrl = generateQueryUrl;
+exports.getFetchOptions = getFetchOptions;
+exports.getQueryString = getQueryString;
+exports.nextAPILog = nextAPILog;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/request/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/request/module.ts"],"names":["convertObjectToSearchParams"],"mappings":"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","file":"index.cjs","sourcesContent":["import { convertObjectToSearchParams } from \"@uniai-fe/util-functions\";\nimport type {\n  API_FetchWithBodyParams,\n  API_GetFetchOptionsParams,\n  API_GenerateQueryUrlParams,\n} from \"./types\";\n\n/**\n * API Request Utils; 쿼리스트링 생성\n * @param {unknown} [searchParams] 쿼리스트링 변환 대상\n * @returns {string} 직렬화된 쿼리스트링\n * @example\n * const query = getQueryString({ farm_id: 1 });\n */\nexport const getQueryString = (searchParams?: unknown): string => {\n  // 변경: util-functions 공통 유틸을 재사용해 query 변환 규칙을 단일화한다.\n  const serialized = convertObjectToSearchParams(searchParams).toString();\n  return serialized ? `?${serialized}` : \"\";\n};\n\n/**\n * API Request Utils; Next.js route 디버깅 로그 출력\n * @param {string} method HTTP method 문자열\n * @param {string} routeUrl frontend route URL\n * @param {string} [queryUrl] backend query URL\n * @param {unknown[]} messages 로그 메시지\n */\nexport const nextAPILog = (\n  method: string,\n  routeUrl: string,\n  queryUrl?: string,\n  ...messages: unknown[]\n) => {\n  if (process.env.NODE_ENV === \"production\") {\n    return;\n  }\n\n  // 변경: util-api 단독 동작을 위해 날짜 포맷 의존성을 내부 계산으로 대체한다.\n  const date = new Date();\n  const dateText = date.toISOString().split(\"T\")[0] ?? \"\";\n  const timeText = `${date.toLocaleTimeString(\"en-US\", { hour12: false })}.${date.getMilliseconds()}`;\n  const requestMethod = method.split(\"-\")[0]?.toUpperCase() || \"-\";\n  const responseMethod = method.split(\"-\")[1]?.toUpperCase() || requestMethod;\n\n  return console.log(\n    `\\n`,\n    `[Next Server API] ⏱ ${dateText} ( ${timeText} )`,\n    `\\n  λ [${requestMethod}] FE route`,\n    `\\n   ${routeUrl}`,\n    ...(queryUrl\n      ? [`\\n  ═⏵ Ω [${responseMethod}] BE url`, `\\n   ${queryUrl}`, `\\n`]\n      : []),\n    ...(messages?.[0] ? [` ◇-`, ...messages] : []),\n    `\\n`,\n  );\n};\n\n/**\n * API Request Utils; GET API 요청 URL 생성\n * @param {API_GenerateQueryUrlParams} params URL 생성 파라미터\n * @property {string} [params.method] fetch HTTP method\n * @property {string} params.domain API 도메인\n * @property {string} params.routeUrl frontend route URL\n * @property {string} params.queryUrl backend query URL\n * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본\n * @property {object} [params.log] 디버깅 로그 객체\n * @property {boolean} [params.logDisabled] 로그 비활성화 여부\n * @returns {string} 완성된 요청 URL\n * @example\n * const url = generateQueryUrl({ domain, routeUrl, queryUrl });\n */\nexport const generateQueryUrl = ({\n  method = \"GET\",\n  domain,\n  routeUrl,\n  queryUrl,\n  searchParams,\n  log,\n  logDisabled,\n}: API_GenerateQueryUrlParams): string => {\n  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;\n\n  if (!logDisabled) {\n    nextAPILog(method, routeUrl, url, {\n      ...(log ?? {}),\n      ...(searchParams ?? {}),\n    });\n  }\n\n  return url;\n};\n\n/**\n * API Request Utils; fetch 요청 옵션 생성\n * @param {API_GetFetchOptionsParams} params 요청 옵션 파라미터\n * @property {string} params.method HTTP method 문자열\n * @property {HeadersInit} [params.headers] 요청 헤더\n * @property {BodyInit | null} [params.body] 요청 body\n * @returns {RequestInit} fetch 요청 옵션 객체\n * @example\n * const option = getFetchOptions({\n *   method: \"POST\",\n *   headers: { \"Content-Type\": \"application/json\" },\n *   body: JSON.stringify({ farm_id: 1 }),\n * });\n */\nexport const getFetchOptions = ({\n  method,\n  headers,\n  body,\n}: API_GetFetchOptionsParams): RequestInit => ({\n  method,\n  ...(typeof headers === \"undefined\" ? {} : { headers }),\n  ...(typeof body === \"undefined\" ? {} : { body }),\n});\n\n/**\n * API Request Utils; body 기반 fetch 요청\n * @template BodyDataType\n * @template ResponseType\n * @param {API_FetchWithBodyParams<BodyDataType, ResponseType>} params 요청 파라미터\n * @property {string} params.domain API 도메인\n * @property {string} params.method HTTP method 문자열\n * @property {string} params.routeUrl frontend route URL\n * @property {string} params.queryUrl backend query URL\n * @property {ResponseType} params.alternateResponse 실패 시 대체 응답\n * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본\n * @property {HeadersInit} [params.headers] fetch headers\n * @property {BodyInit | null} [params.body] fetch body\n * @property {BodyDataType} [params.bodyData] body 데이터\n * @property {boolean} [params.isRawResponse] raw response 반환 여부\n * @property {object} [params.debug] 디버그 로그 객체\n * @property {boolean} [params.disabled] fetch 비활성화 여부\n * @property {boolean} [params.disabledLog] 로그 비활성화 여부\n * @returns {Promise<ResponseType>} 응답 데이터 또는 alternateResponse\n * @example\n * const response = await fetchWithBody({ domain, method: \"POST\", routeUrl, queryUrl, alternateResponse });\n */\nexport const fetchWithBody = async <\n  BodyDataType = object,\n  ResponseType extends object | Response = Response,\n>({\n  domain,\n  method,\n  routeUrl,\n  queryUrl,\n  searchParams,\n  headers,\n  body,\n  bodyData,\n  isRawResponse,\n  alternateResponse,\n  debug,\n  disabled,\n  disabledLog,\n}: API_FetchWithBodyParams<\n  BodyDataType,\n  ResponseType\n>): Promise<ResponseType> => {\n  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;\n  const option = getFetchOptions({ method, headers, body });\n\n  if (!body && typeof bodyData !== \"undefined\") {\n    // 변경: util-functions 공통 유틸을 재사용해 body 직렬화 규칙을 단일화한다.\n    const bodyParams = convertObjectToSearchParams(bodyData).toString();\n    if (bodyParams === \"\") {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: \"ERROR (BODY - DATA)\",\n        error: \"데이터가 유효하지 않습니다.\",\n        bodyData,\n        ...(debug ?? {}),\n      });\n      return alternateResponse;\n    }\n    option.body = bodyData as BodyInit;\n  }\n\n  if (!disabledLog) {\n    nextAPILog(method.toLowerCase(), routeUrl, url, {\n      state: \"READY\",\n      ...option,\n      ...(debug ?? {}),\n    });\n  }\n\n  if (disabled) {\n    nextAPILog(method.toLowerCase(), routeUrl, url, {\n      state: \"FETCH DISABLED\",\n      message: \"API 요청제한 활성화됨.\",\n    });\n    return alternateResponse;\n  }\n\n  try {\n    const responseRaw = await fetch(url, option);\n    const responseCode = responseRaw.status;\n\n    if (!disabledLog) {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: responseCode === 200 ? \"SUCCESS\" : \"FAIL\",\n        code: responseCode,\n      });\n    }\n\n    if (isRawResponse) {\n      return responseRaw as ResponseType;\n    }\n    return (await responseRaw.json()) as ResponseType;\n  } catch (error: unknown) {\n    if (!disabledLog) {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: \"ERROR (RESPONSE)\",\n        error,\n        ...(debug ?? {}),\n      });\n    }\n    return alternateResponse;\n  }\n};\n"]}

package/dist/request/index.d.cts

@@ -0,0 +1,212 @@
+import { API_Res_Base } from '../response/index.cjs';
+
+/**
+ * API Request Types; GET URL 생성 파라미터
+ * @property {string} [method] fetch HTTP method
+ * @property {string} domain API 도메인
+ * @property {string} routeUrl frontend route URL
+ * @property {string} queryUrl backend query URL
+ * @property {URLSearchParams | object} [searchParams] 쿼리스트링 원본
+ * @property {object} [log] 디버깅 로그 객체
+ * @property {boolean} [logDisabled] 로그 비활성화 여부
+ */
+interface API_GenerateQueryUrlParams {
+    /**
+     * fetch HTTP method
+     */
+    method?: string;
+    /**
+     * API 도메인
+     */
+    domain: string;
+    /**
+     * frontend route URL
+     */
+    routeUrl: string;
+    /**
+     * backend query URL
+     */
+    queryUrl: string;
+    /**
+     * 쿼리스트링 원본
+     */
+    searchParams?: URLSearchParams | object;
+    /**
+     * 디버깅 로그 객체
+     */
+    log?: object;
+    /**
+     * 로그 비활성화 여부
+     */
+    logDisabled?: boolean;
+}
+/**
+ * API Request Types; body 기반 fetch 파라미터
+ * @template BodyDataType
+ * @template ResponseType
+ * @property {string} domain API 도메인
+ * @property {string} method HTTP method 문자열
+ * @property {string} routeUrl frontend route URL
+ * @property {string} queryUrl backend query URL
+ * @property {ResponseType} alternateResponse 실패 시 대체 응답
+ * @property {URLSearchParams | object} [searchParams] 쿼리스트링 원본
+ * @property {HeadersInit} [headers] fetch headers
+ * @property {BodyInit | null} [body] fetch body
+ * @property {BodyDataType} [bodyData] body 데이터
+ * @property {boolean} [isRawResponse] raw response 반환 여부
+ * @property {object} [debug] 디버그 로그 객체
+ * @property {boolean} [disabled] fetch 비활성화 여부
+ * @property {boolean} [disabledLog] 로그 비활성화 여부
+ */
+interface API_FetchWithBodyParams<BodyDataType = object, ResponseType extends object | Response = Response> {
+    /**
+     * API 도메인
+     */
+    domain: string;
+    /**
+     * HTTP method 문자열
+     */
+    method: string;
+    /**
+     * frontend route URL
+     */
+    routeUrl: string;
+    /**
+     * backend query URL
+     */
+    queryUrl: string;
+    /**
+     * 실패 시 대체 응답
+     */
+    alternateResponse: ResponseType;
+    /**
+     * 쿼리스트링 원본
+     */
+    searchParams?: URLSearchParams | object;
+    /**
+     * fetch headers
+     */
+    headers?: HeadersInit;
+    /**
+     * fetch body
+     */
+    body?: BodyInit | null;
+    /**
+     * body 데이터
+     */
+    bodyData?: BodyDataType;
+    /**
+     * raw response 반환 여부
+     */
+    isRawResponse?: boolean;
+    /**
+     * 디버그 로그 객체
+     */
+    debug?: object;
+    /**
+     * fetch 비활성화 여부
+     */
+    disabled?: boolean;
+    /**
+     * 로그 비활성화 여부
+     */
+    disabledLog?: boolean;
+}
+/**
+ * API Request Types; body 기반 fetch 응답 fallback 타입
+ * @example
+ * type FileDeleteResponse = API_FetchWithBodyResponseFallback<boolean | null>;
+ */
+type API_FetchWithBodyResponseFallback<ResponseDataType> = API_Res_Base<ResponseDataType>;
+/**
+ * API Request Types; fetch 옵션 생성 파라미터
+ * @property {string} method HTTP method 문자열
+ * @property {HeadersInit} [headers] 요청 헤더
+ * @property {BodyInit | null} [body] 요청 body
+ */
+interface API_GetFetchOptionsParams {
+    /**
+     * HTTP method 문자열
+     */
+    method: string;
+    /**
+     * 요청 헤더
+     */
+    headers?: HeadersInit;
+    /**
+     * 요청 body
+     */
+    body?: BodyInit | null;
+}
+
+/**
+ * API Request Utils; 쿼리스트링 생성
+ * @param {unknown} [searchParams] 쿼리스트링 변환 대상
+ * @returns {string} 직렬화된 쿼리스트링
+ * @example
+ * const query = getQueryString({ farm_id: 1 });
+ */
+declare const getQueryString: (searchParams?: unknown) => string;
+/**
+ * API Request Utils; Next.js route 디버깅 로그 출력
+ * @param {string} method HTTP method 문자열
+ * @param {string} routeUrl frontend route URL
+ * @param {string} [queryUrl] backend query URL
+ * @param {unknown[]} messages 로그 메시지
+ */
+declare const nextAPILog: (method: string, routeUrl: string, queryUrl?: string, ...messages: unknown[]) => void;
+/**
+ * API Request Utils; GET API 요청 URL 생성
+ * @param {API_GenerateQueryUrlParams} params URL 생성 파라미터
+ * @property {string} [params.method] fetch HTTP method
+ * @property {string} params.domain API 도메인
+ * @property {string} params.routeUrl frontend route URL
+ * @property {string} params.queryUrl backend query URL
+ * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본
+ * @property {object} [params.log] 디버깅 로그 객체
+ * @property {boolean} [params.logDisabled] 로그 비활성화 여부
+ * @returns {string} 완성된 요청 URL
+ * @example
+ * const url = generateQueryUrl({ domain, routeUrl, queryUrl });
+ */
+declare const generateQueryUrl: ({ method, domain, routeUrl, queryUrl, searchParams, log, logDisabled, }: API_GenerateQueryUrlParams) => string;
+/**
+ * API Request Utils; fetch 요청 옵션 생성
+ * @param {API_GetFetchOptionsParams} params 요청 옵션 파라미터
+ * @property {string} params.method HTTP method 문자열
+ * @property {HeadersInit} [params.headers] 요청 헤더
+ * @property {BodyInit | null} [params.body] 요청 body
+ * @returns {RequestInit} fetch 요청 옵션 객체
+ * @example
+ * const option = getFetchOptions({
+ *   method: "POST",
+ *   headers: { "Content-Type": "application/json" },
+ *   body: JSON.stringify({ farm_id: 1 }),
+ * });
+ */
+declare const getFetchOptions: ({ method, headers, body, }: API_GetFetchOptionsParams) => RequestInit;
+/**
+ * API Request Utils; body 기반 fetch 요청
+ * @template BodyDataType
+ * @template ResponseType
+ * @param {API_FetchWithBodyParams<BodyDataType, ResponseType>} params 요청 파라미터
+ * @property {string} params.domain API 도메인
+ * @property {string} params.method HTTP method 문자열
+ * @property {string} params.routeUrl frontend route URL
+ * @property {string} params.queryUrl backend query URL
+ * @property {ResponseType} params.alternateResponse 실패 시 대체 응답
+ * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본
+ * @property {HeadersInit} [params.headers] fetch headers
+ * @property {BodyInit | null} [params.body] fetch body
+ * @property {BodyDataType} [params.bodyData] body 데이터
+ * @property {boolean} [params.isRawResponse] raw response 반환 여부
+ * @property {object} [params.debug] 디버그 로그 객체
+ * @property {boolean} [params.disabled] fetch 비활성화 여부
+ * @property {boolean} [params.disabledLog] 로그 비활성화 여부
+ * @returns {Promise<ResponseType>} 응답 데이터 또는 alternateResponse
+ * @example
+ * const response = await fetchWithBody({ domain, method: "POST", routeUrl, queryUrl, alternateResponse });
+ */
+declare const fetchWithBody: <BodyDataType = object, ResponseType extends object | Response = Response>({ domain, method, routeUrl, queryUrl, searchParams, headers, body, bodyData, isRawResponse, alternateResponse, debug, disabled, disabledLog, }: API_FetchWithBodyParams<BodyDataType, ResponseType>) => Promise<ResponseType>;
+
+export { type API_FetchWithBodyParams, type API_FetchWithBodyResponseFallback, type API_GenerateQueryUrlParams, type API_GetFetchOptionsParams, fetchWithBody, generateQueryUrl, getFetchOptions, getQueryString, nextAPILog };

package/dist/request/index.d.ts

@@ -0,0 +1,212 @@
+import { API_Res_Base } from '../response/index.js';
+
+/**
+ * API Request Types; GET URL 생성 파라미터
+ * @property {string} [method] fetch HTTP method
+ * @property {string} domain API 도메인
+ * @property {string} routeUrl frontend route URL
+ * @property {string} queryUrl backend query URL
+ * @property {URLSearchParams | object} [searchParams] 쿼리스트링 원본
+ * @property {object} [log] 디버깅 로그 객체
+ * @property {boolean} [logDisabled] 로그 비활성화 여부
+ */
+interface API_GenerateQueryUrlParams {
+    /**
+     * fetch HTTP method
+     */
+    method?: string;
+    /**
+     * API 도메인
+     */
+    domain: string;
+    /**
+     * frontend route URL
+     */
+    routeUrl: string;
+    /**
+     * backend query URL
+     */
+    queryUrl: string;
+    /**
+     * 쿼리스트링 원본
+     */
+    searchParams?: URLSearchParams | object;
+    /**
+     * 디버깅 로그 객체
+     */
+    log?: object;
+    /**
+     * 로그 비활성화 여부
+     */
+    logDisabled?: boolean;
+}
+/**
+ * API Request Types; body 기반 fetch 파라미터
+ * @template BodyDataType
+ * @template ResponseType
+ * @property {string} domain API 도메인
+ * @property {string} method HTTP method 문자열
+ * @property {string} routeUrl frontend route URL
+ * @property {string} queryUrl backend query URL
+ * @property {ResponseType} alternateResponse 실패 시 대체 응답
+ * @property {URLSearchParams | object} [searchParams] 쿼리스트링 원본
+ * @property {HeadersInit} [headers] fetch headers
+ * @property {BodyInit | null} [body] fetch body
+ * @property {BodyDataType} [bodyData] body 데이터
+ * @property {boolean} [isRawResponse] raw response 반환 여부
+ * @property {object} [debug] 디버그 로그 객체
+ * @property {boolean} [disabled] fetch 비활성화 여부
+ * @property {boolean} [disabledLog] 로그 비활성화 여부
+ */
+interface API_FetchWithBodyParams<BodyDataType = object, ResponseType extends object | Response = Response> {
+    /**
+     * API 도메인
+     */
+    domain: string;
+    /**
+     * HTTP method 문자열
+     */
+    method: string;
+    /**
+     * frontend route URL
+     */
+    routeUrl: string;
+    /**
+     * backend query URL
+     */
+    queryUrl: string;
+    /**
+     * 실패 시 대체 응답
+     */
+    alternateResponse: ResponseType;
+    /**
+     * 쿼리스트링 원본
+     */
+    searchParams?: URLSearchParams | object;
+    /**
+     * fetch headers
+     */
+    headers?: HeadersInit;
+    /**
+     * fetch body
+     */
+    body?: BodyInit | null;
+    /**
+     * body 데이터
+     */
+    bodyData?: BodyDataType;
+    /**
+     * raw response 반환 여부
+     */
+    isRawResponse?: boolean;
+    /**
+     * 디버그 로그 객체
+     */
+    debug?: object;
+    /**
+     * fetch 비활성화 여부
+     */
+    disabled?: boolean;
+    /**
+     * 로그 비활성화 여부
+     */
+    disabledLog?: boolean;
+}
+/**
+ * API Request Types; body 기반 fetch 응답 fallback 타입
+ * @example
+ * type FileDeleteResponse = API_FetchWithBodyResponseFallback<boolean | null>;
+ */
+type API_FetchWithBodyResponseFallback<ResponseDataType> = API_Res_Base<ResponseDataType>;
+/**
+ * API Request Types; fetch 옵션 생성 파라미터
+ * @property {string} method HTTP method 문자열
+ * @property {HeadersInit} [headers] 요청 헤더
+ * @property {BodyInit | null} [body] 요청 body
+ */
+interface API_GetFetchOptionsParams {
+    /**
+     * HTTP method 문자열
+     */
+    method: string;
+    /**
+     * 요청 헤더
+     */
+    headers?: HeadersInit;
+    /**
+     * 요청 body
+     */
+    body?: BodyInit | null;
+}
+
+/**
+ * API Request Utils; 쿼리스트링 생성
+ * @param {unknown} [searchParams] 쿼리스트링 변환 대상
+ * @returns {string} 직렬화된 쿼리스트링
+ * @example
+ * const query = getQueryString({ farm_id: 1 });
+ */
+declare const getQueryString: (searchParams?: unknown) => string;
+/**
+ * API Request Utils; Next.js route 디버깅 로그 출력
+ * @param {string} method HTTP method 문자열
+ * @param {string} routeUrl frontend route URL
+ * @param {string} [queryUrl] backend query URL
+ * @param {unknown[]} messages 로그 메시지
+ */
+declare const nextAPILog: (method: string, routeUrl: string, queryUrl?: string, ...messages: unknown[]) => void;
+/**
+ * API Request Utils; GET API 요청 URL 생성
+ * @param {API_GenerateQueryUrlParams} params URL 생성 파라미터
+ * @property {string} [params.method] fetch HTTP method
+ * @property {string} params.domain API 도메인
+ * @property {string} params.routeUrl frontend route URL
+ * @property {string} params.queryUrl backend query URL
+ * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본
+ * @property {object} [params.log] 디버깅 로그 객체
+ * @property {boolean} [params.logDisabled] 로그 비활성화 여부
+ * @returns {string} 완성된 요청 URL
+ * @example
+ * const url = generateQueryUrl({ domain, routeUrl, queryUrl });
+ */
+declare const generateQueryUrl: ({ method, domain, routeUrl, queryUrl, searchParams, log, logDisabled, }: API_GenerateQueryUrlParams) => string;
+/**
+ * API Request Utils; fetch 요청 옵션 생성
+ * @param {API_GetFetchOptionsParams} params 요청 옵션 파라미터
+ * @property {string} params.method HTTP method 문자열
+ * @property {HeadersInit} [params.headers] 요청 헤더
+ * @property {BodyInit | null} [params.body] 요청 body
+ * @returns {RequestInit} fetch 요청 옵션 객체
+ * @example
+ * const option = getFetchOptions({
+ *   method: "POST",
+ *   headers: { "Content-Type": "application/json" },
+ *   body: JSON.stringify({ farm_id: 1 }),
+ * });
+ */
+declare const getFetchOptions: ({ method, headers, body, }: API_GetFetchOptionsParams) => RequestInit;
+/**
+ * API Request Utils; body 기반 fetch 요청
+ * @template BodyDataType
+ * @template ResponseType
+ * @param {API_FetchWithBodyParams<BodyDataType, ResponseType>} params 요청 파라미터
+ * @property {string} params.domain API 도메인
+ * @property {string} params.method HTTP method 문자열
+ * @property {string} params.routeUrl frontend route URL
+ * @property {string} params.queryUrl backend query URL
+ * @property {ResponseType} params.alternateResponse 실패 시 대체 응답
+ * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본
+ * @property {HeadersInit} [params.headers] fetch headers
+ * @property {BodyInit | null} [params.body] fetch body
+ * @property {BodyDataType} [params.bodyData] body 데이터
+ * @property {boolean} [params.isRawResponse] raw response 반환 여부
+ * @property {object} [params.debug] 디버그 로그 객체
+ * @property {boolean} [params.disabled] fetch 비활성화 여부
+ * @property {boolean} [params.disabledLog] 로그 비활성화 여부
+ * @returns {Promise<ResponseType>} 응답 데이터 또는 alternateResponse
+ * @example
+ * const response = await fetchWithBody({ domain, method: "POST", routeUrl, queryUrl, alternateResponse });
+ */
+declare const fetchWithBody: <BodyDataType = object, ResponseType extends object | Response = Response>({ domain, method, routeUrl, queryUrl, searchParams, headers, body, bodyData, isRawResponse, alternateResponse, debug, disabled, disabledLog, }: API_FetchWithBodyParams<BodyDataType, ResponseType>) => Promise<ResponseType>;
+
+export { type API_FetchWithBodyParams, type API_FetchWithBodyResponseFallback, type API_GenerateQueryUrlParams, type API_GetFetchOptionsParams, fetchWithBody, generateQueryUrl, getFetchOptions, getQueryString, nextAPILog };

package/dist/request/index.mjs

@@ -0,0 +1,132 @@
+import { convertObjectToSearchParams } from '@uniai-fe/util-functions';
+
+// src/request/module.ts
+var getQueryString = (searchParams) => {
+  const serialized = convertObjectToSearchParams(searchParams).toString();
+  return serialized ? `?${serialized}` : "";
+};
+var nextAPILog = (method, routeUrl, queryUrl, ...messages) => {
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
+  const date = /* @__PURE__ */ new Date();
+  const dateText = date.toISOString().split("T")[0] ?? "";
+  const timeText = `${date.toLocaleTimeString("en-US", { hour12: false })}.${date.getMilliseconds()}`;
+  const requestMethod = method.split("-")[0]?.toUpperCase() || "-";
+  const responseMethod = method.split("-")[1]?.toUpperCase() || requestMethod;
+  return console.log(
+    `
+`,
+    `[Next Server API] \u23F1 ${dateText} ( ${timeText} )`,
+    `
+  \u03BB [${requestMethod}] FE route`,
+    `
+   ${routeUrl}`,
+    ...queryUrl ? [`
+  \u2550\u23F5 \u03A9 [${responseMethod}] BE url`, `
+   ${queryUrl}`, `
+`] : [],
+    ...messages?.[0] ? [` \u25C7-`, ...messages] : [],
+    `
+`
+  );
+};
+var generateQueryUrl = ({
+  method = "GET",
+  domain,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  log,
+  logDisabled
+}) => {
+  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;
+  if (!logDisabled) {
+    nextAPILog(method, routeUrl, url, {
+      ...log ?? {},
+      ...searchParams ?? {}
+    });
+  }
+  return url;
+};
+var getFetchOptions = ({
+  method,
+  headers,
+  body
+}) => ({
+  method,
+  ...typeof headers === "undefined" ? {} : { headers },
+  ...typeof body === "undefined" ? {} : { body }
+});
+var fetchWithBody = async ({
+  domain,
+  method,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  headers,
+  body,
+  bodyData,
+  isRawResponse,
+  alternateResponse,
+  debug,
+  disabled,
+  disabledLog
+}) => {
+  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;
+  const option = getFetchOptions({ method, headers, body });
+  if (!body && typeof bodyData !== "undefined") {
+    const bodyParams = convertObjectToSearchParams(bodyData).toString();
+    if (bodyParams === "") {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: "ERROR (BODY - DATA)",
+        error: "\uB370\uC774\uD130\uAC00 \uC720\uD6A8\uD558\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4.",
+        bodyData,
+        ...debug ?? {}
+      });
+      return alternateResponse;
+    }
+    option.body = bodyData;
+  }
+  if (!disabledLog) {
+    nextAPILog(method.toLowerCase(), routeUrl, url, {
+      state: "READY",
+      ...option,
+      ...debug ?? {}
+    });
+  }
+  if (disabled) {
+    nextAPILog(method.toLowerCase(), routeUrl, url, {
+      state: "FETCH DISABLED",
+      message: "API \uC694\uCCAD\uC81C\uD55C \uD65C\uC131\uD654\uB428."
+    });
+    return alternateResponse;
+  }
+  try {
+    const responseRaw = await fetch(url, option);
+    const responseCode = responseRaw.status;
+    if (!disabledLog) {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: responseCode === 200 ? "SUCCESS" : "FAIL",
+        code: responseCode
+      });
+    }
+    if (isRawResponse) {
+      return responseRaw;
+    }
+    return await responseRaw.json();
+  } catch (error) {
+    if (!disabledLog) {
+      nextAPILog(method.toLowerCase(), routeUrl, url, {
+        state: "ERROR (RESPONSE)",
+        error,
+        ...debug ?? {}
+      });
+    }
+    return alternateResponse;
+  }
+};
+
+export { fetchWithBody, generateQueryUrl, getFetchOptions, getQueryString, nextAPILog };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/request/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/request/module.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["import { convertObjectToSearchParams } from \"@uniai-fe/util-functions\";\nimport type {\n  API_FetchWithBodyParams,\n  API_GetFetchOptionsParams,\n  API_GenerateQueryUrlParams,\n} from \"./types\";\n\n/**\n * API Request Utils; 쿼리스트링 생성\n * @param {unknown} [searchParams] 쿼리스트링 변환 대상\n * @returns {string} 직렬화된 쿼리스트링\n * @example\n * const query = getQueryString({ farm_id: 1 });\n */\nexport const getQueryString = (searchParams?: unknown): string => {\n  // 변경: util-functions 공통 유틸을 재사용해 query 변환 규칙을 단일화한다.\n  const serialized = convertObjectToSearchParams(searchParams).toString();\n  return serialized ? `?${serialized}` : \"\";\n};\n\n/**\n * API Request Utils; Next.js route 디버깅 로그 출력\n * @param {string} method HTTP method 문자열\n * @param {string} routeUrl frontend route URL\n * @param {string} [queryUrl] backend query URL\n * @param {unknown[]} messages 로그 메시지\n */\nexport const nextAPILog = (\n  method: string,\n  routeUrl: string,\n  queryUrl?: string,\n  ...messages: unknown[]\n) => {\n  if (process.env.NODE_ENV === \"production\") {\n    return;\n  }\n\n  // 변경: util-api 단독 동작을 위해 날짜 포맷 의존성을 내부 계산으로 대체한다.\n  const date = new Date();\n  const dateText = date.toISOString().split(\"T\")[0] ?? \"\";\n  const timeText = `${date.toLocaleTimeString(\"en-US\", { hour12: false })}.${date.getMilliseconds()}`;\n  const requestMethod = method.split(\"-\")[0]?.toUpperCase() || \"-\";\n  const responseMethod = method.split(\"-\")[1]?.toUpperCase() || requestMethod;\n\n  return console.log(\n    `\\n`,\n    `[Next Server API] ⏱ ${dateText} ( ${timeText} )`,\n    `\\n  λ [${requestMethod}] FE route`,\n    `\\n   ${routeUrl}`,\n    ...(queryUrl\n      ? [`\\n  ═⏵ Ω [${responseMethod}] BE url`, `\\n   ${queryUrl}`, `\\n`]\n      : []),\n    ...(messages?.[0] ? [` ◇-`, ...messages] : []),\n    `\\n`,\n  );\n};\n\n/**\n * API Request Utils; GET API 요청 URL 생성\n * @param {API_GenerateQueryUrlParams} params URL 생성 파라미터\n * @property {string} [params.method] fetch HTTP method\n * @property {string} params.domain API 도메인\n * @property {string} params.routeUrl frontend route URL\n * @property {string} params.queryUrl backend query URL\n * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본\n * @property {object} [params.log] 디버깅 로그 객체\n * @property {boolean} [params.logDisabled] 로그 비활성화 여부\n * @returns {string} 완성된 요청 URL\n * @example\n * const url = generateQueryUrl({ domain, routeUrl, queryUrl });\n */\nexport const generateQueryUrl = ({\n  method = \"GET\",\n  domain,\n  routeUrl,\n  queryUrl,\n  searchParams,\n  log,\n  logDisabled,\n}: API_GenerateQueryUrlParams): string => {\n  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;\n\n  if (!logDisabled) {\n    nextAPILog(method, routeUrl, url, {\n      ...(log ?? {}),\n      ...(searchParams ?? {}),\n    });\n  }\n\n  return url;\n};\n\n/**\n * API Request Utils; fetch 요청 옵션 생성\n * @param {API_GetFetchOptionsParams} params 요청 옵션 파라미터\n * @property {string} params.method HTTP method 문자열\n * @property {HeadersInit} [params.headers] 요청 헤더\n * @property {BodyInit | null} [params.body] 요청 body\n * @returns {RequestInit} fetch 요청 옵션 객체\n * @example\n * const option = getFetchOptions({\n *   method: \"POST\",\n *   headers: { \"Content-Type\": \"application/json\" },\n *   body: JSON.stringify({ farm_id: 1 }),\n * });\n */\nexport const getFetchOptions = ({\n  method,\n  headers,\n  body,\n}: API_GetFetchOptionsParams): RequestInit => ({\n  method,\n  ...(typeof headers === \"undefined\" ? {} : { headers }),\n  ...(typeof body === \"undefined\" ? {} : { body }),\n});\n\n/**\n * API Request Utils; body 기반 fetch 요청\n * @template BodyDataType\n * @template ResponseType\n * @param {API_FetchWithBodyParams<BodyDataType, ResponseType>} params 요청 파라미터\n * @property {string} params.domain API 도메인\n * @property {string} params.method HTTP method 문자열\n * @property {string} params.routeUrl frontend route URL\n * @property {string} params.queryUrl backend query URL\n * @property {ResponseType} params.alternateResponse 실패 시 대체 응답\n * @property {URLSearchParams | object} [params.searchParams] 쿼리스트링 원본\n * @property {HeadersInit} [params.headers] fetch headers\n * @property {BodyInit | null} [params.body] fetch body\n * @property {BodyDataType} [params.bodyData] body 데이터\n * @property {boolean} [params.isRawResponse] raw response 반환 여부\n * @property {object} [params.debug] 디버그 로그 객체\n * @property {boolean} [params.disabled] fetch 비활성화 여부\n * @property {boolean} [params.disabledLog] 로그 비활성화 여부\n * @returns {Promise<ResponseType>} 응답 데이터 또는 alternateResponse\n * @example\n * const response = await fetchWithBody({ domain, method: \"POST\", routeUrl, queryUrl, alternateResponse });\n */\nexport const fetchWithBody = async <\n  BodyDataType = object,\n  ResponseType extends object | Response = Response,\n>({\n  domain,\n  method,\n  routeUrl,\n  queryUrl,\n  searchParams,\n  headers,\n  body,\n  bodyData,\n  isRawResponse,\n  alternateResponse,\n  debug,\n  disabled,\n  disabledLog,\n}: API_FetchWithBodyParams<\n  BodyDataType,\n  ResponseType\n>): Promise<ResponseType> => {\n  const url = `${domain}${queryUrl}${getQueryString(searchParams)}`;\n  const option = getFetchOptions({ method, headers, body });\n\n  if (!body && typeof bodyData !== \"undefined\") {\n    // 변경: util-functions 공통 유틸을 재사용해 body 직렬화 규칙을 단일화한다.\n    const bodyParams = convertObjectToSearchParams(bodyData).toString();\n    if (bodyParams === \"\") {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: \"ERROR (BODY - DATA)\",\n        error: \"데이터가 유효하지 않습니다.\",\n        bodyData,\n        ...(debug ?? {}),\n      });\n      return alternateResponse;\n    }\n    option.body = bodyData as BodyInit;\n  }\n\n  if (!disabledLog) {\n    nextAPILog(method.toLowerCase(), routeUrl, url, {\n      state: \"READY\",\n      ...option,\n      ...(debug ?? {}),\n    });\n  }\n\n  if (disabled) {\n    nextAPILog(method.toLowerCase(), routeUrl, url, {\n      state: \"FETCH DISABLED\",\n      message: \"API 요청제한 활성화됨.\",\n    });\n    return alternateResponse;\n  }\n\n  try {\n    const responseRaw = await fetch(url, option);\n    const responseCode = responseRaw.status;\n\n    if (!disabledLog) {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: responseCode === 200 ? \"SUCCESS\" : \"FAIL\",\n        code: responseCode,\n      });\n    }\n\n    if (isRawResponse) {\n      return responseRaw as ResponseType;\n    }\n    return (await responseRaw.json()) as ResponseType;\n  } catch (error: unknown) {\n    if (!disabledLog) {\n      nextAPILog(method.toLowerCase(), routeUrl, url, {\n        state: \"ERROR (RESPONSE)\",\n        error,\n        ...(debug ?? {}),\n      });\n    }\n    return alternateResponse;\n  }\n};\n"]}

package/dist/response/index.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/response/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/response/index.d.cts

@@ -0,0 +1,72 @@
+/**
+ * API Response Types; Error item
+ * @property {string} field_name 에러 필드 이름
+ * @property {string} message 에러 메시지
+ */
+interface API_Res_Error {
+    /**
+     * 에러 필드 이름
+     */
+    field_name: string;
+    /**
+     * 에러 메시지
+     */
+    message: string;
+}
+/**
+ * API Response Types; Status 값 타입
+ * @example
+ * const status: API_Res_Status = "success";
+ */
+type API_Res_Status = "success" | "fail" | "timeout" | string;
+/**
+ * API Response Types; Base 응답 구조
+ * @property {API_Res_Status} status 통신 상태
+ * @property {ResultDataType} data 요청 응답 데이터
+ * @property {API_Res_Error[]} errors 에러 목록
+ * @property {string} [timestamp] 응답 시간(UTC ISO 문자열)
+ * @example
+ * type API_Res_User = API_Res_Base<{ user_id: number } | null>;
+ */
+interface API_Res_Base<ResultDataType> {
+    /**
+     * 통신 상태
+     */
+    status: API_Res_Status;
+    /**
+     * 요청 응답 데이터
+     */
+    data: ResultDataType;
+    /**
+     * 에러 목록
+     */
+    errors: API_Res_Error[];
+    /**
+     * 응답 시간(UTC ISO 문자열)
+     */
+    timestamp?: string;
+}
+/**
+ * API Response Types; Pagination 응답 데이터
+ * @property {number} total_count 전체 아이템 수
+ * @property {number} size 페이지당 아이템 수
+ * @property {ItemData} items 아이템 데이터
+ * @example
+ * type UserPagination = API_Res_Pagination<{ rows: Array<{ user_id: number }> }>;
+ */
+interface API_Res_Pagination<ItemData extends Record<string, unknown>> {
+    /**
+     * 전체 아이템 수
+     */
+    total_count: number;
+    /**
+     * 페이지당 아이템 수
+     */
+    size: number;
+    /**
+     * 아이템 데이터
+     */
+    items: ItemData;
+}
+
+export type { API_Res_Base, API_Res_Error, API_Res_Pagination, API_Res_Status };

package/dist/response/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * API Response Types; Error item
+ * @property {string} field_name 에러 필드 이름
+ * @property {string} message 에러 메시지
+ */
+interface API_Res_Error {
+    /**
+     * 에러 필드 이름
+     */
+    field_name: string;
+    /**
+     * 에러 메시지
+     */
+    message: string;
+}
+/**
+ * API Response Types; Status 값 타입
+ * @example
+ * const status: API_Res_Status = "success";
+ */
+type API_Res_Status = "success" | "fail" | "timeout" | string;
+/**
+ * API Response Types; Base 응답 구조
+ * @property {API_Res_Status} status 통신 상태
+ * @property {ResultDataType} data 요청 응답 데이터
+ * @property {API_Res_Error[]} errors 에러 목록
+ * @property {string} [timestamp] 응답 시간(UTC ISO 문자열)
+ * @example
+ * type API_Res_User = API_Res_Base<{ user_id: number } | null>;
+ */
+interface API_Res_Base<ResultDataType> {
+    /**
+     * 통신 상태
+     */
+    status: API_Res_Status;
+    /**
+     * 요청 응답 데이터
+     */
+    data: ResultDataType;
+    /**
+     * 에러 목록
+     */
+    errors: API_Res_Error[];
+    /**
+     * 응답 시간(UTC ISO 문자열)
+     */
+    timestamp?: string;
+}
+/**
+ * API Response Types; Pagination 응답 데이터
+ * @property {number} total_count 전체 아이템 수
+ * @property {number} size 페이지당 아이템 수
+ * @property {ItemData} items 아이템 데이터
+ * @example
+ * type UserPagination = API_Res_Pagination<{ rows: Array<{ user_id: number }> }>;
+ */
+interface API_Res_Pagination<ItemData extends Record<string, unknown>> {
+    /**
+     * 전체 아이템 수
+     */
+    total_count: number;
+    /**
+     * 페이지당 아이템 수
+     */
+    size: number;
+    /**
+     * 아이템 데이터
+     */
+    items: ItemData;
+}
+
+export type { API_Res_Base, API_Res_Error, API_Res_Pagination, API_Res_Status };

package/dist/response/index.mjs

@@ -0,0 +1,3 @@
+
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/response/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.mjs"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@uniai-fe/util-api",
+  "version": "0.1.0",
+  "description": "API contract types and framework-agnostic utilities for UNIAI FE projects",
+  "type": "module",
+  "private": false,
+  "sideEffects": false,
+  "license": "MIT",
+  "homepage": "https://www.uniai.co.kr/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "packageManager": "pnpm@10.28.2",
+  "engines": {
+    "node": ">=24",
+    "pnpm": ">=10"
+  },
+  "author": {
+    "name": "GraffitoRyu",
+    "email": "yth4135@naver.com",
+    "url": "https://github.com/GraffitoRyu"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint . --max-warnings=0",
+    "typecheck": "tsc --project tsconfig.build.json --noEmit",
+    "build": "pnpm format && tsup",
+    "dev": "node ../../../scripts/tsup-watch-filter.mjs --watch",
+    "module:lint": "pnpm lint",
+    "module:typecheck": "pnpm typecheck",
+    "module:build": "pnpm build",
+    "util-api:build": "pnpm run build",
+    "util-api:dev": "pnpm run dev",
+    "publish:public": "bash ../../../scripts/npm-publish.sh"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.mjs"
+    },
+    "./request": {
+      "types": "./dist/request/index.d.ts",
+      "import": "./dist/request/index.mjs",
+      "require": "./dist/request/index.cjs",
+      "default": "./dist/request/index.mjs"
+    },
+    "./response": {
+      "types": "./dist/response/index.d.ts",
+      "import": "./dist/response/index.mjs",
+      "require": "./dist/response/index.cjs",
+      "default": "./dist/response/index.mjs"
+    }
+  },
+  "dependencies": {
+    "@uniai-fe/util-functions": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.2",
+    "@uniai-fe/eslint-config": "workspace:*",
+    "@uniai-fe/tsconfig": "workspace:*",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3"
+  }
+}