deliveryapi 1.1.0 → 1.3.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,24 +626,23 @@ 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({
+     * const { results } = await client.tracking.trace({
      *   items: [
-     *     { courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' },
+     *     { courierCode: 'cj',    trackingNumber: '1234567890', clientId: 'order_001' },
      *     { courierCode: 'lotte', trackingNumber: '9876543210', clientId: 'order_002' },
      *   ],
-     *   includeProgresses: true,
      * })
      *
      * for (const result of results) {
@@ -677,18 +652,17 @@ declare class TrackingResource {
      *     console.warn(result.error?.code)          // 'NOT_FOUND'
      *   }
      * }
-     *
-     * console.log(`성공: ${summary.successful} / 전체: ${summary.total}`)
      */
-    trace(params: TraceParams): Promise<TraceResponse>;
+    trace(params: {
+        items: {
+            courierCode: string;
+            trackingNumber: string;
+            clientId?: string;
+        }[];
+        includeProgresses?: boolean;
+    }): Promise<TraceResponse>;
 }
 
-/**
- * 웹훅 엔드포인트 관리
- *
- * 웹훅을 수신할 URL을 등록/관리합니다.
- * 엔드포인트는 한 번 설정하면 여러 구독에서 재사용할 수 있습니다.
- */
 declare class EndpointsResource {
     private readonly auth;
     constructor(auth: AuthCredentials);
@@ -699,17 +673,21 @@ declare class EndpointsResource {
      * 응답의 `webhookSecret`은 **이 응답에서만 평문으로 반환**됩니다.
      * 분실 시 `rotateSecret()`으로 재발급해야 합니다.
      *
+     * @param url 웹훅을 수신할 URL (`https://` 필수)
+     * @param name 엔드포인트 이름 (관리용)
+     * @param webhookSecret 서명 시크릿 직접 지정 (미제공 시 서버 자동 생성, 최소 5자)
+     *
      * @throws {ApiError} `WEBHOOK_ENDPOINT_LIMIT` — 엔드포인트 등록 한도 초과
      *
      * @example
-     * const endpoint = await client.webhooks.endpoints.create({
-     *   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) // 반드시 저장하세요!
      */
-    create(params: CreateEndpointParams): Promise<CreateEndpointResponse>;
+    create(url: string, name: string, webhookSecret?: string): Promise<CreateEndpointResponse>;
     /**
      * 등록된 웹훅 엔드포인트 목록을 조회합니다.
      *
@@ -723,12 +701,15 @@ declare class EndpointsResource {
      *
      * URL은 변경할 수 없습니다. URL을 변경해야 한다면 삭제 후 재등록하세요.
      *
+     * @param endpointId 수정할 엔드포인트 ID
+     * @param name 새 이름
+     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
      *
      * @example
-     * await client.webhooks.endpoints.update('ep_xxxx', { name: '스테이징 서버' })
+     * await client.webhooks.endpoints.update('ep_xxxx', '스테이징 서버')
      */
-    update(endpointId: string, params: UpdateEndpointParams): Promise<void>;
+    update(endpointId: string, name: string): Promise<void>;
     /**
      * 웹훅 엔드포인트를 삭제합니다.
      *
@@ -746,20 +727,18 @@ declare class EndpointsResource {
      * 기존 시크릿은 즉시 무효화됩니다.
      * 새 시크릿은 **이 응답에서만 평문으로 반환**됩니다.
      *
+     * @param endpointId 대상 엔드포인트 ID
+     * @param webhookSecret 새 시크릿 직접 지정 (미제공 시 서버 자동 생성)
+     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
      *
      * @example
      * 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);
@@ -772,25 +751,35 @@ declare class SubscriptionsResource {
      * **일회성** (`recurring: false`): 등록 즉시 1회 크롤 후 종료합니다.
      * `endpointId` 없이 사용하면 결과를 `get(requestId)`으로 직접 조회할 수 있습니다.
      *
+     * @param items 추적할 택배 목록
+     * @param recurring true: 반복 구독, false: 1회성
+     * @param endpointId 웹훅 수신 엔드포인트 ID (선택)
+     *
      * @example
      * // 구독형 — 상태 변경 시 웹훅 수신
-     * const sub = await client.webhooks.subscriptions.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.subscriptions.register({
-     *   items: [{ courierCode: 'lotte', trackingNumber: '9876543210' }],
-     *   recurring: false,
-     * })
+     * // 일회성 — 웹훅 없이 결과를 직접 조회
+     * const req = await client.webhooks.subscriptions.register(
+     *   [{ courierCode: 'lotte', trackingNumber: '9876543210' }],
+     *   false,
+     * )
      * const detail = await client.webhooks.subscriptions.get(req.requestId)
      */
-    register(params: RegisterParams): Promise<RegisterResponse>;
+    register(params: {
+        items: {
+            courierCode: string;
+            trackingNumber: string;
+            clientId?: string;
+        }[];
+        recurring: boolean;
+        endpointId?: string;
+    }): Promise<RegisterResponse>;
     /**
      * 구독 목록을 조회합니다.
      *
@@ -811,8 +800,6 @@ declare class SubscriptionsResource {
     /**
      * 구독 상세 정보를 조회합니다.
      *
-     * 각 택배별 현재 상태 및 최신 배송 데이터를 포함합니다.
-     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 구독
      *
      * @example
@@ -825,8 +812,6 @@ declare class SubscriptionsResource {
     /**
      * 구독을 취소합니다.
      *
-     * 취소된 구독은 더 이상 폴링되지 않으며 웹훅도 발송되지 않습니다.
-     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 구독
      *
      * @example
@@ -838,18 +823,23 @@ declare class SubscriptionsResource {
      *
      * 해당 계정에 등록된 구독 중 일치하는 아이템의 최신 상태를 반환합니다.
      *
+     * @param items 조회할 택배 목록
+     *
      * @example
-     * const { results } = await client.webhooks.subscriptions.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(params: {
+        items: {
+            courierCode: string;
+            trackingNumber: string;
+        }[];
+    }): Promise<BatchResultsResponse>;
 }
 
 /**

package/dist/index.d.ts

@@ -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,24 +626,23 @@ 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({
+     * const { results } = await client.tracking.trace({
      *   items: [
-     *     { courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' },
+     *     { courierCode: 'cj',    trackingNumber: '1234567890', clientId: 'order_001' },
      *     { courierCode: 'lotte', trackingNumber: '9876543210', clientId: 'order_002' },
      *   ],
-     *   includeProgresses: true,
      * })
      *
      * for (const result of results) {
@@ -677,18 +652,17 @@ declare class TrackingResource {
      *     console.warn(result.error?.code)          // 'NOT_FOUND'
      *   }
      * }
-     *
-     * console.log(`성공: ${summary.successful} / 전체: ${summary.total}`)
      */
-    trace(params: TraceParams): Promise<TraceResponse>;
+    trace(params: {
+        items: {
+            courierCode: string;
+            trackingNumber: string;
+            clientId?: string;
+        }[];
+        includeProgresses?: boolean;
+    }): Promise<TraceResponse>;
 }
 
-/**
- * 웹훅 엔드포인트 관리
- *
- * 웹훅을 수신할 URL을 등록/관리합니다.
- * 엔드포인트는 한 번 설정하면 여러 구독에서 재사용할 수 있습니다.
- */
 declare class EndpointsResource {
     private readonly auth;
     constructor(auth: AuthCredentials);
@@ -699,17 +673,21 @@ declare class EndpointsResource {
      * 응답의 `webhookSecret`은 **이 응답에서만 평문으로 반환**됩니다.
      * 분실 시 `rotateSecret()`으로 재발급해야 합니다.
      *
+     * @param url 웹훅을 수신할 URL (`https://` 필수)
+     * @param name 엔드포인트 이름 (관리용)
+     * @param webhookSecret 서명 시크릿 직접 지정 (미제공 시 서버 자동 생성, 최소 5자)
+     *
      * @throws {ApiError} `WEBHOOK_ENDPOINT_LIMIT` — 엔드포인트 등록 한도 초과
      *
      * @example
-     * const endpoint = await client.webhooks.endpoints.create({
-     *   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) // 반드시 저장하세요!
      */
-    create(params: CreateEndpointParams): Promise<CreateEndpointResponse>;
+    create(url: string, name: string, webhookSecret?: string): Promise<CreateEndpointResponse>;
     /**
      * 등록된 웹훅 엔드포인트 목록을 조회합니다.
      *
@@ -723,12 +701,15 @@ declare class EndpointsResource {
      *
      * URL은 변경할 수 없습니다. URL을 변경해야 한다면 삭제 후 재등록하세요.
      *
+     * @param endpointId 수정할 엔드포인트 ID
+     * @param name 새 이름
+     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
      *
      * @example
-     * await client.webhooks.endpoints.update('ep_xxxx', { name: '스테이징 서버' })
+     * await client.webhooks.endpoints.update('ep_xxxx', '스테이징 서버')
      */
-    update(endpointId: string, params: UpdateEndpointParams): Promise<void>;
+    update(endpointId: string, name: string): Promise<void>;
     /**
      * 웹훅 엔드포인트를 삭제합니다.
      *
@@ -746,20 +727,18 @@ declare class EndpointsResource {
      * 기존 시크릿은 즉시 무효화됩니다.
      * 새 시크릿은 **이 응답에서만 평문으로 반환**됩니다.
      *
+     * @param endpointId 대상 엔드포인트 ID
+     * @param webhookSecret 새 시크릿 직접 지정 (미제공 시 서버 자동 생성)
+     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 엔드포인트
      *
      * @example
      * 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);
@@ -772,25 +751,35 @@ declare class SubscriptionsResource {
      * **일회성** (`recurring: false`): 등록 즉시 1회 크롤 후 종료합니다.
      * `endpointId` 없이 사용하면 결과를 `get(requestId)`으로 직접 조회할 수 있습니다.
      *
+     * @param items 추적할 택배 목록
+     * @param recurring true: 반복 구독, false: 1회성
+     * @param endpointId 웹훅 수신 엔드포인트 ID (선택)
+     *
      * @example
      * // 구독형 — 상태 변경 시 웹훅 수신
-     * const sub = await client.webhooks.subscriptions.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.subscriptions.register({
-     *   items: [{ courierCode: 'lotte', trackingNumber: '9876543210' }],
-     *   recurring: false,
-     * })
+     * // 일회성 — 웹훅 없이 결과를 직접 조회
+     * const req = await client.webhooks.subscriptions.register(
+     *   [{ courierCode: 'lotte', trackingNumber: '9876543210' }],
+     *   false,
+     * )
      * const detail = await client.webhooks.subscriptions.get(req.requestId)
      */
-    register(params: RegisterParams): Promise<RegisterResponse>;
+    register(params: {
+        items: {
+            courierCode: string;
+            trackingNumber: string;
+            clientId?: string;
+        }[];
+        recurring: boolean;
+        endpointId?: string;
+    }): Promise<RegisterResponse>;
     /**
      * 구독 목록을 조회합니다.
      *
@@ -811,8 +800,6 @@ declare class SubscriptionsResource {
     /**
      * 구독 상세 정보를 조회합니다.
      *
-     * 각 택배별 현재 상태 및 최신 배송 데이터를 포함합니다.
-     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 구독
      *
      * @example
@@ -825,8 +812,6 @@ declare class SubscriptionsResource {
     /**
      * 구독을 취소합니다.
      *
-     * 취소된 구독은 더 이상 폴링되지 않으며 웹훅도 발송되지 않습니다.
-     *
      * @throws {ApiError} `NOT_FOUND` — 존재하지 않는 구독
      *
      * @example
@@ -838,18 +823,23 @@ declare class SubscriptionsResource {
      *
      * 해당 계정에 등록된 구독 중 일치하는 아이템의 최신 상태를 반환합니다.
      *
+     * @param items 조회할 택배 목록
+     *
      * @example
-     * const { results } = await client.webhooks.subscriptions.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(params: {
+        items: {
+            courierCode: string;
+            trackingNumber: string;
+        }[];
+    }): Promise<BatchResultsResponse>;
 }
 
 /**