deliveryapi 1.8.1 → 1.11.0

package/dist/index.cjs

@@ -1,8 +1,13 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -15,14 +20,51 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// ../shared-types/dist/courier/CourierDeliveryStatus.js
+var require_CourierDeliveryStatus = __commonJS({
+  "../shared-types/dist/courier/CourierDeliveryStatus.js"(exports2) {
+    "use strict";
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    exports2.CourierDeliveryStatus = void 0;
+    var CourierDeliveryStatus2;
+    (function(CourierDeliveryStatus3) {
+      CourierDeliveryStatus3["PENDING"] = "PENDING";
+      CourierDeliveryStatus3["REGISTERED"] = "REGISTERED";
+      CourierDeliveryStatus3["PICKUP_READY"] = "PICKUP_READY";
+      CourierDeliveryStatus3["PICKED_UP"] = "PICKED_UP";
+      CourierDeliveryStatus3["IN_TRANSIT"] = "IN_TRANSIT";
+      CourierDeliveryStatus3["OUT_FOR_DELIVERY"] = "OUT_FOR_DELIVERY";
+      CourierDeliveryStatus3["DELIVERED"] = "DELIVERED";
+      CourierDeliveryStatus3["FAILED"] = "FAILED";
+      CourierDeliveryStatus3["RETURNED"] = "RETURNED";
+      CourierDeliveryStatus3["CANCELLED"] = "CANCELLED";
+      CourierDeliveryStatus3["HOLD"] = "HOLD";
+      CourierDeliveryStatus3["UNKNOWN"] = "UNKNOWN";
+    })(CourierDeliveryStatus2 || (exports2.CourierDeliveryStatus = CourierDeliveryStatus2 = {}));
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AccountsResource: () => AccountsResource,
   ApiError: () => ApiError,
-  CourierDeliveryStatus: () => CourierDeliveryStatus,
-  DeliveryAPIClient: () => DeliveryAPIClient
+  CourierDeliveryStatus: () => import_CourierDeliveryStatus.CourierDeliveryStatus,
+  CourierResource: () => CourierResource,
+  DeliveriesResource: () => DeliveriesResource,
+  DeliveryAPIClient: () => DeliveryAPIClient,
+  HistoriesResource: () => HistoriesResource,
+  PrintResource: () => PrintResource
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -56,7 +98,7 @@ async function request(path, options, auth) {
     throw new ApiError(
       json.errorCode ?? "INTERNAL_ERROR",
       json.error ?? json.message ?? `HTTP ${res.status}`,
-      json.statusCode ?? res.status,
+      res.status,
       json.data
     );
   }
@@ -282,7 +324,7 @@ var SubscriptionsResource = class {
   async list(params) {
     return request(
       "/v1/webhooks/subscriptions",
-      { params: { cursor: params?.cursor, limit: params?.limit } },
+      { params: { cursor: params?.cursor, limit: params?.limit, status: params?.status, from: params?.from, to: params?.to } },
       this.auth
     );
   }
@@ -352,6 +394,355 @@ var WebhooksResource = class {
   }
 };
 
+// src/resources/accounts.ts
+var AccountsResource = class {
+  constructor(auth) {
+    this.auth = auth;
+  }
+  /**
+   * 택배사 계정을 등록합니다.
+   *
+   * 롯데택배, CJ대한통운 계정을 등록할 수 있습니다.
+   * CJ대한통운은 2FA(OTP) 인증이 필요할 수 있으며, 이 경우 `COURIER_OTP_REQUIRED` 에러가 발생합니다.
+   *
+   * @param params - 계정 등록 파라미터
+   * @returns 등록된 계정 정보 (courierAccountKey 포함)
+   * @throws {ApiError} COURIER_OTP_REQUIRED — CJ 계정 OTP 인증 필요
+   * @throws {ApiError} COURIER_AUTH_FAILED — 계정 인증 실패 (아이디/비밀번호 오류)
+   * @throws {ApiError} FORBIDDEN — 계정 슬롯 한도 초과
+   *
+   * @example
+   * const account = await client.courier.accounts.register({
+   *   providerId: 'lotte',
+   *   accountId: 'my-lotte-id',
+   *   accountPassword: 'my-password',
+   *   accountName: '메인 롯데 계정',
+   * })
+   * console.log(account.courierAccountKey) // 이후 API 호출에 사용
+   */
+  async register(params) {
+    return request(
+      "/v1/courier/accounts/register",
+      { method: "POST", body: params },
+      this.auth
+    );
+  }
+  /**
+   * 등록된 택배사 계정 목록을 조회합니다.
+   *
+   * @returns 계정 목록 (courierAccountKey, providerId, isActive 등)
+   *
+   * @example
+   * const accounts = await client.courier.accounts.list()
+   * const active = accounts.filter(a => a.isActive)
+   * console.log(active[0].courierAccountKey)
+   */
+  async list() {
+    return request(
+      "/v1/courier/accounts",
+      {},
+      this.auth
+    );
+  }
+  /**
+   * 특정 택배사 계정의 상세 정보를 조회합니다.
+   *
+   * 목록 조회와 달리 `accountPassword` 필드가 포함됩니다 (항상 마스킹된 값).
+   * `expiresAt` 필드는 포함되지 않습니다.
+   *
+   * @param accountKey - 조회할 계정의 courierAccountKey
+   * @returns 계정 상세 정보
+   * @throws {ApiError} NOT_FOUND — 존재하지 않는 계정
+   *
+   * @example
+   * const detail = await client.courier.accounts.get('your-account-key')
+   * console.log(detail.accountId)       // 'my-lotte-id'
+   * console.log(detail.accountPassword) // '(암호화하여 저장중)'
+   */
+  async get(accountKey) {
+    return request(
+      `/v1/courier/accounts/${accountKey}`,
+      {},
+      this.auth
+    );
+  }
+  /**
+   * 택배사 계정을 삭제합니다.
+   *
+   * @param accountKey - 삭제할 계정의 courierAccountKey
+   * @throws {ApiError} NOT_FOUND — 존재하지 않는 계정
+   *
+   * @example
+   * await client.courier.accounts.delete('your-account-key')
+   */
+  async delete(accountKey) {
+    await request(
+      `/v1/courier/accounts/${accountKey}`,
+      { method: "DELETE" },
+      this.auth
+    );
+  }
+};
+
+// src/resources/histories.ts
+var HistoriesResource = class {
+  constructor(auth) {
+    this.auth = auth;
+  }
+  /**
+   * 대량 등록 이력 목록을 조회합니다.
+   *
+   * @param params - 조회 파라미터 (providerId 필수)
+   * @returns 이력 목록 (histories 배열)
+   *
+   * @example
+   * const { histories } = await client.courier.deliveries.histories.list({
+   *   providerId: 'lotte',
+   *   courierAccountKey: 'your-key',
+   *   limit: 20,
+   * })
+   * const completed = histories.filter(h => h.status === 'completed')
+   */
+  async list(params) {
+    return request(
+      "/v1/courier/deliveries/bulk-upload-histories",
+      {
+        method: "GET",
+        params: {
+          providerId: params.providerId,
+          courierAccountKey: params.courierAccountKey,
+          fromDate: params.fromDate,
+          toDate: params.toDate,
+          limit: params.limit
+        }
+      },
+      this.auth
+    );
+  }
+  /**
+   * 대량 등록 이력의 상세 정보를 조회합니다.
+   *
+   * 택배사 API를 호출하여 실시간 배송 상태를 함께 반환합니다.
+   *
+   * @param historyId - 이력 ID
+   * @param params - 조회 파라미터 (courierAccountKey 필수)
+   * @returns 이력 정보 + 실시간 배송 상태 (detailItems)
+   * @throws {ApiError} NOT_FOUND — 존재하지 않는 이력 또는 계정
+   *
+   * @example
+   * const { history, detailItems } = await client.courier.deliveries.histories.get(
+   *   '202603221456_a1b2c',
+   *   { courierAccountKey: 'your-key' },
+   * )
+   * const delivered = detailItems.filter(d => d.isDelivered)
+   */
+  async get(historyId, params) {
+    return request(
+      `/v1/courier/deliveries/bulk-upload-histories/${historyId}/detail`,
+      {
+        method: "GET",
+        params: { courierAccountKey: params.courierAccountKey }
+      },
+      this.auth
+    );
+  }
+};
+
+// src/resources/deliveries.ts
+var DeliveriesResource = class {
+  constructor(auth) {
+    this.auth = auth;
+    this.histories = new HistoriesResource(auth);
+  }
+  /**
+   * 택배를 대량 등록합니다. 최대 1,000건까지 한 번에 등록 가능합니다.
+   *
+   * 등록 직후에는 관리번호(courierDeliveryId)만 발급됩니다.
+   * 송장번호(trackingNumber)는 **송장 출력 시점에 발급**됩니다.
+   *
+   * HTTP 200으로 응답하며, `success`는 전체 성공 여부입니다.
+   * 부분 실패가 가능하므로 반드시 `results[].success`로 개별 확인하세요.
+   *
+   * @param params - 대량 등록 요청 파라미터
+   * @returns 등록 결과 (부분 성공 포함, results[].success로 개별 확인)
+   * @throws {ApiError} RATE_LIMITED — 요청 한도 초과
+   * @throws {ApiError} FORBIDDEN — 계정 슬롯 한도 초과
+   *
+   * @example
+   * const result = await client.courier.deliveries.bulkUpload({
+   *   courierAccountKey: 'your-key',
+   *   items: [{
+   *     clientOrderId: 'ORD-001',
+   *     receiverName: '홍길동',
+   *     receiverPhone1: '01012345678',
+   *     receiverAddress: '서울특별시 중구 세종대로 110',
+   *     productName: '테스트 상품',
+   *     quantity: 1,
+   *   }],
+   * })
+   * const failed = result.results.filter(r => !r.success)
+   * const ids = result.results.filter(r => r.success).map(r => r.courierDeliveryId)
+   */
+  async bulkUpload(params) {
+    return request(
+      "/v1/courier/deliveries/bulk-upload",
+      { method: "POST", body: params },
+      this.auth
+    );
+  }
+  /**
+   * 택배사 계정의 배송 목록을 조회합니다.
+   *
+   * 택배사 API를 실시간으로 호출하여 최신 배송 상태를 반환합니다.
+   *
+   * @param params - 조회 파라미터
+   * @returns 배송 목록 (items) + 요약 통계 (summary)
+   * @throws {ApiError} NOT_FOUND — 존재하지 않는 계정
+   *
+   * @example
+   * const result = await client.courier.deliveries.inquiry({
+   *   courierAccountKey: 'your-key',
+   *   fromDate: '2026-03-01',
+   *   toDate: '2026-03-22',
+   * })
+   * console.log(result.summary.delivered) // 배송 완료 건수
+   * const pending = result.items.filter(i => i.deliveryStatus === 'PENDING')
+   */
+  async inquiry(params) {
+    return request(
+      "/v1/courier/deliveries/inquiry",
+      { method: "POST", body: params },
+      this.auth
+    );
+  }
+  /**
+   * 택배사 계정의 배송 통계(대시보드)를 조회합니다.
+   *
+   * @param params - 조회 파라미터
+   * @returns 배송 통계 (items: 상세 행, summary: 요약)
+   * @throws {ApiError} NOT_FOUND — 존재하지 않는 계정
+   *
+   * @example
+   * const stats = await client.courier.deliveries.dashboard({
+   *   courierAccountKey: 'your-key',
+   *   fromDate: '2026-03-01',
+   *   toDate: '2026-03-22',
+   * })
+   * console.log(stats.summary.totalCount)  // 전체 건수
+   * console.log(stats.summary.delivered)   // 배송 완료 건수
+   */
+  async dashboard(params) {
+    return request(
+      "/v1/courier/deliveries/dashboard",
+      {
+        method: "GET",
+        params: {
+          courierAccountKey: params.courierAccountKey,
+          fromDate: params.fromDate,
+          toDate: params.toDate
+        }
+      },
+      this.auth
+    );
+  }
+  /**
+   * 배송을 취소합니다. 3가지 사용 방식을 지원합니다.
+   *
+   * 1. **historyId만**: 해당 이력의 전체 배송 취소 + 이력 soft delete
+   * 2. **historyId + courierDeliveryIds**: 이력 내 부분 취소
+   * 3. **courierDeliveryIds만**: 택배사 직접 취소 (이력 무관, 최근 7일 이내)
+   *
+   * `historyId`와 `courierDeliveryIds` 중 하나는 반드시 필요합니다.
+   *
+   * @param params - 취소 파라미터
+   * @throws {ApiError} NOT_FOUND — 존재하지 않는 계정 또는 이력
+   * @throws {ApiError} INVALID_PARAMS — 택배사가 배송 취소를 지원하지 않음
+   *
+   * @example
+   * // 이력 전체 취소
+   * await client.courier.deliveries.cancel({
+   *   courierAccountKey: 'your-key',
+   *   historyId: '202603221456_a1b2c',
+   * })
+   *
+   * // 이력 내 부분 취소
+   * await client.courier.deliveries.cancel({
+   *   courierAccountKey: 'your-key',
+   *   historyId: '202603221456_a1b2c',
+   *   courierDeliveryIds: ['7705241632'],
+   * })
+   *
+   * // 직접 취소 (이력 없이)
+   * await client.courier.deliveries.cancel({
+   *   courierAccountKey: 'your-key',
+   *   courierDeliveryIds: ['7705241632', '7705241633'],
+   * })
+   */
+  async cancel(params) {
+    await request(
+      "/v1/courier/deliveries/cancel",
+      { method: "POST", body: params },
+      this.auth
+    );
+  }
+};
+
+// src/resources/print.ts
+var PrintResource = class {
+  constructor(auth) {
+    this.auth = auth;
+  }
+  /**
+   * 송장 출력 세션을 생성합니다.
+   *
+   * 세션 ID로 출력 페이지(`https://print.deliveryapi.co.kr?session={sessionId}`)에 접속할 수 있습니다.
+   * 세션은 **10분 유효, 1회용**입니다. OZ Viewer 설치가 필요합니다.
+   *
+   * `courierTrackingIds` 또는 `bulkUploadHistoryId` 중 하나를 지정하세요.
+   *
+   * **중요**: 대부분의 택배사에서 송장번호(trackingNumber)는 이 출력 시점에 발급됩니다.
+   * 출력 후 `client.courier.deliveries.inquiry()`로 발급된 송장번호를 확인하세요.
+   *
+   * @param params - 출력 세션 생성 파라미터
+   * @returns 세션 정보 (sessionId, expiresAt)
+   * @throws {ApiError} NOT_FOUND — 존재하지 않는 계정 또는 배송 ID
+   *
+   * @example
+   * // 개별 ID로 출력
+   * const session = await client.courier.print.createSession({
+   *   courierAccountKey: 'your-key',
+   *   providerId: 'lotte',
+   *   courierTrackingIds: ['7705241632', '7705241633'],
+   * })
+   * // 브라우저에서 출력 페이지 열기
+   * window.open(`https://print.deliveryapi.co.kr?session=${session.sessionId}`)
+   *
+   * @example
+   * // 이력 전체 출력
+   * const session = await client.courier.print.createSession({
+   *   courierAccountKey: 'your-key',
+   *   providerId: 'lotte',
+   *   bulkUploadHistoryId: '202603221456_a1b2c',
+   * })
+   */
+  async createSession(params) {
+    return request(
+      "/v1/courier/print/sessions",
+      { method: "POST", body: params },
+      this.auth
+    );
+  }
+};
+
+// src/resources/courier.ts
+var CourierResource = class {
+  constructor(auth) {
+    this.accounts = new AccountsResource(auth);
+    this.deliveries = new DeliveriesResource(auth);
+    this.print = new PrintResource(auth);
+  }
+};
+
 // src/client.ts
 var DeliveryAPIClient = class {
   constructor(options) {
@@ -360,29 +751,21 @@ var DeliveryAPIClient = class {
     const auth = { apiKey: options.apiKey, secretKey: options.secretKey };
     this.tracking = new TrackingResource(auth);
     this.webhooks = new WebhooksResource(auth);
+    this.courier = new CourierResource(auth);
   }
 };
 
 // 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 || {});
+var import_CourierDeliveryStatus = __toESM(require_CourierDeliveryStatus(), 1);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AccountsResource,
   ApiError,
   CourierDeliveryStatus,
-  DeliveryAPIClient
+  CourierResource,
+  DeliveriesResource,
+  DeliveryAPIClient,
+  HistoriesResource,
+  PrintResource
 });
 //# sourceMappingURL=index.cjs.map