deliveryapi 1.0.1 → 1.2.0

package/dist/index.d.cts

@@ -227,8 +227,8 @@ interface CreateEndpointParams {
      * 등록 시 서버에서 테스트 POST 요청을 전송하여 URL을 검증합니다.
      */
     url: string;
-    /** 엔드포인트 이름 (선택, 관리용) */
-    name?: string;
+    /** 엔드포인트 이름 (관리용) */
+    name: string;
     /**
      * 서명 시크릿 직접 지정 (선택)
      *
@@ -610,28 +610,6 @@ interface AuthCredentials {
     secretKey: string;
 }
 
-/**
- * 택배 조회 리소스
- *
- * 송장번호로 배송 정보를 즉시 조회합니다.
- * 단건/다건을 모두 지원하며, 여러 택배사를 한 번의 요청으로 조회할 수 있습니다.
- *
- * @example
- * const client = new DeliveryAPIClient({ apiKey: '...', secretKey: '...' })
- *
- * // 단건 조회
- * const result = await client.tracking.trace({
- *   items: [{ courierCode: 'cj', trackingNumber: '1234567890' }],
- * })
- *
- * // 다건 조회 (여러 택배사 혼합 가능)
- * const result = await client.tracking.trace({
- *   items: [
- *     { courierCode: 'cj',    trackingNumber: '1111111111', clientId: 'order_001' },
- *     { courierCode: 'lotte', trackingNumber: '2222222222', clientId: 'order_002' },
- *   ],
- * })
- */
 declare class TrackingResource {
     private readonly auth;
     constructor(auth: AuthCredentials);
@@ -640,8 +618,6 @@ declare class TrackingResource {
      *
      * 택배사 코드(`trackingApiCode`)는 `trace()`의 `courierCode` 파라미터에 사용합니다.
      *
-     * @returns 지원 택배사 목록 및 총 수
-     *
      * @example
      * const { couriers } = await client.tracking.getCouriers()
      * // couriers: [{ trackingApiCode: 'cj', displayName: 'CJ대한통운' }, ...]
@@ -650,25 +626,22 @@ declare class TrackingResource {
     /**
      * 송장번호로 배송 정보를 조회합니다.
      *
-     * - 요청당 여러 건을 배열로 전달할 수 있습니다.
+     * - 여러 건을 배열로 전달할 수 있습니다.
      * - 결과는 요청 순서와 동일한 인덱스로 반환됩니다.
      * - 일부 아이템이 실패해도 전체 요청이 실패하지 않습니다. `results[].success`로 건별 확인하세요.
      *
      * **과금 안내**: `NOT_FOUND` 에러는 과금됩니다. `results[].error.billable`로 확인하세요.
      *
-     * @param params 조회 파라미터
-     * @returns 아이템별 조회 결과 및 집계 요약
+     * @param items 조회할 택배 목록
+     * @param includeProgresses 배송 진행 내역 포함 여부 (기본값: true)
      *
      * @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,
-     * })
+     * const { results } = await client.tracking.trace([
+     *   { courierCode: 'cj',    trackingNumber: '1234567890', clientId: 'order_001' },
+     *   { courierCode: 'lotte', trackingNumber: '9876543210', clientId: 'order_002' },
+     * ])
      *
      * for (const result of results) {
      *   if (result.success) {
@@ -677,39 +650,15 @@ declare class TrackingResource {
      *     console.warn(result.error?.code)          // 'NOT_FOUND'
      *   }
      * }
-     *
-     * console.log(`성공: ${summary.successful} / 전체: ${summary.total}`)
      */
-    trace(params: TraceParams): Promise<TraceResponse>;
+    trace(items: {
+        courierCode: string;
+        trackingNumber: string;
+        clientId?: string;
+    }[], includeProgresses?: boolean): Promise<TraceResponse>;
 }
 
-/**
- * 웹훅 리소스
- *
- * **엔드포인트 관리**: 웹훅을 수신할 URL을 등록/관리합니다.
- * **구독 관리**: 특정 택배를 추적하고 상태 변경 시 웹훅을 수신합니다.
- *
- * @example
- * const client = new DeliveryAPIClient({ apiKey: '...', secretKey: '...' })
- *
- * // 1. 엔드포인트 등록
- * const endpoint = await client.webhooks.createEndpoint({
- *   url: 'https://my-server.com/webhook',
- *   name: '운영 서버',
- * })
- * // ⚠️ endpoint.webhookSecret 을 안전하게 보관하세요!
- *
- * // 2. 택배 추적 구독
- * const sub = await client.webhooks.register({
- *   endpointId: endpoint.endpointId,
- *   items: [{ courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' }],
- *   recurring: true,
- * })
- *
- * // 3. 구독 상태 조회
- * const detail = await client.webhooks.getSubscription(sub.requestId)
- */
-declare class WebhooksResource {
+declare class EndpointsResource {
     private readonly auth;
     constructor(auth: AuthCredentials);
     /**
@@ -719,57 +668,54 @@ declare class WebhooksResource {
      * 응답의 `webhookSecret`은 **이 응답에서만 평문으로 반환**됩니다.
      * 분실 시 `rotateSecret()`으로 재발급해야 합니다.
      *
-     * @param params 엔드포인트 등록 파라미터
-     * @returns 생성된 엔드포인트 정보 (webhookSecret 포함)
+     * @param url 웹훅을 수신할 URL (`https://` 필수)
+     * @param name 엔드포인트 이름 (관리용)
+     * @param webhookSecret 서명 시크릿 직접 지정 (미제공 시 서버 자동 생성, 최소 5자)
      *
      * @throws {ApiError} `WEBHOOK_ENDPOINT_LIMIT` — 엔드포인트 등록 한도 초과
      *
      * @example
-     * const endpoint = await client.webhooks.createEndpoint({
-     *   url: 'https://my-server.com/webhook',
-     *   name: '운영 서버',
-     * })
+     * const endpoint = await client.webhooks.endpoints.create(
+     *   'https://my-server.com/webhook',
+     *   '운영 서버',
+     * )
      * console.log(endpoint.endpointId)    // 'ep_xxxx'
      * console.log(endpoint.webhookSecret) // 반드시 저장하세요!
      */
-    createEndpoint(params: CreateEndpointParams): Promise<CreateEndpointResponse>;
+    create(url: string, name: string, webhookSecret?: string): Promise<CreateEndpointResponse>;
     /**
      * 등록된 웹훅 엔드포인트 목록을 조회합니다.
      *
-     * @returns 엔드포인트 목록 및 총 수
-     *
      * @example
-     * const { endpoints } = await client.webhooks.listEndpoints()
+     * const { endpoints } = await client.webhooks.endpoints.list()
      * const active = endpoints.filter(ep => ep.status === 'active')
      */
-    listEndpoints(): Promise<ListEndpointsResponse>;
+    list(): Promise<ListEndpointsResponse>;
     /**
      * 웹훅 엔드포인트 이름을 수정합니다.
      *
-     * URL은 변경할 수 없습니다. URL을 변경해야 한다면 엔드포인트를 삭제 후 재등록하세요.
+     * URL은 변경할 수 없습니다. URL을 변경해야 한다면 삭제 후 재등록하세요.
      *
      * @param endpointId 수정할 엔드포인트 ID
-     * @param params 수정 내용
+     * @param name 새 이름
      *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
      *
      * @example
-     * await client.webhooks.updateEndpoint('ep_xxxx', { name: '스테이징 서버' })
+     * await client.webhooks.endpoints.update('ep_xxxx', '스테이징 서버')
      */
-    updateEndpoint(endpointId: string, params: UpdateEndpointParams): Promise<void>;
+    update(endpointId: string, name: string): Promise<void>;
     /**
      * 웹훅 엔드포인트를 삭제합니다.
      *
      * 해당 엔드포인트에 연결된 구독도 함께 삭제됩니다 (cascade).
      *
-     * @param endpointId 삭제할 엔드포인트 ID
-     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
      *
      * @example
-     * await client.webhooks.deleteEndpoint('ep_xxxx')
+     * await client.webhooks.endpoints.delete('ep_xxxx')
      */
-    deleteEndpoint(endpointId: string): Promise<void>;
+    delete(endpointId: string): Promise<void>;
     /**
      * 웹훅 서명 시크릿을 재발급합니다.
      *
@@ -777,16 +723,20 @@ declare class WebhooksResource {
      * 새 시크릿은 **이 응답에서만 평문으로 반환**됩니다.
      *
      * @param endpointId 대상 엔드포인트 ID
-     * @param params 새 시크릿 (선택, 미제공 시 서버 생성)
-     * @returns 새 웹훅 시크릿
+     * @param webhookSecret 새 시크릿 직접 지정 (미제공 시 서버 자동 생성)
      *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
      *
      * @example
-     * const { webhookSecret } = await client.webhooks.rotateSecret('ep_xxxx')
+     * const { webhookSecret } = await client.webhooks.endpoints.rotateSecret('ep_xxxx')
      * console.log(webhookSecret) // 새 시크릿 — 반드시 저장하세요!
      */
-    rotateSecret(endpointId: string, params?: RotateSecretParams): Promise<RotateSecretResponse>;
+    rotateSecret(endpointId: string, webhookSecret?: string): Promise<RotateSecretResponse>;
+}
+
+declare class SubscriptionsResource {
+    private readonly auth;
+    constructor(auth: AuthCredentials);
     /**
      * 택배 추적 구독을 등록합니다.
      *
@@ -794,104 +744,141 @@ declare class WebhooksResource {
      * 상태 변경 시 `endpointId`로 웹훅을 발송합니다.
      *
      * **일회성** (`recurring: false`): 등록 즉시 1회 크롤 후 종료합니다.
-     * `endpointId` 없이 사용하면 결과를 `getSubscription(requestId)`으로 직접 조회할 수 있습니다.
+     * `endpointId` 없이 사용하면 결과를 `get(requestId)`으로 직접 조회할 수 있습니다.
      *
-     * @param params 구독 등록 파라미터
-     * @returns 구독 ID (`requestId`) 및 기본 정보
+     * @param items 추적할 택배 목록
+     * @param recurring true: 반복 구독, false: 1회성
+     * @param endpointId 웹훅 수신 엔드포인트 ID (선택)
      *
      * @example
      * // 구독형 — 상태 변경 시 웹훅 수신
-     * const sub = await client.webhooks.register({
-     *   endpointId: 'ep_xxxx',
-     *   items: [
-     *     { courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' },
-     *   ],
-     *   recurring: true,
-     * })
+     * const sub = await client.webhooks.subscriptions.register(
+     *   [{ courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' }],
+     *   true,
+     *   'ep_xxxx',
+     * )
      *
      * @example
-     * // 일회성 즉시 조회 — 웹훅 없이 결과를 직접 폴링
-     * const req = await client.webhooks.register({
-     *   items: [{ courierCode: 'lotte', trackingNumber: '9876543210' }],
-     *   recurring: false,
-     * })
-     * const detail = await client.webhooks.getSubscription(req.requestId)
-     */
-    register(params: RegisterParams): Promise<RegisterResponse>;
+     * // 일회성 — 웹훅 없이 결과를 직접 조회
+     * const req = await client.webhooks.subscriptions.register(
+     *   [{ courierCode: 'lotte', trackingNumber: '9876543210' }],
+     *   false,
+     * )
+     * const detail = await client.webhooks.subscriptions.get(req.requestId)
+     */
+    register(items: {
+        courierCode: string;
+        trackingNumber: string;
+        clientId?: string;
+    }[], recurring: boolean, endpointId?: string): Promise<RegisterResponse>;
     /**
      * 구독 목록을 조회합니다.
      *
      * 커서 기반 페이지네이션을 지원합니다.
      * 다음 페이지가 있으면 응답의 `nextCursor`를 다음 호출의 `cursor` 파라미터로 전달하세요.
      *
-     * @param params 페이지네이션 파라미터 (선택)
-     * @returns 구독 목록 및 다음 페이지 커서
-     *
      * @example
-     * // 전체 구독 목록 순회
      * let cursor: string | undefined
      * do {
-     *   const page = await client.webhooks.listSubscriptions({ cursor, limit: 50 })
+     *   const page = await client.webhooks.subscriptions.list({ cursor, limit: 50 })
      *   for (const sub of page.subscriptions) {
      *     console.log(sub.requestId, sub.isActive)
      *   }
      *   cursor = page.nextCursor
      * } while (cursor)
      */
-    listSubscriptions(params?: ListSubscriptionsParams): Promise<ListSubscriptionsResponse>;
+    list(params?: ListSubscriptionsParams): Promise<ListSubscriptionsResponse>;
     /**
      * 구독 상세 정보를 조회합니다.
      *
-     * 각 택배별 현재 상태 및 최신 배송 데이터를 포함합니다.
-     *
-     * @param requestId `register()` 응답의 `requestId`
-     * @returns 구독 상세 (아이템별 상태 포함)
-     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 구독
      *
      * @example
-     * const detail = await client.webhooks.getSubscription('req_xxxx')
-     *
+     * const detail = await client.webhooks.subscriptions.get('req_xxxx')
      * for (const item of detail.items) {
      *   console.log(item.trackingNumber, item.currentStatus)
      * }
      */
-    getSubscription(requestId: string): Promise<SubscriptionDetail>;
+    get(requestId: string): Promise<SubscriptionDetail>;
     /**
      * 구독을 취소합니다.
      *
-     * 취소된 구독은 더 이상 폴링되지 않으며 웹훅도 발송되지 않습니다.
-     *
-     * @param requestId 취소할 구독 ID
-     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 구독
      *
      * @example
-     * await client.webhooks.cancelSubscription('req_xxxx')
+     * await client.webhooks.subscriptions.cancel('req_xxxx')
      */
-    cancelSubscription(requestId: string): Promise<void>;
+    cancel(requestId: string): Promise<void>;
     /**
      * 여러 송장번호의 최신 배송 정보를 한 번에 조회합니다.
      *
-     * 구독 ID 없이 택배사 코드 + 송장번호로 검색합니다.
-     * 해당 계정에 등록된 구독 중 일치하는 아이템을 반환합니다.
+     * 해당 계정에 등록된 구독 중 일치하는 아이템의 최신 상태를 반환합니다.
      *
-     * @param params 조회할 아이템 목록
-     * @returns 아이템별 최신 배송 정보
+     * @param items 조회할 택배 목록
      *
      * @example
-     * const { results } = await client.webhooks.batchResults({
-     *   items: [
-     *     { courierCode: 'cj',    trackingNumber: '1111111111' },
-     *     { courierCode: 'lotte', trackingNumber: '2222222222' },
-     *   ],
-     * })
-     *
+     * const { results } = await client.webhooks.subscriptions.batchResults([
+     *   { courierCode: 'cj',    trackingNumber: '1111111111' },
+     *   { courierCode: 'lotte', trackingNumber: '2222222222' },
+     * ])
      * for (const r of results) {
      *   console.log(r.currentStatus, r.isDelivered)
      * }
      */
-    batchResults(params: BatchResultsParams): Promise<BatchResultsResponse>;
+    batchResults(items: {
+        courierCode: string;
+        trackingNumber: string;
+    }[]): Promise<BatchResultsResponse>;
+}
+
+/**
+ * 웹훅 리소스
+ *
+ * - `endpoints` — 웹훅 수신 URL 등록/관리
+ * - `subscriptions` — 택배 추적 구독 등록/관리
+ *
+ * @example
+ * const client = new DeliveryAPIClient({ apiKey: '...', secretKey: '...' })
+ *
+ * // 1. 엔드포인트 등록
+ * const endpoint = await client.webhooks.endpoints.create({
+ *   url: 'https://my-server.com/webhook',
+ *   name: '운영 서버',
+ * })
+ * // ⚠️ endpoint.webhookSecret 을 안전하게 보관하세요!
+ *
+ * // 2. 택배 추적 구독
+ * const sub = await client.webhooks.subscriptions.register({
+ *   endpointId: endpoint.endpointId,
+ *   items: [{ courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' }],
+ *   recurring: true,
+ * })
+ *
+ * // 3. 구독 상태 조회
+ * const detail = await client.webhooks.subscriptions.get(sub.requestId)
+ */
+declare class WebhooksResource {
+    /**
+     * 웹훅 엔드포인트 관리
+     *
+     * - `create()` — 수신 URL 등록
+     * - `list()` — 목록 조회
+     * - `update()` — 이름 수정
+     * - `delete()` — 삭제
+     * - `rotateSecret()` — 서명 시크릿 재발급
+     */
+    readonly endpoints: EndpointsResource;
+    /**
+     * 웹훅 구독 관리
+     *
+     * - `register()` — 택배 추적 구독 등록
+     * - `list()` — 구독 목록
+     * - `get()` — 구독 상세
+     * - `cancel()` — 구독 취소
+     * - `batchResults()` — 다건 최신 상태 조회
+     */
+    readonly subscriptions: SubscriptionsResource;
+    constructor(auth: AuthCredentials);
 }
 
 /** `DeliveryAPIClient` 생성 옵션 */
@@ -951,19 +938,8 @@ declare class DeliveryAPIClient {
      *
      * 배송 상태 변경 시 웹훅으로 알림을 받습니다.
      *
-     * **엔드포인트 관리**:
-     * - `createEndpoint()` — 수신 URL 등록
-     * - `listEndpoints()` — 목록 조회
-     * - `updateEndpoint()` — 이름 수정
-     * - `deleteEndpoint()` — 삭제
-     * - `rotateSecret()` — 서명 시크릿 재발급
-     *
-     * **구독 관리**:
-     * - `register()` — 택배 추적 구독 등록
-     * - `listSubscriptions()` — 구독 목록
-     * - `getSubscription()` — 구독 상세
-     * - `cancelSubscription()` — 구독 취소
-     * - `batchResults()` — 다건 최신 상태 조회
+     * **`webhooks.endpoints`** — 수신 URL 등록/관리
+     * **`webhooks.subscriptions`** — 택배 추적 구독 등록/관리
      */
     readonly webhooks: WebhooksResource;
     /** API Base URL (`https://api.deliveryapi.co.kr`) */