deliveryapi 1.8.0 → 1.10.0

package/dist/index.d.cts

@@ -1,542 +1,883 @@
 /**
- * 택배 배송 상태 코드 (정규화된 통합 상태)
+ * 택배 배송 상태 코드
  *
- * 모든 택배사의 상태를 하나의 공통 코드로 변환합니다.
- *
- * @example
- * if (result.deliveryStatus === CourierDeliveryStatus.DELIVERED) {
- *   console.log('배송 완료')
- * }
+ * 모든 택배사의 상태를 하나의 통합 코드로 정규화합니다.
  */
 declare enum CourierDeliveryStatus {
-    /** 접수 대기 */
-    PENDING = "PENDING",
-    /** 접수 완료 */
-    REGISTERED = "REGISTERED",
-    /** 집하 준비 */
-    PICKUP_READY = "PICKUP_READY",
-    /** 집하 완료 */
-    PICKED_UP = "PICKED_UP",
-    /** 배송 중 (간선 이동) */
-    IN_TRANSIT = "IN_TRANSIT",
-    /** 배송 출발 (배달기사 출발) */
-    OUT_FOR_DELIVERY = "OUT_FOR_DELIVERY",
-    /** 배송 완료 */
-    DELIVERED = "DELIVERED",
-    /** 배송 실패 */
-    FAILED = "FAILED",
-    /** 반송 */
-    RETURNED = "RETURNED",
-    /** 취소 */
-    CANCELLED = "CANCELLED",
-    /** 보류 */
-    HOLD = "HOLD",
-    /** 알 수 없음 */
+    PENDING = "PENDING",// 접수 대기
+    REGISTERED = "REGISTERED",// 접수 완료
+    PICKUP_READY = "PICKUP_READY",// 집하 준비
+    PICKED_UP = "PICKED_UP",// 집하 완료
+    IN_TRANSIT = "IN_TRANSIT",// 배송 중
+    OUT_FOR_DELIVERY = "OUT_FOR_DELIVERY",// 배송 출발
+    DELIVERED = "DELIVERED",// 배송 완료
+    FAILED = "FAILED",// 배송 실패
+    RETURNED = "RETURNED",// 반송
+    CANCELLED = "CANCELLED",// 취소
+    HOLD = "HOLD",// 보류
     UNKNOWN = "UNKNOWN"
 }
+
 /**
- * API 에러 코드
+ * API 에러 코드 (모든 엔드포인트 공통)
+ *
+ * ApiResponse.errorCode 필드에 포함되어 반환됩니다.
+ * 클라이언트가 에러 유형을 프로그래밍적으로 구분할 수 있도록 합니다.
  *
- * 에러 응답의 `errorCode` 필드에 포함됩니다.
- * 이 코드를 기준으로 클라이언트 분기 처리를 구현하세요.
+ * 참고: 택배 조회의 아이템별 에러는 TrackingErrorCode를 사용합니다.
+ *       (TrackingResult.error.code 필드)
  */
-type ApiErrorCode = 'UNAUTHORIZED' | 'FORBIDDEN' | 'RATE_LIMITED' | 'MISSING_PARAMS' | 'INVALID_PARAMS' | 'NOT_FOUND' | 'CONFLICT' | 'EXPIRED' | 'COURIER_OTP_REQUIRED' | 'COURIER_AUTH_FAILED' | 'WEBHOOK_INVALID_SIGNATURE' | 'WEBHOOK_ENDPOINT_LIMIT' | 'WEBHOOK_ENDPOINT_UNREACHABLE' | 'INTERNAL_ERROR';
+type ApiErrorCode = 'UNAUTHORIZED' | 'FORBIDDEN' | 'MISSING_PARAMS' | 'INVALID_PARAMS' | 'NOT_FOUND' | 'CONFLICT' | 'RATE_LIMITED' | 'EMAIL_ALREADY_EXISTS' | 'COURIER_OTP_REQUIRED' | 'COURIER_AUTH_FAILED' | 'WEBHOOK_ENDPOINT_LIMIT' | 'WEBHOOK_ENDPOINT_UNREACHABLE' | 'INVALID_ITEMS' | 'NOT_IMPLEMENTED' | 'INTERNAL_ERROR';
+
 /**
- * 택배 조회 아이템별 에러 코드
+ * 택배사 코드 상수 및 정보
  *
- * `trace()` 응답의 `results[].error.code`에 포함됩니다.
+ * ⚠️ 이 파일은 farmfree/packages/common과 별도로 관리됩니다
+ * - delivery-saas-api-functions는 완전히 독립된 프로젝트입니다
+ * - farmfree와 코드를 공유하지 않습니다 (API 호출만 함)
  */
-type TrackingErrorCode = 'MISSING_PARAMS' | 'INVALID_TRACKING_NUMBER' | 'UNSUPPORTED_COURIER' | 'NOT_FOUND' | 'TRACKING_FAILED';
+declare const COURIER_CODES: {
+    readonly LOTTE: "lotte";
+    readonly CJ: "cj";
+    readonly POST: "post";
+    readonly HANJIN: "hanjin";
+    readonly LOGEN: "logen";
+    readonly GSPOSTBOX: "gspostbox";
+    readonly ILYANG: "ilyang";
+    readonly KYUNGDONG: "kyungdong";
+    readonly DAESIN: "daesin";
+    readonly HAPDONG: "hapdong";
+    readonly COUPANG: "coupang";
+    readonly WOORI: "woori";
+};
+type CourierCode = (typeof COURIER_CODES)[keyof typeof COURIER_CODES];
+
+/**
+ * 택배사 ID 타입
+ * COURIER_INFO_MAP의 CourierCode와 동일
+ */
+type CourierProviderId = CourierCode;
+
+/**
+ * 개별 택배 조회 항목
+ */
+interface TrackingItem {
+    id?: string;
+    clientId?: string;
+    courierCode: string;
+    trackingNumber: string;
+}
+/**
+ * 택배 조회 요청 (배열로 다건 지원)
+ */
+interface TrackingRequest {
+    items: TrackingItem[];
+    includeProgresses?: boolean;
+}
 /**
- * 배송 진행 내역 한 건
+ * 택배 진행 상황
  */
 interface TrackingProgress {
-    /** 처리 시간 (ISO 8601) */
     dateTime: string;
-    /** 처리 위치 (예: "서울 허브") */
     location: string;
-    /** 택배사 원본 상태 텍스트 */
     status: string;
-    /** 정규화된 상태 코드 */
     statusCode?: CourierDeliveryStatus;
-    /** 상세 설명 */
     description?: string;
-    /** 연락처 */
     telno?: string;
-    /** 추가 연락처 */
     telno2?: string;
 }
 /**
- * 통합 택배 조회 결과 (단건)
+ * 통합 택배 조회 응답
  */
 interface UnifiedTrackingResponse {
-    /** 송장번호 */
     trackingNumber: string;
-    /** 택배사 코드 (예: `'cj'`, `'lotte'`) */
     courierCode: string;
-    /** 택배사 이름 (예: `'CJ대한통운'`) */
     courierName: string;
-    /** 정규화된 배송 상태 코드 */
     deliveryStatus: CourierDeliveryStatus;
-    /** 택배사 원본 상태 텍스트 */
     deliveryStatusText: string;
-    /** 배송 완료 여부 */
     isDelivered: boolean;
-    /** 발송인 이름 */
     senderName?: string;
-    /** 수취인 이름 */
     receiverName?: string;
-    /** 수취인 주소 */
     receiverAddress?: string;
-    /** 상품명 */
     productName?: string;
-    /** 수량 */
     productQuantity?: number;
-    /** 배송 완료일 (ISO 8601, 완료 시에만 존재) */
     dateDelivered?: string;
-    /** 배송 예정일 (ISO 8601) */
     dateEstimated?: string;
-    /** 마지막 진행 날짜/시간 (`yyyy-MM-dd HH:mm:ss`) */
     dateLastProgress: string;
-    /** 배송 진행 내역 (최신순) */
     progresses: TrackingProgress[];
-    /** 조회 시점 (ISO 8601) */
     queriedAt: string;
 }
 /**
- * 단건 조회 항목
+ * 택배 조회 에러 코드
+ *
+ * 과금 정책:
+ * - NOT_FOUND만 과금 (택배사 API를 호출했으나 데이터 없음 = 사용자 책임)
+ * - 나머지는 비과금 (요청 검증 실패 또는 시스템 오류)
  */
