deliveryapi 0.2.2 → 1.0.0

package/dist/index.js

@@ -1,310 +1,388 @@
 // src/http.ts
+var BASE_URL = "https://api.deliveryapi.co.kr";
 var ApiError = class extends Error {
-  constructor(statusCode, errorCode, message) {
+  constructor(code, message, status) {
     super(message);
-    this.statusCode = statusCode;
-    this.errorCode = errorCode;
     this.name = "ApiError";
+    this.code = code;
+    this.status = status;
   }
 };
-async function request(baseUrl, path, options = {}) {
-  const { token, ...fetchOptions } = options;
-  const headers = {
-    "Content-Type": "application/json",
-    ...fetchOptions.headers
-  };
-  if (token) {
-    headers["Authorization"] = `Bearer ${token}`;
-  }
-  const res = await fetch(`${baseUrl}${path}`, {
-    ...fetchOptions,
-    headers
+async function request(path, options, auth) {
+  let url = `${BASE_URL}${path}`;
+  if (options.params) {
+    const qs = Object.entries(options.params).filter(([, v]) => v !== void 0).map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`).join("&");
+    if (qs) url += `?${qs}`;
+  }
+  const res = await fetch(url, {
+    method: options.method ?? "GET",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${auth.apiKey}:${auth.secretKey}`
+    },
+    body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
   });
-  const body = await res.json();
-  if (!res.ok || !body.isSuccess) {
+  const json = await res.json();
+  if (!json.isSuccess) {
     throw new ApiError(
-      res.status,
-      body.errorCode,
-      body.error ?? `Request failed with status ${res.status}`
+      json.errorCode ?? "INTERNAL_ERROR",
+      json.error ?? json.message ?? `HTTP ${res.status}`,
+      json.statusCode ?? res.status
     );
   }
-  return body.data;
+  return json.data;
 }
 
-// src/resources/auth.ts
-var AuthResource = class {
-  constructor(baseUrl, getToken) {
-    this.baseUrl = baseUrl;
-    this.getToken = getToken;
-  }
-  /** Step 1: 이메일 인증 코드 요청 */
-  async requestVerification(params) {
-    await request(this.baseUrl, "/v1/homepage/register/request", {
-      method: "POST",
-      body: JSON.stringify(params)
-    });
-  }
-  /** Step 2: 인증 코드 검증 + Firebase 계정 생성 → customToken 반환 */
-  async verifyAndRegister(params) {
-    return request(this.baseUrl, "/v1/homepage/register/verify", {
-      method: "POST",
-      body: JSON.stringify(params)
-    });
-  }
-  /** Google 로그인 후 HP 사용자 문서 확인/생성 */
-  async ensureUser() {
-    const token = await this.getToken();
-    return request(this.baseUrl, "/v1/homepage/ensure-user", {
-      method: "POST",
-      body: JSON.stringify({}),
-      token
-    });
-  }
-};
-
-// src/resources/dashboard.ts
-var DashboardResource = class {
-  constructor(baseUrl, getToken) {
-    this.baseUrl = baseUrl;
-    this.getToken = getToken;
-  }
-  /** 대시보드 데이터 조회 (API 키 목록, 사용량, 플랜 정보) */
-  async get() {
-    const token = await this.getToken();
-    return request(this.baseUrl, "/v1/homepage/dashboard", { token });
-  }
-  /** API 키 발급 */
-  async issueKey() {
-    const token = await this.getToken();
-    return request(this.baseUrl, "/v1/homepage/dashboard/issue-key", {
-      method: "POST",
-      body: JSON.stringify({}),
-      token
-    });
-  }
-};
-
-// src/resources/qna.ts
-var QnaResource = class {
-  constructor(baseUrl, getToken) {
-    this.baseUrl = baseUrl;
-    this.getToken = getToken;
-  }
-  /** 게시글 목록 조회 (비회원도 공개글 열람 가능) */
-  async listPosts(params = {}) {
-    const token = await this.getToken();
-    const qs = new URLSearchParams();
-    if (params.cursor) qs.set("cursor", params.cursor);
-    if (params.pageSize) qs.set("pageSize", String(params.pageSize));
-    const query = qs.toString() ? `?${qs.toString()}` : "";
-    return request(this.baseUrl, `/v1/homepage/posts${query}`, { token });
-  }
-  /** 게시글 상세 조회 */
-  async getPost(postId) {
-    const token = await this.getToken();
-    return request(this.baseUrl, `/v1/homepage/posts/${postId}`, { token });
-  }
-  /** 게시글 작성 (로그인 필요) */
-  async createPost(params) {
-    const token = await this.getToken();
-    return request(this.baseUrl, "/v1/homepage/posts", {
-      method: "POST",
-      body: JSON.stringify(params),
-      token
-    });
-  }
-  /** 게시글 수정 (작성자/관리자만) */
-  async updatePost(postId, params) {
-    const token = await this.getToken();
-    return request(this.baseUrl, `/v1/homepage/posts/${postId}`, {
-      method: "PUT",
-      body: JSON.stringify(params),
-      token
-    });
-  }
-  /** 게시글 삭제 (작성자/관리자만) */
-  async deletePost(postId) {
-    const token = await this.getToken();
-    await request(this.baseUrl, `/v1/homepage/posts/${postId}`, {
-      method: "DELETE",
-      token
-    });
-  }
-  /** 댓글 목록 조회 */
-  async listComments(postId) {
-    const token = await this.getToken();
-    return request(this.baseUrl, `/v1/homepage/posts/${postId}/comments`, { token });
-  }
-  /** 댓글 작성 (로그인 필요) */
-  async createComment(postId, params) {
-    const token = await this.getToken();
-    return request(this.baseUrl, `/v1/homepage/posts/${postId}/comments`, {
-      method: "POST",
-      body: JSON.stringify(params),
-      token
-    });
+// src/resources/tracking.ts
+var TrackingResource = class {
+  constructor(auth) {
+    this.auth = auth;
+  }
+  /**
+   * 지원 택배사 목록을 조회합니다.
+   *
+   * 택배사 코드(`trackingApiCode`)는 `trace()`의 `courierCode` 파라미터에 사용합니다.
+   *
+   * @returns 지원 택배사 목록 및 총 수
+   *
+   * @example
+   * const { couriers } = await client.tracking.getCouriers()
+   * // couriers: [{ trackingApiCode: 'cj', displayName: 'CJ대한통운' }, ...]
+   */
+  async getCouriers() {
+    return request(
+      "/v1/tracking/couriers",
+      {},
+      this.auth
+    );
   }
-  /** 댓글 삭제 (작성자/관리자만) */
-  async deleteComment(commentId) {
-    const token = await this.getToken();
-    await request(this.baseUrl, `/v1/homepage/comments/${commentId}`, {
-      method: "DELETE",
-      token
-    });
+  /**
+   * 송장번호로 배송 정보를 조회합니다.
+   *
+   * - 요청당 여러 건을 배열로 전달할 수 있습니다.
+   * - 결과는 요청 순서와 동일한 인덱스로 반환됩니다.
+   * - 일부 아이템이 실패해도 전체 요청이 실패하지 않습니다. `results[].success`로 건별 확인하세요.
+   *
+   * **과금 안내**: `NOT_FOUND` 에러는 과금됩니다. `results[].error.billable`로 확인하세요.
+   *
+   * @param params 조회 파라미터
+   * @returns 아이템별 조회 결과 및 집계 요약
+   *
+   * @throws {ApiError} API 인증 실패, 요청 한도 초과 등 전체 요청 실패 시
+   *
+   * @example
+   * const { results, summary } = await client.tracking.trace({
+   *   items: [
+   *     { courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' },
+   *     { courierCode: 'lotte', trackingNumber: '9876543210', clientId: 'order_002' },
+   *   ],
+   *   includeProgresses: true,
+   * })
+   *
+   * for (const result of results) {
+   *   if (result.success) {
+   *     console.log(result.data?.deliveryStatus)  // 'DELIVERED'
+   *   } else {
+   *     console.warn(result.error?.code)          // 'NOT_FOUND'
+   *   }
+   * }
+   *
+   * console.log(`성공: ${summary.successful} / 전체: ${summary.total}`)
+   */
+  async trace(params) {
+    return request(
+      "/v1/tracking/trace",
+      { method: "POST", body: params },
+      this.auth
+    );
   }
 };
 
-// src/resources/admin.ts
-var AdminResource = class {
-  constructor(baseUrl, getToken) {
-    this.baseUrl = baseUrl;
-    this.getToken = getToken;
-  }
-  async token() {
-    return this.getToken();
-  }
-  /** 전체 통계 조회 */
-  async getStats() {
-    return request(this.baseUrl, "/v1/homepage/admin/stats", {
-      token: await this.token()
-    });
-  }
-  /** 최근 14일 일별 가입자 수 */
-  async getDailySignups() {
-    return request(this.baseUrl, "/v1/homepage/admin/daily-signups", {
-      token: await this.token()
-    });
-  }
-  /** 사용자 목록 조회 */
-  async listUsers() {
-    return request(this.baseUrl, "/v1/homepage/admin/users", {
-      token: await this.token()
-    });
-  }
-  /** 사용자 정보 수정 */
-  async updateUser(uid, params) {
-    await request(this.baseUrl, `/v1/homepage/admin/users/${uid}`, {
-      method: "PATCH",
-      body: JSON.stringify(params),
-      token: await this.token()
-    });
-  }
-  /** 사용자 상세 조회 (API 키 + 사용량 포함) */
-  async getUserDetail(uid) {
-    return request(this.baseUrl, `/v1/homepage/admin/users/${uid}/detail`, {
-      token: await this.token()
-    });
-  }
-  /** customers 목록 조회 */
-  async listCustomers() {
-    return request(this.baseUrl, "/v1/homepage/admin/customers", {
-      token: await this.token()
-    });
-  }
-  /** API 키 목록 조회 */
-  async listKeys() {
-    return request(this.baseUrl, "/v1/homepage/admin/keys", {
-      token: await this.token()
-    });
-  }
-  /** API 키 플랜 변경 */
-  async updateKeyPlan(apiKeyHash, params) {
-    await request(this.baseUrl, `/v1/homepage/admin/keys/${apiKeyHash}/plan`, {
-      method: "PATCH",
-      body: JSON.stringify(params),
-      token: await this.token()
-    });
-  }
-  /** API 키 플랜 일괄 변경 */
-  async bulkUpdateKeyPlan(params) {
-    await request(this.baseUrl, "/v1/homepage/admin/keys/bulk/plan", {
-      method: "PATCH",
-      body: JSON.stringify(params),
-      token: await this.token()
-    });
-  }
-  /** Secret Key limits 수정 */
-  async updateKeyLimits(apiKeyHash, params) {
-    await request(this.baseUrl, `/v1/homepage/admin/keys/${apiKeyHash}/limits`, {
-      method: "PATCH",
-      body: JSON.stringify(params),
-      token: await this.token()
-    });
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(auth) {
+    this.auth = auth;
+  }
+  // ─────────────────────── 엔드포인트 관리 ────────────────────────────────
+  /**
+   * 웹훅 엔드포인트를 등록합니다.
+   *
+   * 등록 시 서버에서 해당 URL로 테스트 POST 요청을 전송하여 연결 가능 여부를 검증합니다.
+   * 응답의 `webhookSecret`은 **이 응답에서만 평문으로 반환**됩니다.
+   * 분실 시 `rotateSecret()`으로 재발급해야 합니다.
+   *
+   * @param params 엔드포인트 등록 파라미터
+   * @returns 생성된 엔드포인트 정보 (webhookSecret 포함)
+   *
+   * @throws {ApiError} `WEBHOOK_ENDPOINT_LIMIT` — 엔드포인트 등록 한도 초과
+   *
+   * @example
+   * const endpoint = await client.webhooks.createEndpoint({
+   *   url: 'https://my-server.com/webhook',
+   *   name: '운영 서버',
+   * })
+   * console.log(endpoint.endpointId)    // 'ep_xxxx'
+   * console.log(endpoint.webhookSecret) // 반드시 저장하세요!
+   */
+  async createEndpoint(params) {
+    return request(
+      "/v1/webhooks/endpoints",
+      { method: "POST", body: params },
+      this.auth
+    );
   }
-  /** 데모 키 생성 */
-  async createDemoKey(params = {}) {
-    return request(this.baseUrl, "/v1/homepage/admin/demo-keys", {
-      method: "POST",
-      body: JSON.stringify(params),
-      token: await this.token()
-    });
+  /**
+   * 등록된 웹훅 엔드포인트 목록을 조회합니다.
+   *
+   * @returns 엔드포인트 목록 및 총 수
+   *
+   * @example
+   * const { endpoints } = await client.webhooks.listEndpoints()
+   * const active = endpoints.filter(ep => ep.status === 'active')
+   */
+  async listEndpoints() {
+    return request(
+      "/v1/webhooks/endpoints",
+      {},
+      this.auth
+    );
   }
-  /** 데모 키 목록 조회 */
-  async listDemoKeys() {
-    return request(this.baseUrl, "/v1/homepage/admin/demo-keys", {
-      token: await this.token()
-    });
+  /**
+   * 웹훅 엔드포인트 이름을 수정합니다.
+   *
+   * URL은 변경할 수 없습니다. URL을 변경해야 한다면 엔드포인트를 삭제 후 재등록하세요.
+   *
+   * @param endpointId 수정할 엔드포인트 ID
+   * @param params 수정 내용
+   *
+   * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
+   *
+   * @example
+   * await client.webhooks.updateEndpoint('ep_xxxx', { name: '스테이징 서버' })
+   */
+  async updateEndpoint(endpointId, params) {
+    await request(
+      `/v1/webhooks/endpoints/${endpointId}`,
+      { method: "PUT", body: params },
+      this.auth
+    );
   }
-  /** 데모 키 비활성화 */
-  async deactivateDemoKey(apiKeyHash) {
-    await request(this.baseUrl, `/v1/homepage/admin/demo-keys/${apiKeyHash}/deactivate`, {
-      method: "PATCH",
-      body: JSON.stringify({}),
-      token: await this.token()
-    });
+  /**
+   * 웹훅 엔드포인트를 삭제합니다.
+   *
+   * 해당 엔드포인트에 연결된 구독도 함께 삭제됩니다 (cascade).
+   *
+   * @param endpointId 삭제할 엔드포인트 ID
+   *
+   * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
+   *
+   * @example
+   * await client.webhooks.deleteEndpoint('ep_xxxx')
+   */
+  async deleteEndpoint(endpointId) {
+    await request(
+      `/v1/webhooks/endpoints/${endpointId}`,
+      { method: "DELETE" },
+      this.auth
+    );
   }
-  /** 데모 키 활성화 */
-  async activateDemoKey(apiKeyHash) {
-    await request(this.baseUrl, `/v1/homepage/admin/demo-keys/${apiKeyHash}/activate`, {
-      method: "PATCH",
-      body: JSON.stringify({}),
-      token: await this.token()
-    });
+  /**
+   * 웹훅 서명 시크릿을 재발급합니다.
+   *
+   * 기존 시크릿은 즉시 무효화됩니다.
+   * 새 시크릿은 **이 응답에서만 평문으로 반환**됩니다.
+   *
+   * @param endpointId 대상 엔드포인트 ID
+   * @param params 새 시크릿 (선택, 미제공 시 서버 생성)
+   * @returns 새 웹훅 시크릿
+   *
+   * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
+   *
+   * @example
+   * const { webhookSecret } = await client.webhooks.rotateSecret('ep_xxxx')
+   * console.log(webhookSecret) // 새 시크릿 — 반드시 저장하세요!
+   */
+  async rotateSecret(endpointId, params) {
+    return request(
+      `/v1/webhooks/endpoints/${endpointId}/rotate`,
+      { method: "POST", body: params ?? {} },
+      this.auth
+    );
   }
-  /** 조회 로그 목록 */
-  async listTrackingLogs(page = 1) {
+  // ─────────────────────── 구독 관리 ──────────────────────────────────────
+  /**
+   * 택배 추적 구독을 등록합니다.
+   *
+   * **구독형** (`recurring: true`): 배송 완료 또는 최대 14일까지 주기적으로 폴링하여
+   * 상태 변경 시 `endpointId`로 웹훅을 발송합니다.
+   *
+   * **일회성** (`recurring: false`): 등록 즉시 1회 크롤 후 종료합니다.
+   * `endpointId` 없이 사용하면 결과를 `getSubscription(requestId)`으로 직접 조회할 수 있습니다.
+   *
+   * @param params 구독 등록 파라미터
+   * @returns 구독 ID (`requestId`) 및 기본 정보
+   *
+   * @example
+   * // 구독형 — 상태 변경 시 웹훅 수신
+   * const sub = await client.webhooks.register({
+   *   endpointId: 'ep_xxxx',
+   *   items: [
+   *     { courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' },
+   *   ],
+   *   recurring: true,
+   * })
+   *
+   * @example
+   * // 일회성 즉시 조회 — 웹훅 없이 결과를 직접 폴링
+   * const req = await client.webhooks.register({
+   *   items: [{ courierCode: 'lotte', trackingNumber: '9876543210' }],
+   *   recurring: false,
+   * })
+   * const detail = await client.webhooks.getSubscription(req.requestId)
+   */
+  async register(params) {
     return request(
-      this.baseUrl,
-      `/v1/homepage/admin/tracking-logs?page=${page}`,
-      { token: await this.token() }
+      "/v1/webhooks/register",
+      { method: "POST", body: params },
+      this.auth
     );
   }
-};
-
-// src/resources/public.ts
-var PublicResource = class {
-  constructor(baseUrl) {
-    this.baseUrl = baseUrl;
+  /**
+   * 구독 목록을 조회합니다.
+   *
+   * 커서 기반 페이지네이션을 지원합니다.
+   * 다음 페이지가 있으면 응답의 `nextCursor`를 다음 호출의 `cursor` 파라미터로 전달하세요.
+   *
+   * @param params 페이지네이션 파라미터 (선택)
+   * @returns 구독 목록 및 다음 페이지 커서
+   *
+   * @example
+   * // 전체 구독 목록 순회
+   * let cursor: string | undefined
+   * do {
+   *   const page = await client.webhooks.listSubscriptions({ cursor, limit: 50 })
+   *   for (const sub of page.subscriptions) {
+   *     console.log(sub.requestId, sub.isActive)
+   *   }
+   *   cursor = page.nextCursor
+   * } while (cursor)
+   */
+  async listSubscriptions(params) {
+    return request(
+      "/v1/webhooks/subscriptions",
+      {
+        params: {
+          cursor: params?.cursor,
+          limit: params?.limit
+        }
+      },
+      this.auth
+    );
   }
-  /** 요금제 목록 조회 */
-  async getPlans() {
-    return request(this.baseUrl, "/v1/homepage/plans");
+  /**
+   * 구독 상세 정보를 조회합니다.
+   *
+   * 각 택배별 현재 상태 및 최신 배송 데이터를 포함합니다.
+   *
+   * @param requestId `register()` 응답의 `requestId`
+   * @returns 구독 상세 (아이템별 상태 포함)
+   *
+   * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 구독
+   *
+   * @example
+   * const detail = await client.webhooks.getSubscription('req_xxxx')
+   *
+   * for (const item of detail.items) {
+   *   console.log(item.trackingNumber, item.currentStatus)
+   * }
+   */
+  async getSubscription(requestId) {
+    return request(
+      `/v1/webhooks/subscriptions/${requestId}`,
+      {},
+      this.auth
+    );
   }
-  /** Secret Key 프리셋 목록 조회 */
-  async getSecretPresets() {
-    return request(this.baseUrl, "/v1/homepage/secret-presets");
+  /**
+   * 구독을 취소합니다.
+   *
+   * 취소된 구독은 더 이상 폴링되지 않으며 웹훅도 발송되지 않습니다.
+   *
+   * @param requestId 취소할 구독 ID
+   *
+   * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 구독
+   *
+   * @example
+   * await client.webhooks.cancelSubscription('req_xxxx')
+   */
+  async cancelSubscription(requestId) {
+    await request(
+      `/v1/webhooks/subscriptions/${requestId}`,
+      { method: "DELETE" },
+      this.auth
+    );
   }
-  /** 개발 의뢰 문의 전송 */
-  async sendContactInquiry(params) {
-    await request(this.baseUrl, "/v1/homepage/contact/inquiry", {
-      method: "POST",
-      body: JSON.stringify(params)
-    });
+  /**
+   * 여러 송장번호의 최신 배송 정보를 한 번에 조회합니다.
+   *
+   * 구독 ID 없이 택배사 코드 + 송장번호로 검색합니다.
+   * 해당 계정에 등록된 구독 중 일치하는 아이템을 반환합니다.
+   *
+   * @param params 조회할 아이템 목록
+   * @returns 아이템별 최신 배송 정보
+   *
+   * @example
+   * const { results } = await client.webhooks.batchResults({
+   *   items: [
+   *     { courierCode: 'cj',    trackingNumber: '1111111111' },
+   *     { courierCode: 'lotte', trackingNumber: '2222222222' },
+   *   ],
+   * })
+   *
+   * for (const r of results) {
+   *   console.log(r.currentStatus, r.isDelivered)
+   * }
+   */
+  async batchResults(params) {
+    return request(
+      "/v1/webhooks/results",
+      { method: "POST", body: params },
+      this.auth
+    );
   }
 };
 
 // src/client.ts
-var BASE_URL = "https://api.deliveryapi.co.kr";
-var noToken = async () => null;
-var HomepageClient = class {
-  constructor(options = {}) {
-    const { getToken = noToken } = options;
-    this.auth = new AuthResource(BASE_URL, getToken);
-    this.dashboard = new DashboardResource(BASE_URL, getToken);
-    this.qna = new QnaResource(BASE_URL, getToken);
-    this.admin = new AdminResource(BASE_URL, getToken);
-    this.public = new PublicResource(BASE_URL);
+var BASE_URL2 = "https://api.deliveryapi.co.kr";
+var DeliveryAPIClient = class {
+  constructor(options) {
+    /** API Base URL (`https://api.deliveryapi.co.kr`) */
+    this.baseUrl = BASE_URL2;
+    const auth = { apiKey: options.apiKey, secretKey: options.secretKey };
+    this.tracking = new TrackingResource(auth);
+    this.webhooks = new WebhooksResource(auth);
   }
 };
 
-export { ApiError, HomepageClient };
+// src/types.ts
+var CourierDeliveryStatus = /* @__PURE__ */ ((CourierDeliveryStatus2) => {
+  CourierDeliveryStatus2["PENDING"] = "PENDING";
+  CourierDeliveryStatus2["REGISTERED"] = "REGISTERED";
+  CourierDeliveryStatus2["PICKUP_READY"] = "PICKUP_READY";
+  CourierDeliveryStatus2["PICKED_UP"] = "PICKED_UP";
+  CourierDeliveryStatus2["IN_TRANSIT"] = "IN_TRANSIT";
+  CourierDeliveryStatus2["OUT_FOR_DELIVERY"] = "OUT_FOR_DELIVERY";
+  CourierDeliveryStatus2["DELIVERED"] = "DELIVERED";
+  CourierDeliveryStatus2["FAILED"] = "FAILED";
+  CourierDeliveryStatus2["RETURNED"] = "RETURNED";
+  CourierDeliveryStatus2["CANCELLED"] = "CANCELLED";
+  CourierDeliveryStatus2["HOLD"] = "HOLD";
+  CourierDeliveryStatus2["UNKNOWN"] = "UNKNOWN";
+  return CourierDeliveryStatus2;
+})(CourierDeliveryStatus || {});
+export {
+  ApiError,
+  CourierDeliveryStatus,
+  DeliveryAPIClient
+};
+//# sourceMappingURL=index.js.map