-interface TraceItem {
-    /** 택배사 코드 (예: `'cj'`, `'lotte'`, `'hanjin'`) */
-    courierCode: string;
-    /** 송장번호 */
-    trackingNumber: string;
-    /**
-     * 클라이언트 매핑 ID (선택)
-     *
-     * 주문번호 등 내부 식별자를 넣으면 응답에 그대로 반환됩니다.
-     */
-    clientId?: string;
+type TrackingErrorCode = 'MISSING_PARAMS' | 'INVALID_TRACKING_NUMBER' | 'UNSUPPORTED_COURIER' | 'NOT_FOUND' | 'TRACKING_FAILED';
+/**
+ * 택배 조회 오류
+ */
+interface TrackingError {
+    code: TrackingErrorCode;
+    message: string;
+    courierCode?: string;
+    trackingNumber?: string;
+    details?: unknown;
+    billable: boolean;
 }
 /**
- * `tracking.trace()` 파라미터
+ * 택배 조회 아이템별 에러 (courierCode, trackingNumber 필수)
  *
- * @example
- * const result = await client.tracking.trace({
- *   items: [
- *     { courierCode: 'cj', trackingNumber: '1234567890', clientId: 'order_001' }
- *   ],
- *   includeProgresses: true,
- * })
+ * TrackingError의 변형으로, 개별 조회 결과에서 사용
+ * (courierCode/trackingNumber가 반드시 존재하는 경우)
  */
-interface TraceParams {
-    /** 조회할 택배 목록 (1건도 배열로 전달) */
-    items: TraceItem[];
-    /**
-     * 배송 진행 내역 포함 여부
-     *
-     * `false`로 설정하면 `progresses`가 빈 배열로 반환됩니다.
-     * 상태만 확인할 때 사용하면 응답 크기가 줄어듭니다.
-     * @default true
-     */
-    includeProgresses?: boolean;
-}
-/** 아이템별 조회 에러 */
-interface TraceItemError {
-    /** 에러 코드 */
+interface TrackingItemError {
     code: TrackingErrorCode;
-    /** 에러 메시지 */
     message: string;
-    /** 택배사 코드 */
     courierCode: string;
-    /** 송장번호 */
     trackingNumber: string;
-    /**
-     * 과금 여부
-     *
-     * `true`이면 이 건은 사용량으로 집계됩니다.
-     * `NOT_FOUND` 에러만 과금됩니다.
-     */
     billable: boolean;
 }
-/** 아이템별 캐시 정보 */
-interface TraceCacheInfo {
-    /** 캐시에서 반환된 경우 `true` */
+/**
+ * 캐시 메타데이터
+ */
+interface TrackingCacheInfo {
     fromCache: boolean;
-    /** 캐시 저장 시점 (ISO 8601, 캐시 히트 시에만 존재) */
     cachedAt?: string;
 }
-/** 단건 택배 조회 결과 */
-interface TraceResult {
-    /** 요청 시 전달된 `clientId` (있으면 그대로 반환) */
+/**
+ * 개별 택배 조회 결과
+ */
+interface TrackingResult {
+    id?: string;
     clientId?: string;
-    /** 조회 성공 여부 */
     success: boolean;
-    /** 성공 시 배송 정보 */
     data?: UnifiedTrackingResponse;
-    /** 실패 시 에러 정보 */
-    error?: TraceItemError;
-    /** 캐시 정보 */
-    cache?: TraceCacheInfo;
-}
-/** `tracking.trace()` 응답 */
-interface TraceResponse {
-    /** 아이템별 결과 (요청 순서와 동일) */
-    results: TraceResult[];
-    /** 집계 요약 */
+    error?: TrackingError;
+    cache?: TrackingCacheInfo;
+}
+/**
+ * 택배 조회 응답 (배열로 다건 응답)
+ */
+interface TrackingResponse {
+    results: TrackingResult[];
     summary: {
-        /** 전체 요청 건수 */
         total: number;
-        /** 성공 건수 */
         successful: number;
-        /** 실패 건수 */
         failed: number;
-        /** 과금 대상 건수 (성공 + `NOT_FOUND`) */
         billable: number;
     };
 }
-/** 지원 택배사 정보 */
-interface CourierInfo {
+
+/**
+ * Firebase Timestamp 호환 인터페이스
+ * firebase-admin/firestore 및 firebase/firestore의 Timestamp와 구조적으로 호환됨
+ */
+interface Timestamp {
+    seconds: number;
+    nanoseconds: number;
+    toDate(): Date;
+    toMillis(): number;
+    isEqual(other: Timestamp): boolean;
+    valueOf(): string;
+}
+
+/**
+ * 웹훅 시스템 타입 정의
+ * - 다건 추적 요청 (최대 100건)
+ * - 재시도 없음 (1시간 폴링이 자연 재전송)
+ * - 엔드포인트별 독립 컬렉션
+ */
+
+type TrackingBatchStatus = 'active' | 'completed' | 'cancelled';
+interface TrackingBatchSummary {
+    total: number;
+    delivered: number;
+    active: number;
+    failed: number;
+}
+/**
+ * 웹훅으로 전송되는 개별 항목
+ */
+interface WebhookTrackingItem {
+    courierCode: string;
+    trackingNumber: string;
+    clientId?: string;
+    currentStatus: CourierDeliveryStatus;
+    previousStatus?: CourierDeliveryStatus;
+    hasChanged: boolean;
+    isDelivered: boolean;
+    trackingData?: UnifiedTrackingResponse;
+    error?: string;
+}
+/**
+ * 웹훅 POST 페이로드
+ */
+interface WebhookPayload {
+    event: 'tracking.polled' | 'tracking.completed';
+    requestId: string;
+    timestamp: string;
+    summary: {
+        total: number;
+        delivered: number;
+        active: number;
+        hasChanges: boolean;
+    };
+    items: WebhookTrackingItem[];
+    metadata?: Record<string, string>;
+}
+
+/** 지원 택배사 정보 (API 응답용) */
+interface CourierInfoResponse {
     /** 택배사 코드 (예: `'cj'`, `'lotte'`) */
     trackingApiCode: string;
     /** 택배사 표시명 (예: `'CJ대한통운'`) */
     displayName: string;
 }
-/** `tracking.getCouriers()` 응답 */
-interface GetCouriersResponse {
-    /** 지원 택배사 목록 */
-    couriers: CourierInfo[];
-    /** 전체 택배사 수 */
+/** GET /v1/tracking/couriers 응답 */
+interface GetCouriersApiResponse {
+    couriers: CourierInfoResponse[];
     total: number;
 }
-/**
- * `webhooks.endpoints.create()` 파라미터
- *
- * @example
- * const endpoint = await client.webhooks.endpoints.create({
- *   url: 'https://my-server.com/webhook',
- *   name: '운영 서버',
- * })
- * // endpoint.webhookSecret 은 이 응답에서만 확인 가능합니다 — 안전하게 보관하세요!
- */
-interface CreateEndpointParams {
-    /**
-     * 웹훅을 수신할 URL
-     *
-     * `https://` 로 시작해야 합니다.
-     * 등록 시 서버에서 테스트 POST 요청을 전송하여 URL을 검증합니다.
-     */
+/** POST /v1/webhooks/endpoints 요청 */
+interface CreateEndpointRequest {
+    /** 웹훅 수신 URL (https:// 필수) */
     url: string;
-    /** 엔드포인트 이름 (관리용) */
-    name: string;
-    /**
-     * 서명 시크릿 직접 지정 (선택)
-     *
-     * 미제공 시 서버가 랜덤 시크릿을 생성합니다.
-     * 최소 5자 이상이어야 합니다.
-     */
+    /** 엔드포인트 이름 */
+    name?: string;
+    /** 서명 시크릿 직접 지정 (선택, 미제공 시 서버 생성, 최소 5자) */
     webhookSecret?: string;
 }
-/** `webhooks.endpoints.create()` 응답 */
-interface CreateEndpointResponse {
-    /** 생성된 엔드포인트 ID */
+/** POST /v1/webhooks/endpoints 응답 */
+interface CreateEndpointApiResponse {
     endpointId: string;
-    /** 등록된 URL */
     url: string;
-    /** 엔드포인트 이름 */
     name?: string;
-    /**
-     * 웹훅 서명 시크릿
-     *
-     * **이 응답에서만 평문으로 반환됩니다. 이후에는 조회 불가합니다.**
-     * 분실 시 `rotateSecret()`으로 재발급해야 합니다.
-     *
-     * 수신된 웹훅의 `X-Webhook-Signature` 헤더를 이 값으로 HMAC-SHA256 검증하세요.
-     */
+    /** 최초 1회만 평문 반환 */
     webhookSecret: string;
-    /** 생성 시각 (ISO 8601) */
     dateCreated: string;
 }
 /** 엔드포인트 목록 아이템 */
-interface EndpointInfo {
-    /** 엔드포인트 ID */
+interface EndpointListItem {
     endpointId: string;
-    /** 웹훅 수신 URL */
     url: string;
-    /** 엔드포인트 이름 */
     name?: string;
-    /**
-     * 엔드포인트 상태
-     *
-     * 연속 5회 이상 전송 실패 시 자동으로 `inactive` 로 전환됩니다.
-     */
     status: 'active' | 'inactive';
-    /**
-     * 연속 실패 횟수
-     *
-     * 5회 초과 시 엔드포인트가 비활성화됩니다.
-     */
     consecutiveFailures: number;
-    /** 생성 시각 (ISO 8601) */
     dateCreated: string;
-    /** 최종 수정 시각 (ISO 8601) */
     dateModified: string;
 }
-/** `webhooks.endpoints.list()` 응답 */
-interface ListEndpointsResponse {
-    /** 등록된 엔드포인트 목록 */
-    endpoints: EndpointInfo[];
-    /** 전체 수 */
+/** GET /v1/webhooks/endpoints 응답 */
+interface ListEndpointsApiResponse {
+    endpoints: EndpointListItem[];
     total: number;
 }
-/**
- * `webhooks.endpoints.update()` 파라미터
- *
- * URL은 변경할 수 없습니다. 이름만 수정 가능합니다.
- */
-interface UpdateEndpointParams {
-    /** 새 엔드포인트 이름 */
+/** PATCH /v1/webhooks/endpoints/:id 요청 */
+interface UpdateEndpointRequest {
+    /** name만 변경 가능, URL 변경 불가 */
     name: string;
 }
-/**
- * `webhooks.endpoints.rotateSecret()` 파라미터
- */
-interface RotateSecretParams {
-    /**
-     * 새 시크릿 직접 지정 (선택)
-     *
-     * 미제공 시 서버가 랜덤 시크릿을 생성합니다.
-     */
+/** POST /v1/webhooks/endpoints/:id/rotate-secret 요청 */
+interface RotateSecretRequest {
+    /** 새 시크릿 직접 지정 (선택, 미제공 시 서버 생성) */
     webhookSecret?: string;
 }
-/** `webhooks.endpoints.rotateSecret()` 응답 */
-interface RotateSecretResponse {
-    /** 엔드포인트 ID */
+/** POST /v1/webhooks/endpoints/:id/rotate-secret 응답 */
+interface RotateSecretApiResponse {
     endpointId: string;
-    /**
-     * 새 웹훅 서명 시크릿
-     *
-     * **이 응답에서만 평문으로 반환됩니다.**
-     */
+    /** 최초 1회만 평문 반환 */
     webhookSecret: string;
-    /** 재발급 시각 (ISO 8601) */
     dateRotated: string;
 }
-/** 구독 등록 아이템 */
-interface RegisterItem {
-    /** 택배사 코드 (예: `'cj'`, `'lotte'`) */
+/** 추적 등록 아이템 */
+interface RegisterTrackingItem {
     courierCode: string;
-    /** 송장번호 */
     trackingNumber: string;
-    /**
-     * 클라이언트 매핑 ID (선택)
-     *
-     * 주문번호 등을 넣으면 웹훅 페이로드에 그대로 포함됩니다.
-     */
+    /** 클라이언트 매핑 ID (선택, 웹훅 페이로드에 그대로 포함) */
     clientId?: string;
 }
-/** `webhooks.subscriptions.register()` 응답 */
-interface RegisterResponse {
-    /**
-     * 구독/요청 ID
-     *
-     * `subscriptions.get(requestId)`, `subscriptions.cancel(requestId)` 에 사용합니다.
-     */
+/** POST /v1/webhooks/subscriptions 응답 */
+interface RegisterTrackingApiResponse {
     requestId: string;
-    /** 등록된 아이템 수 */
     itemCount: number;
-    /** 반복 구독 여부 */
     recurring: boolean;
 }
-/** 구독 요약 정보 */
-interface SubscriptionSummary {
-    /** 전체 택배 수 */
-    total: number;
-    /** 배송 완료 수 */
-    delivered: number;
-    /** 배송 진행 중 수 */
-    active: number;
-    /** 조회 실패 수 */
-    failed: number;
-}
-/** `webhooks.subscriptions.list()` 파라미터 */
-interface ListSubscriptionsParams {
-    /**
-     * 페이지네이션 커서
-     *
-     * 이전 응답의 `nextCursor` 값을 전달합니다.
-     * 생략하면 처음부터 조회합니다.
-     */
+/** GET /v1/webhooks/subscriptions 요청 파라미터 */
+interface ListSubscriptionsRequest {
+    /** 페이지네이션 커서 (이전 응답의 nextCursor) */
     cursor?: string;
-    /** 페이지 크기 */
     limit?: number;
+    status?: 'active' | 'completed' | 'cancelled';
+    /** 시작일 필터 (YYYY-MM-DD) */
+    from?: string;
+    /** 종료일 필터 (YYYY-MM-DD) */
+    to?: string;
 }
 /** 구독 목록 아이템 */
 interface SubscriptionListItem {
-    /** 구독 ID */
     requestId: string;
-    /** 연결된 엔드포인트 ID */
     endpointId?: string;
-    /** 반복 구독 여부 */
     recurring: boolean;
-    /** 구독 활성 여부 */
     isActive: boolean;
-    /** 등록된 아이템 수 */
+    status: TrackingBatchStatus;
     itemCount: number;
-    /** 요약 */
-    summary: SubscriptionSummary;
-    /** 등록 시각 (ISO 8601) */
+    summary: {
+        total: number;
+        delivered: number;
+        active: number;
+        failed: number;
+    };
     dateCreated: string;
 }
-/** `webhooks.subscriptions.list()` 응답 */
-interface ListSubscriptionsResponse {
-    /** 구독 목록 */
+/** GET /v1/webhooks/subscriptions 응답 */
+interface ListSubscriptionsApiResponse {
     subscriptions: SubscriptionListItem[];
-    /** 전체 수 */
     total: number;
-    /**
-     * 다음 페이지 커서
-     *
-     * 마지막 페이지이면 존재하지 않습니다.
-     */
+    /** 다음 페이지 커서 (마지막 페이지이면 없음) */
     nextCursor?: string;
 }
-/** 구독 상세 아이템 (개별 택배) */
-interface SubscriptionItem {
-    /** 택배사 코드 */
+/** 추적 결과 아이템 (구독 상세/배치 결과에서 사용) */
+interface TrackingResultItem {
     courierCode: string;
-    /** 송장번호 */
     trackingNumber: string;
-    /** 클라이언트 매핑 ID */
     clientId?: string;
-    /** 현재 배송 상태 */
     currentStatus: CourierDeliveryStatus;
-    /** 이전 배송 상태 */
     previousStatus?: CourierDeliveryStatus;
-    /** 상태 변경 여부 */
     hasChanged: boolean;
-    /** 배송 완료 여부 */
     isDelivered: boolean;
-    /** 최신 배송 조회 데이터 */
     trackingData?: UnifiedTrackingResponse;
-    /** 조회 에러 메시지 (실패 시) */
     error?: string;
 }
-/** `webhooks.subscriptions.get()` 응답 */
-interface SubscriptionDetail {
-    /** 구독 ID */
+/** GET /v1/webhooks/subscriptions/:id 응답 */
+interface SubscriptionDetailApiResponse {
     requestId: string;
-    /** 연결된 엔드포인트 ID */
     endpointId?: string;
-    /** 반복 구독 여부 */
     recurring: boolean;
-    /** 구독 활성 여부 */
     isActive: boolean;
-    /** 등록된 아이템 수 */
+    status: TrackingBatchStatus;
     itemCount: number;
-    /** 요약 */
-    summary: SubscriptionSummary;
-    /** 각 택배별 상세 상태 */
-    items: SubscriptionItem[];
-    /** 마지막 폴링 시각 (ISO 8601) */
+    summary: {
+        total: number;
+        delivered: number;
+        active: number;
+        failed: number;
+    };
+    items: TrackingResultItem[];
     lastPolledAt?: string;
-    /** 다음 폴링 예정 시각 (ISO 8601) */
     nextPollAt?: string;
-    /** 이용자 정의 메타데이터 */
     metadata?: Record<string, string>;
-    /** 등록 시각 (ISO 8601) */
     dateCreated: string;
-    /** 최종 수정 시각 (ISO 8601) */
     dateModified: string;
 }
-/** `webhooks.subscriptions.batchResults()` 파라미터 아이템 */
+/** 배치 결과 검색 아이템 */
 interface BatchResultItem {
-    /** 택배사 코드 */
     courierCode: string;
-    /** 송장번호 */
     trackingNumber: string;
 }
-/**
- * `webhooks.subscriptions.batchResults()` 파라미터
- *
- * 여러 송장번호의 최신 배송 정보를 한 번에 조회합니다.
- * 구독 ID가 아닌 (택배사 코드 + 송장번호)로 검색합니다.
- */
-interface BatchResultsParams {
-    /** 조회할 아이템 목록 */
+/** POST /v1/webhooks/subscriptions/batch-results 요청 */
+interface BatchResultsRequest {
     items: BatchResultItem[];
 }
 /** 배치 결과 단건 */
 interface BatchResultEntry {
-    /** 택배사 코드 */
     courierCode: string;
-    /** 송장번호 */
     trackingNumber: string;
-    /** 클라이언트 매핑 ID */
     clientId?: string;
-    /** 구독 ID */
     requestId: string;
-    /** 현재 배송 상태 */
     currentStatus: CourierDeliveryStatus;
-    /** 배송 완료 여부 */
     isDelivered: boolean;
-    /** 최신 배송 데이터 */
     trackingData?: UnifiedTrackingResponse;
-    /** 에러 메시지 (실패 시) */
     error?: string;
-    /** 마지막 폴링 시각 (ISO 8601) */
     lastPolledAt?: string;
 }
-/** `webhooks.subscriptions.batchResults()` 응답 */
-interface BatchResultsResponse {
-    /** 결과 목록 */
+/** POST /v1/webhooks/subscriptions/batch-results 응답 */
+interface BatchResultsApiResponse {
     results: BatchResultEntry[];
-    /** 전체 수 */
     total: number;
 }
+
 /**
- * 웹훅 수신 페이로드
- *
- * 배송 상태 변경 시 등록된 엔드포인트로 POST 요청이 전송됩니다.
- * `X-Webhook-Signature` 헤더를 `webhookSecret`으로 HMAC-SHA256 검증하세요.
- *
- * @example
- * // Express 수신 예시
- * app.post('/webhook', (req, res) => {
- *   const sig = req.headers['x-webhook-signature']
- *   const body = JSON.stringify(req.body)
- *   const expected = crypto.createHmac('sha256', webhookSecret).update(body).digest('hex')
- *   if (sig !== expected) return res.status(401).send('Invalid signature')
+ * transmitting: sent to courier but no response received (may or may not be registered — system failure)
+ * completed: courier response received + all successful items have courierDeliveryId secured
+ * failed: courier response received + all items rejected (zero successes)
  *
- *   const payload: WebhookPayload = req.body
- *   if (payload.event === 'tracking.completed') {
- *     console.log(`${payload.requestId} 배송 추적 완료`)
- *   }
- *   res.sendStatus(200)
- * })
+ * Note: pre-validation failures (auth, address format, etc.) do not create a history document
  */
-interface WebhookPayload {
+type BulkUploadStatus = 'transmitting' | 'completed' | 'failed' | 'deleted';
+
+/**
+ * 배송 주소 정보
+ */
+interface DeliveryAddress {
+    zipCode?: string;
+    roadAddress?: string;
+    jibunAddress?: string;
+    detailAddress?: string;
+    fullAddress: string;
+}
+/**
+ * 배송 담당자 정보
+ */
+interface DeliveryPerson {
+    name: string;
+    phoneNumber?: string;
+    branchName?: string;
+    branchCode?: string;
+    branchPhone?: string;
+}
+/**
+ * 요금 정보
+ */
+interface FareInfo {
+    fareType: string;
+    fareTypeCode?: string;
+}
+/**
+ * 택배 계정 조회 응답 (개별 배송 정보)
+ * UnifiedTrackingResponse를 확장하여 계정 조회에 필요한 추가 정보 포함
+ */
+interface AccountInquiryItem {
+    courierTrackingId: string;
+    trackingNumber: string;
+    orderNumber?: string;
+    courierCode: string;
+    courierName: string;
+    deliveryStatus: CourierDeliveryStatus;
+    deliveryStatusText: string;
+    isDelivered: boolean;
+    cancelReason?: string;
+    isReturn?: boolean;
+    returnType?: string;
+    originalTrackingNumber?: string;
+    senderName: string;
+    senderPhone?: string;
+    senderPhone2?: string;
+    senderAddress?: DeliveryAddress;
+    receiverName: string;
+    receiverPhone: string;
+    receiverPhone2?: string;
+    receiverAddress: DeliveryAddress;
+    productName: string;
+    productQuantity: number;
+    productDetails?: string;
+    productOption?: string;
+    deliveryMessage?: string;
+    pickupDate?: string;
+    firstScanDate?: string;
+    deliveryDate?: string;
+    estimatedDeliveryDate?: string;
+    pickupBranch?: DeliveryPerson;
+    deliveryBranch?: DeliveryPerson;
+    pickupPerson?: DeliveryPerson;
+    deliveryPerson?: DeliveryPerson;
+    fareInfo?: FareInfo;
+    accountCustomerCode?: string;
+    accountCustomerName?: string;
+    pickupCustomerCode?: string;
+    pickupCustomerName?: string;
+    queriedAt: string;
+    rawData?: Record<string, unknown>;
+}
+/**
+ * 택배 계정 조회 응답
+ */
+interface AccountInquiryResponse {
+    items: AccountInquiryItem[];
+    summary: {
+        total: number;
+        pending: number;
+        inTransit: number;
+        delivered: number;
+        cancelled: number;
+        returned: number;
+    };
+    dateRange: {
+        from: string;
+        to: string;
+    };
+    courierInfo: {
+        courierCode: string;
+        courierName: string;
+        accountId: string;
+    };
+    lastUpdated: string;
+}
+
+/** Parameters for registering a courier account */
+interface RegisterAccountParams {
+    /** Courier provider ID */
+    providerId: 'lotte' | 'cj';
+    /** Account login ID */
+    accountId: string;
+    /** Account login password */
+    accountPassword: string;
+    /** Display name for the account */
+    accountName?: string;
+    /** Account description */
+    description?: string;
+    /** Enable automatic SMS OTP capture (CJ 2FA accounts) */
+    smsAutoCapture?: boolean;
+    /** Phone number for receiving OTP SMS (used with smsAutoCapture) */
+    phoneNumber?: string;
+}
+/** Response from account registration (formatAccountResponse — 6 fields) */
+interface RegisterAccountResponse {
+    /** Unique key for the registered account */
+    courierAccountKey: string;
+    /** Courier provider ID */
+    providerId: string;
+    /** Account login ID */
+    accountId: string;
+    /** Display name */
+    accountName: string;
+    /** Whether the account is active */
+    isActive: boolean;
+    /** Whether 2FA (OTP) is required */
+    requires2FA: boolean;
+}
+/** Account info returned in list response (GET /courier/accounts) */
+interface CourierAccountInfo {
+    courierAccountKey: string;
+    providerId: string;
+    accountId: string;
+    accountName: string;
+    description: string;
+    isActive: boolean;
+    requires2FA: boolean;
+    smsAutoCapture: boolean;
+    /** Last inquiry date (ISO 8601) */
+    lastInquiryDate: string | null;
+    /** Account creation date (ISO 8601) */
+    dateCreated: string | null;
+    /** Token expiration date (ISO 8601) */
+    expiresAt: string | null;
+}
+/** Account detail returned by GET /courier/accounts/:accountKey (no expiresAt, has accountPassword) */
+interface CourierAccountDetail extends Omit<CourierAccountInfo, 'expiresAt'> {
+    /** Always "(암호화하여 저장중)" — actual password is never exposed */
+    accountPassword: string;
+}
+/** SDK-friendly bulk upload item — sender fields are optional (account defaults used) */
+interface BulkUploadItemParams {
+    /** Client-side order ID for result matching */
+    clientOrderId: string;
+    /** Receiver name */
+    receiverName: string;
+    /** Receiver phone number */
+    receiverPhone1: string;
+    /** Receiver address (road or jibun) */
+    receiverAddress: string;
+    /** Product name */
+    productName: string;
+    /** Product quantity */
+    quantity: number;
+    /** Receiver secondary phone */
+    receiverPhone2?: string;
+    /** Receiver detail address (building, floor, etc.) */
+    receiverDetailAddress?: string;
+    /** Receiver zip code */
+    receiverZipCode?: string;
+    /** Sender name (omit to use account default) */
+    senderName?: string;
+    /** Sender phone number (omit to use account default) */
+    senderPhone1?: string;
+    /** Sender secondary phone */
+    senderPhone2?: string;
+    /** Sender address (omit to use account default) */
+    senderAddress?: string;
+    /** Sender detail address */
+    senderDetailAddress?: string;
+    /** Sender zip code */
+    senderZipCode?: string;
+    /** Delivery message for the courier */
+    deliveryMessage?: string;
+}
+/** Parameters for bulk upload */
+interface BulkUploadParams {
+    /** Courier account key (from register or list) */
+    courierAccountKey: string;
+    /** Items to upload (max 1,000) */
+    items: BulkUploadItemParams[];
+}
+/** Delivery status filter for inquiry */
+type DeliveryStatusFilter = 'all' | 'delivered' | 'not_delivered' | 'in_transit' | 'pending';
+/** Parameters for delivery inquiry */
+interface InquiryParams {
+    /** Courier account key */
+    courierAccountKey: string;
+    /** Start date (YYYY-MM-DD) */
+    fromDate: string;
+    /** End date (YYYY-MM-DD) */
+    toDate: string;
     /**
-     * 이벤트 유형
-     *
-     * - `tracking.polled`: 주기적 폴링 결과 (상태 변경 또는 최신 정보)
-     * - `tracking.completed`: 배송 완료 또는 구독 종료
+     * Delivery status filter
+     * - `'all'` — all statuses (default)
+     * - `'delivered'` — delivered only
+     * - `'not_delivered'` — failed delivery only
+     * - `'in_transit'` — in transit / out for delivery
+     * - `'pending'` — pending / registered / pickup ready / picked up
      */
-    event: 'tracking.polled' | 'tracking.completed';
-    /** 구독 ID */
-    requestId: string;
-    /** 연결된 엔드포인트 ID */
-    endpointId: string;
-    /** 이용자 정의 메타데이터 */
-    metadata?: Record<string, string>;
-    /** 각 택배별 상태 정보 */
-    items: SubscriptionItem[];
-    /** 요약 */
-    summary: SubscriptionSummary;
-    /** 이벤트 발생 시각 (ISO 8601) */
-    timestamp: string;
+    statusFilter?: DeliveryStatusFilter;
+    /** Include raw courier data in response */
+    includeDetails?: boolean;
+}
+/** Parameters for dashboard statistics (GET — sent as query params) */
+interface DashboardParams {
+    /** Courier account key */
+    courierAccountKey: string;
+    /** Start date (YYYY-MM-DD) */
+    fromDate: string;
+    /** End date (YYYY-MM-DD) */
+    toDate: string;
+}
+/** Parameters for cancelling deliveries */
+interface CancelDeliveriesParams {
+    /** Courier account key */
+    courierAccountKey: string;
+    /** Courier delivery IDs to cancel */
+    courierDeliveryIds: string[];
+}
+/** SDK-facing bulk upload history item (Timestamp → ISO string) */
+interface BulkUploadHistoryItemInfo {
+    /** Item index within the upload batch (0-based) */
+    requestIndex: number;
+    /** Client-provided order ID */
+    clientOrderId: string;
+    /** Receiver name */
+    receiverName: string;
+    /** Product name */
+    productName: string;
+    /** Whether this item was uploaded successfully */
+    success: boolean;
+    /** Result message */
+    message: string;
+    /** Tracking number (issued at print time, may be undefined) */
+    trackingNumber?: string;
+    /** Courier management number (issued at upload time) */
+    courierDeliveryId?: string;
+    /** Print date (ISO 8601, set when printed) */
+    datePrinted?: string;
+}
+/** SDK-facing bulk upload history (Timestamp → ISO string, internal fields omitted) */
+interface BulkUploadHistoryInfo {
+    /** History document ID (yyyyMMddHHmm_random5chars) */
+    id: string;
+    /** Courier account key */
+    courierAccountKey: string;
+    /** Courier provider ID */
+    providerId: string;
+    /** Upload status */
+    status: BulkUploadStatus;
+    /** Total items in upload */
+    totalCount: number;
+    /** Successfully uploaded items */
+    successCount: number;
+    /** Failed items */
+    failCount: number;
+    /** Individual item results */
+    items: BulkUploadHistoryItemInfo[];
+    /** Courier file acceptance number (CJ: actual value, Lotte: null) */
+    fileAcptOdrNo: string | null;
+    /** Last management number before registration (Lotte only) */
+    lastRsrvMgrNo: string | null;
+    /** Upload creation date (ISO 8601) */
+    dateCreated: string | null;
+    /** Last modification date (ISO 8601) */
+    dateModified: string | null;
+}
+/** Parameters for listing bulk upload histories (GET — sent as query params) */
+interface ListHistoriesParams {
+    /** Courier provider ID (required) */
+    providerId: string;
+    /** Filter by courier account key */
+    courierAccountKey?: string;
+    /** Start date filter (YYYY-MM-DD) */
+    fromDate?: string;
+    /** End date filter (YYYY-MM-DD) */
+    toDate?: string;
+    /** Max number of results (default 50) */
+    limit?: number;
+}
+/** Response from listing bulk upload histories */
+interface ListHistoriesResponse {
+    histories: BulkUploadHistoryInfo[];
+}
+/** Parameters for getting history detail */
+interface HistoryDetailParams {
+    /** Courier account key (required for ownership verification) */
+    courierAccountKey: string;
+}
+/** Response from getting history detail (history + live delivery status) */
+interface HistoryDetailResponse {
+    /** The bulk upload history record */
+    history: BulkUploadHistoryInfo;
+    /** Live delivery status for items in this upload (from courier API) */
+    detailItems: AccountInquiryItem[];
+}
+/** Parameters for deleting/cancelling a bulk upload history */
+interface DeleteHistoryParams {
+    /** Courier account key (required for ownership verification) */
+    courierAccountKey: string;
+    /** Specific delivery IDs to cancel (omit for full cancel/delete) */
+    courierDeliveryIds?: string[];
+}
+/** Parameters for creating a print session */
+interface CreatePrintSessionParams {
+    /** Courier account key */
+    courierAccountKey: string;
+    /** Courier provider ID */
+    providerId: string;
+    /** Specific courier tracking IDs to print */
+    courierTrackingIds?: string[];
+    /** Print all items from a bulk upload history */
+    bulkUploadHistoryId?: string;
+}
+/** Response from creating a print session */
+interface PrintSessionResponse {
+    /** Session ID for accessing the print page */
+    sessionId: string;
+    /** Session expiration time (ISO 8601, 10-minute TTL) */
+    expiresAt: string;
+}
+
+/**
+ * 개별 택배 정보
+ * - OrderPen.deliveryItems에 저장되는 배송 정보
+ * - AccountInquiryItem보다 간소화된 형태 (DB 저장용)
+ */
+interface DeliveryItem {
+    id: string;
+    courierProvider: CourierProviderId;
+    courierAccountId: string;
+    courierTrackingId: string;
+    trackingNumber: string;
+    deliveryStatus: CourierDeliveryStatus;
+    isPickupScanned: boolean;
+    isReturn: boolean;
+    dateCreated: Timestamp;
+    dateModified: Timestamp;
+    cancelReason: string;
+    accountCustomerCode?: string;
+    accountCustomerName?: string;
+}
+
+/**
+ * 대량 업로드 응답 타입 정의
+ * ⚠️ farmfree와 동기화 필요 (packages/common/types/courierSaas/bulkUpload.ts)
+ */
+
+/**
+ * 개별 아이템 업로드 결과
+ */
+interface BulkUploadResultItem$1 {
+    requestIndex: number;
+    success: boolean;
+    message: string;
+    trackingNumber?: string;
+    courierDeliveryId?: string;
+    clientOrderId?: string;
+    quantityOriginal: number;
+    quantityUploaded: number;
+    skipped: boolean;
+    skipReason?: string;
+    deliveryItem?: DeliveryItem;
+    courierMetadata?: {
+        acceptanceDate?: string;
+        acceptanceFileNo?: string;
+    };
+}
+/**
+ * 대량 업로드 전체 응답
+ */
+interface BulkUploadResponse$1 {
+    success: boolean;
+    historyId: string;
+    totalRequested: number;
+    totalUploaded: number;
+    totalSkipped: number;
+    totalFailed: number;
+    results: BulkUploadResultItem$1[];
+    fileAcptOdrNo?: string;
+    acptDt?: string;
+    warning?: string;
+}
+
+/**
+ * 대시보드 통계 인터페이스
+ * 롯데택배 API 응답 기준으로 설계
+ * 모든 택배사가 동일한 형식으로 반환해야 함
+ */
+/**
+ * 대시보드 통계 항목
+ * 개별 데이터 및 집계 데이터를 포함
+ */
+interface DashboardStatsItem {
+    totCnt: number;
+    prtCnt: number;
+    nonPrtCnt: number;
+    pickCnt: number;
+    pickCclCnt: number;
+    outCnt: number;
+    nonOutCnt: number;
+    arvCnt: number;
+    nonArvCnt: number;
+    dlvcpCnt: number;
+    nonDlvCnt: number;
+    invRgstCnt: number;
+    nonInvRgstCnt: number;
+    dlvbCnt: number;
+    pcadCnt: number;
+    stbhCnt: number;
+    pickYmd: string | null;
+    fstmIstrYmd: string | null;
+    ustRtgSctCd: string | null;
+    ustRtgSctNm: '출고' | '반품';
+    ustRtgSct: string | null;
+    jobCustCd: string | null;
+    jobCustNm: string;
+    pickYmdGrouping: number;
+    ustRtgSctCdGrouping: number;
+    ustRtgSctNmGrouping: number;
+    jobCustCdGrouping: number;
+    jobCustNmGrouping: number;
+}
+/**
+ * 대시보드 요약 통계
+ * [총 계] 행에서 추출한 핵심 지표
+ */
+interface DashboardSummary {
+    totalCount: number;
+    pending: number;
+    inTransit: number;
+    delivered: number;
+    problem: number;
+}
+/**
+ * 대시보드 API 응답
+ * 전체 데이터 + 요약 통계 포함
+ */
+interface DashboardStatsResponse {
+    items: DashboardStatsItem[];
+    summary: DashboardSummary;
+    dateRange: {
+        from: string;
+        to: string;
+    };
+    lastUpdated: string;
 }
 
+/** Individual bulk upload result item (SDK-safe: deliveryItem is raw JSON) */
+type BulkUploadResultItem = Omit<BulkUploadResultItem$1, 'deliveryItem'> & {
+    /** Courier delivery data (raw JSON object, only present when tracking number is updated) */
+    deliveryItem?: Record<string, unknown>;
+};
+/** Bulk upload response */
+type BulkUploadResponse = Omit<BulkUploadResponse$1, 'results'> & {
+    /** Individual item results (same order as request items) */
+    results: BulkUploadResultItem[];
+};
+
 /**
  * API 호출 실패 시 throw 되는 에러 클래스
  *
@@ -560,7 +901,14 @@ declare class ApiError extends Error {
     readonly code: ApiErrorCode | string;
     /** HTTP 상태 코드 */
     readonly status: number;
-    constructor(code: ApiErrorCode | string, message: string, status: number);
+    /**
+     * 에러 상세 데이터 (에러 종류에 따라 포함될 수 있음)
+     *
+     * 예) `INVALID_ITEMS` 에러 시 잘못된 항목 목록:
+     * `[{ courierCode, trackingNumber, errorCode }]`
+     */
+    readonly data?: unknown;
+    constructor(code: ApiErrorCode | string, message: string, status: number, data?: unknown);
 }
 /** API Key 인증 정보 */
 interface AuthCredentials {
@@ -580,7 +928,7 @@ declare class TrackingResource {
      * const { couriers } = await client.tracking.getCouriers()
      * // couriers: [{ trackingApiCode: 'cj', displayName: 'CJ대한통운' }, ...]
      */
-    getCouriers(): Promise<GetCouriersResponse>;
+    getCouriers(): Promise<GetCouriersApiResponse>;
     /**
      * 송장번호로 배송 정보를 조회합니다.
      *
@@ -615,7 +963,7 @@ declare class TrackingResource {
             clientId?: string;
         }[];
         includeProgresses?: boolean;
-    }): Promise<TraceResponse>;
+    }): Promise<TrackingResponse>;
 }
 
 declare class EndpointsResource {
@@ -646,7 +994,7 @@ declare class EndpointsResource {
         name: string;
         /** 서명 시크릿 직접 지정 (미제공 시 서버 자동 생성, 최소 5자) */
         webhookSecret?: string;
-    }): Promise<CreateEndpointResponse>;
+    }): Promise<CreateEndpointApiResponse>;
     /**
      * 등록된 웹훅 엔드포인트 목록을 조회합니다.
      *
@@ -655,7 +1003,7 @@ declare class EndpointsResource {
      * const active = endpoints.filter(ep => ep.status === 'active')
      * console.log(active[0].endpointId) // 'ep_xxxx'
      */
-    list(): Promise<ListEndpointsResponse>;
+    list(): Promise<ListEndpointsApiResponse>;
     /**
      * 웹훅 엔드포인트 이름을 수정합니다.
      *
@@ -696,7 +1044,7 @@ declare class EndpointsResource {
     rotateSecret(endpointId: string, params?: {
         /** 새 시크릿 직접 지정 (미제공 시 서버 자동 생성) */
         webhookSecret?: string;
-    }): Promise<RotateSecretResponse>;
+    }): Promise<RotateSecretApiResponse>;
 }
 
 declare class SubscriptionsResource {
@@ -791,7 +1139,7 @@ declare class SubscriptionsResource {
          * 웹훅 페이로드의 `metadata` 필드에 그대로 포함되어 반환됩니다.
          */
         metadata?: Record<string, string>;
-    }): Promise<RegisterResponse>;
+    }): Promise<RegisterTrackingApiResponse>;
     /**
      * 구독 목록을 조회합니다.
      *
@@ -808,7 +1156,7 @@ declare class SubscriptionsResource {
      *   cursor = page.nextCursor
      * } while (cursor)
      */
-    list(params?: ListSubscriptionsParams): Promise<ListSubscriptionsResponse>;
+    list(params?: ListSubscriptionsRequest): Promise<ListSubscriptionsApiResponse>;
     /**
      * 구독 상세 정보를 조회합니다.
      *
@@ -820,7 +1168,7 @@ declare class SubscriptionsResource {
      *   console.log(item.trackingNumber, item.currentStatus)
      * }
      */
-    get(requestId: string): Promise<SubscriptionDetail>;
+    get(requestId: string): Promise<SubscriptionDetailApiResponse>;
     /**
      * 구독을 취소합니다.
      *
@@ -851,7 +1199,7 @@ declare class SubscriptionsResource {
             courierCode: string;
             trackingNumber: string;
         }[];
-    }): Promise<BatchResultsResponse>;
+    }): Promise<BatchResultsApiResponse>;
 }
 
 /**
@@ -904,6 +1252,299 @@ declare class WebhooksResource {
     constructor(auth: AuthCredentials);
 }
 
+declare class AccountsResource {
+    private readonly auth;
+    constructor(auth: AuthCredentials);
+    /**
+     * 택배사 계정을 등록합니다.
+     *
+     * 롯데택배, 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 호출에 사용
+     */
+    register(params: RegisterAccountParams): Promise<RegisterAccountResponse>;
+    /**
+     * 등록된 택배사 계정 목록을 조회합니다.
+     *
+     * @returns 계정 목록 (courierAccountKey, providerId, isActive 등)
+     *
+     * @example
+     * const accounts = await client.courier.accounts.list()
+     * const active = accounts.filter(a => a.isActive)
+     * console.log(active[0].courierAccountKey)
+     */
+    list(): Promise<CourierAccountInfo[]>;
+    /**
+     * 특정 택배사 계정의 상세 정보를 조회합니다.
+     *
+     * 목록 조회와 달리 `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) // '(암호화하여 저장중)'
+     */
+    get(accountKey: string): Promise<CourierAccountDetail>;
+    /**
+     * 택배사 계정을 삭제합니다.
+     *
+     * @param accountKey - 삭제할 계정의 courierAccountKey
+     * @throws {ApiError} NOT_FOUND — 존재하지 않는 계정
+     *
+     * @example
+     * await client.courier.accounts.delete('your-account-key')
+     */
+    delete(accountKey: string): Promise<void>;
+}
+
+declare class HistoriesResource {
+    private readonly auth;
+    constructor(auth: AuthCredentials);
+    /**
+     * 대량 등록 이력 목록을 조회합니다.
+     *
+     * @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')
+     */
+    list(params: ListHistoriesParams): Promise<ListHistoriesResponse>;
+    /**
+     * 대량 등록 이력의 상세 정보를 조회합니다.
+     *
+     * 택배사 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)
+     */
+    get(historyId: string, params: HistoryDetailParams): Promise<HistoryDetailResponse>;
+    /**
+     * 대량 등록 이력을 삭제(취소)합니다.
+     *
+     * `courierDeliveryIds`를 지정하면 부분 취소, 생략하면 전체 취소(soft delete)입니다.
+     * 택배사 API를 호출하여 실제 접수도 취소합니다.
+     *
+     * @param historyId - 이력 ID
+     * @param params - 삭제 파라미터 (courierAccountKey 필수)
+     * @throws {ApiError} NOT_FOUND — 존재하지 않는 이력 또는 계정
+     *
+     * @example
+     * // 전체 취소
+     * await client.courier.deliveries.histories.delete('202603221456_a1b2c', {
+     *   courierAccountKey: 'your-key',
+     * })
+     *
+     * // 부분 취소
+     * await client.courier.deliveries.histories.delete('202603221456_a1b2c', {
+     *   courierAccountKey: 'your-key',
+     *   courierDeliveryIds: ['7705241632'],
+     * })
+     */
+    delete(historyId: string, params: DeleteHistoryParams): Promise<void>;
+}
+
+declare class DeliveriesResource {
+    private readonly auth;
+    /** 대량 등록 이력 관리 */
+    readonly histories: HistoriesResource;
+    constructor(auth: AuthCredentials);
+    /**
+     * 택배를 대량 등록합니다. 최대 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)
+     */
+    bulkUpload(params: BulkUploadParams): Promise<BulkUploadResponse>;
+    /**
+     * 택배사 계정의 배송 목록을 조회합니다.
+     *
+     * 택배사 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')
+     */
+    inquiry(params: InquiryParams): Promise<AccountInquiryResponse>;
+    /**
+     * 택배사 계정의 배송 통계(대시보드)를 조회합니다.
+     *
+     * @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)   // 배송 완료 건수
+     */
+    dashboard(params: DashboardParams): Promise<DashboardStatsResponse>;
+    /**
+     * 등록된 배송을 취소합니다.
+     *
+     * **주의**: 등록 후 7일 이내의 배송만 취소 가능합니다.
+     * 7일 이상 경과한 배송은 택배사에서 조회되지 않아 취소할 수 없습니다.
+     * 지원하지 않는 택배사의 경우 에러가 반환됩니다.
+     *
+     * 이력 단위 취소가 필요하면 `client.courier.deliveries.histories.delete()`를 사용하세요.
+     *
+     * @param params - 취소 파라미터 (courierDeliveryId 목록)
+     * @throws {ApiError} NOT_FOUND — 존재하지 않는 계정
+     * @throws {ApiError} INVALID_PARAMS — 택배사가 배송 취소를 지원하지 않음
+     *
+     * @example
+     * await client.courier.deliveries.cancel({
+     *   courierAccountKey: 'your-key',
+     *   courierDeliveryIds: ['7705241632', '7705241633'],
+     * })
+     */
+    cancel(params: CancelDeliveriesParams): Promise<void>;
+}
+
+declare class PrintResource {
+    private readonly auth;
+    constructor(auth: AuthCredentials);
+    /**
+     * 송장 출력 세션을 생성합니다.
+     *
+     * 세션 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',
+     * })
+     */
+    createSession(params: CreatePrintSessionParams): Promise<PrintSessionResponse>;
+}
+
+/**
+ * 택배 계정 서비스 리소스
+ *
+ * 택배사 계정을 등록하고, 택배를 대량 등록·조회·취소하며, 송장을 출력합니다.
+ * 현재 롯데택배, CJ대한통운을 지원합니다.
+ *
+ * @example
+ * // 전체 플로우: 계정 등록 → 대량 등록 → 송장 출력 → 배송 추적
+ * const account = await client.courier.accounts.register({
+ *   providerId: 'lotte',
+ *   accountId: 'my-id',
+ *   accountPassword: 'my-password',
+ * })
+ *
+ * const upload = await client.courier.deliveries.bulkUpload({
+ *   courierAccountKey: account.courierAccountKey,
+ *   items: [{ clientOrderId: 'ORD-001', receiverName: '홍길동', ... }],
+ * })
+ *
+ * const session = await client.courier.print.createSession({
+ *   courierAccountKey: account.courierAccountKey,
+ *   providerId: 'lotte',
+ *   courierTrackingIds: upload.results.filter(r => r.success).map(r => r.courierDeliveryId!),
+ * })
+ * // 출력 후 trackingNumber가 발급됨 → inquiry로 확인 → webhooks로 추적
+ */
+declare class CourierResource {
+    /** 택배사 계정 관리 (등록, 조회, 삭제) */
+    readonly accounts: AccountsResource;
+    /** 배송 관리 (대량 등록, 조회, 대시보드, 취소, 이력) */
+    readonly deliveries: DeliveriesResource;
+    /** 송장 출력 (세션 생성) */
+    readonly print: PrintResource;
+    constructor(auth: AuthCredentials);
+}
+
 /** `DeliveryAPIClient` 생성 옵션 */
 interface DeliveryAPIClientOptions {
     /**
@@ -965,9 +1606,20 @@ declare class DeliveryAPIClient {
      * **`webhooks.subscriptions`** — 택배 추적 구독 등록/관리
      */
     readonly webhooks: WebhooksResource;
+    /**
+     * 택배 계정 서비스 API
+     *
+     * 택배사 계정 등록, 택배 대량 등록·조회·취소, 송장 출력을 제공합니다.
+     * 현재 롯데택배, CJ대한통운을 지원합니다.
+     *
+     * **`courier.accounts`** — 택배사 계정 관리
+     * **`courier.deliveries`** — 대량 등록, 배송 조회/취소, 이력
+     * **`courier.print`** — 송장 출력 세션 생성
+     */
+    readonly courier: CourierResource;
     /** API Base URL (`https://api.deliveryapi.co.kr`) */
     readonly baseUrl: string;
     constructor(options: DeliveryAPIClientOptions);
 }
 
-export { ApiError, type ApiErrorCode, type BatchResultEntry, type BatchResultItem, type BatchResultsParams, type BatchResultsResponse, CourierDeliveryStatus, type CourierInfo, type CreateEndpointParams, type CreateEndpointResponse, DeliveryAPIClient, type DeliveryAPIClientOptions, type EndpointInfo, type GetCouriersResponse, type ListEndpointsResponse, type ListSubscriptionsParams, type ListSubscriptionsResponse, type RegisterItem, type RegisterResponse, type RotateSecretParams, type RotateSecretResponse, type SubscriptionDetail, type SubscriptionItem, type SubscriptionListItem, type SubscriptionSummary, type TraceCacheInfo, type TraceItem, type TraceItemError, type TraceParams, type TraceResponse, type TraceResult, type TrackingErrorCode, type TrackingProgress, type UnifiedTrackingResponse, type UpdateEndpointParams, type WebhookPayload };
+export { type AccountInquiryItem, type AccountInquiryResponse, AccountsResource, ApiError, type ApiErrorCode, type BatchResultEntry, type BatchResultItem, type BatchResultsRequest as BatchResultsParams, type BatchResultsApiResponse as BatchResultsResponse, type BulkUploadHistoryInfo, type BulkUploadHistoryItemInfo, type BulkUploadItemParams, type BulkUploadParams, type BulkUploadResponse, type BulkUploadResultItem, type BulkUploadStatus, type CancelDeliveriesParams, type CourierAccountDetail, type CourierAccountInfo, CourierDeliveryStatus, type CourierInfoResponse as CourierInfo, CourierResource, type CreateEndpointRequest as CreateEndpointParams, type CreateEndpointApiResponse as CreateEndpointResponse, type CreatePrintSessionParams, type DashboardParams, type DashboardStatsItem, type DashboardStatsResponse, type DashboardSummary, type DeleteHistoryParams, DeliveriesResource, DeliveryAPIClient, type DeliveryAPIClientOptions, type DeliveryStatusFilter, type EndpointListItem as EndpointInfo, type GetCouriersApiResponse as GetCouriersResponse, HistoriesResource, type HistoryDetailParams, type HistoryDetailResponse, type InquiryParams, type ListEndpointsApiResponse as ListEndpointsResponse, type ListHistoriesParams, type ListHistoriesResponse, type ListSubscriptionsRequest as ListSubscriptionsParams, type ListSubscriptionsApiResponse as ListSubscriptionsResponse, PrintResource, type PrintSessionResponse, type RegisterAccountParams, type RegisterAccountResponse, type RegisterTrackingItem as RegisterItem, type RegisterTrackingApiResponse as RegisterResponse, type RotateSecretRequest as RotateSecretParams, type RotateSecretApiResponse as RotateSecretResponse, type SubscriptionDetailApiResponse as SubscriptionDetail, type WebhookTrackingItem as SubscriptionItem, type SubscriptionListItem, type TrackingBatchSummary as SubscriptionSummary, type TrackingCacheInfo as TraceCacheInfo, type TrackingItem as TraceItem, type TrackingItemError as TraceItemError, type TrackingRequest as TraceParams, type TrackingResponse as TraceResponse, type TrackingResult as TraceResult, type TrackingErrorCode, type TrackingProgress, type UnifiedTrackingResponse, type UpdateEndpointRequest as UpdateEndpointParams, type WebhookPayload, type WebhookTrackingItem };