deliveryapi 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,417 @@
+// Generated by dts-bundle-generator v9.5.1
+
+declare class HttpClient {
+	private readonly baseUrl;
+	private readonly authHeader;
+	constructor(apiKey: string, secretKey: string, baseUrl: string);
+	get<T>(path: string, params?: Record<string, string>): Promise<T>;
+	post<T>(path: string, body?: unknown): Promise<T>;
+	patch<T>(path: string, body?: unknown): Promise<T>;
+	delete<T>(path: string): Promise<T>;
+	private request;
+}
+/**
+ * Firebase Timestamp 호환 인터페이스
+ * firebase-admin/firestore 및 firebase/firestore의 Timestamp와 구조적으로 호환됨
+ */
+export interface Timestamp {
+	seconds: number;
+	nanoseconds: number;
+	toDate(): Date;
+	toMillis(): number;
+	isEqual(other: Timestamp): boolean;
+	valueOf(): string;
+}
+/**
+ * 통일된 API 응답 형식
+ */
+export interface ApiResponse<T = unknown> {
+	isSuccess: boolean;
+	statusCode?: number;
+	data?: T;
+	error?: string;
+	message?: string;
+}
+/**
+ * 택배 배송 상태 열거형
+ * 모든 택배사의 상태를 통합하여 정규화
+ *
+ * 📌 프로젝트별 차이점:
+ * - delivery-saas-api-functions (이 프로젝트): enum만 정의 (데이터 반환용)
+ * - farmsns-admin_new, farmsns-functions_new, farmfree-mobile:
+ *   → CourierDeliveryStatusLabels (한글 라벨)
+ *   → LotteStatusMapping, CJStatusMapping (택배사별 매핑)
+ *   → Helper 함수들 (mapCourierStatus, isDeliveryInProgress 등)
+ *
+ * 이유: delivery-saas-api는 외부 API 역할로 데이터 반환만 수행하므로
+ *       UI 표시용 라벨이나 변환 로직이 불필요
+ */
+export 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",// 보류
+	UNKNOWN = "UNKNOWN"
+}
+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";
+};
+export type CourierCode = (typeof COURIER_CODES)[keyof typeof COURIER_CODES];
+/**
+ * 인증 방식 타입
+ */
+export type AuthMethod = "2FA_SMS" | "2FA_EMAIL" | "2FA_KAKAO" | "2FA_OTP";
+/**
+ * 인증 코드 타입
+ */
+export type AuthCodeType = "NUMERIC" | "ALPHANUMERIC";
+/**
+ * 택배사 정보 인터페이스
+ */
+export interface CourierInfo {
+	id: CourierCode;
+	trackingApiCode: CourierCode;
+	displayName: string;
+	icon: string;
+	supportsTracking: boolean;
+	supportsAccount: boolean;
+	adminUrl: string;
+	trackingUrl: string;
+	customerServicePhone: string;
+	requires2FA: boolean;
+	authMethod?: AuthMethod | null;
+	authCodeLength?: number | null;
+	authCodeType?: AuthCodeType | null;
+	supportsAutoReauth: boolean;
+	allowsMultipleSessions: boolean;
+	reauthMessage: string;
+	accessTokenDurationMinutes: number;
+	maxInquiryDays: number;
+}
+/**
+ * 개별 택배 조회 항목
+ */
+export interface TrackingItem {
+	id?: string;
+	clientId?: string;
+	courierCode: string;
+	trackingNumber: string;
+}
+/**
+ * 택배 진행 상황
+ */
+export interface TrackingProgress {
+	dateTime: string;
+	location: string;
+	status: string;
+	statusCode?: CourierDeliveryStatus;
+	description?: string;
+	telno?: string;
+	telno2?: string;
+}
+/**
+ * 통합 택배 조회 응답
+ */
+export interface UnifiedTrackingResponse {
+	trackingNumber: string;
+	courierCode: string;
+	courierName: string;
+	deliveryStatus: CourierDeliveryStatus;
+	deliveryStatusText: string;
+	isDelivered: boolean;
+	senderName?: string;
+	receiverName?: string;
+	receiverAddress?: string;
+	productName?: string;
+	productQuantity?: number;
+	dateDelivered?: string;
+	dateEstimated?: string;
+	dateLastProgress: string;
+	progresses: TrackingProgress[];
+	queriedAt: string;
+}
+/**
+ * 택배 조회 에러 코드
+ *
+ * 과금 정책:
+ * - NOT_FOUND만 과금 (택배사 API를 호출했으나 데이터 없음 = 사용자 책임)
+ * - 나머지는 비과금 (요청 검증 실패 또는 시스템 오류)
+ */
+export type TrackingErrorCode = "MISSING_PARAMS" | "INVALID_TRACKING_NUMBER" | "UNSUPPORTED_COURIER" | "NOT_FOUND" | "TRACKING_FAILED";
+/**
+ * 택배 조회 오류
+ */
+export interface TrackingError {
+	code: TrackingErrorCode;
+	message: string;
+	courierCode?: string;
+	trackingNumber?: string;
+	details?: unknown;
+	billable: boolean;
+}
+/**
+ * 캐시 메타데이터
+ */
+export interface TrackingCacheInfo {
+	fromCache: boolean;
+	cachedAt?: string;
+}
+/**
+ * 개별 택배 조회 결과
+ */
+export interface TrackingResult {
+	id?: string;
+	clientId?: string;
+	success: boolean;
+	data?: UnifiedTrackingResponse;
+	error?: TrackingError;
+	cache?: TrackingCacheInfo;
+}
+/**
+ * 택배 조회 응답 (배열로 다건 응답)
+ */
+export interface TrackingResponse {
+	results: TrackingResult[];
+	summary: {
+		total: number;
+		successful: number;
+		failed: number;
+		billable: number;
+	};
+}
+/**
+ * 웹훅 엔드포인트 (apiKeys 문서에 저장)
+ * API Key당 최대 10개 등록 가능
+ */
+export interface WebhookEndpoint {
+	id: string;
+	url: string;
+	name?: string;
+	webhookSecret: string;
+	webhookSecretHash: string;
+	status: "active" | "inactive";
+	dateCreated: Timestamp;
+	dateModified: Timestamp;
+}
+/**
+ * 구독 상태
+ */
+export type SubscriptionStatus = "active" | "completed" | "cancelled" | "failed";
+/**
+ * 택배 조회 구독 (trackingSubscriptions 컬렉션)
+ */
+export interface TrackingSubscription {
+	id: string;
+	clientId?: string;
+	customerId: string;
+	apiKeyHash: string;
+	courierCode: string;
+	trackingNumber: string;
+	endpointId: string;
+	subscribedStatuses: CourierDeliveryStatus[];
+	currentStatus: CourierDeliveryStatus;
+	lastPolledAt: Timestamp;
+	nextPollAt: Timestamp;
+	status: SubscriptionStatus;
+	failureCount: number;
+	metadata?: Record<string, string>;
+	dateCreated: Timestamp;
+	dateModified: Timestamp;
+}
+/**
+ * 웹훅 페이로드
+ */
+export interface WebhookPayload {
+	event: "tracking.status_changed";
+	subscriptionId: string;
+	timestamp: string;
+	data: {
+		courierCode: string;
+		trackingNumber: string;
+		previousStatus?: CourierDeliveryStatus;
+		currentStatus: CourierDeliveryStatus;
+		tracking: UnifiedTrackingResponse;
+	};
+	metadata?: Record<string, string>;
+}
+export interface DeliverySaasClientConfig {
+	/** API Key (발급받은 API Key) */
+	apiKey: string;
+	/** Secret Key (발급받은 Secret Key) */
+	secretKey: string;
+	/** API Base URL (기본값: https://api.deliveryapi.co.kr) */
+	baseUrl?: string;
+}
+export interface TrackingRequestInput {
+	items: TrackingItem[];
+	includeProgresses?: boolean;
+}
+export interface SubscriptionCreateInput {
+	courierCode: string;
+	trackingNumber: string;
+	endpointId: string;
+	subscribedStatuses?: CourierDeliveryStatus[];
+	clientId?: string;
+	metadata?: Record<string, string>;
+}
+export interface SubscriptionListResult {
+	subscriptions: TrackingSubscription[];
+	total: number;
+}
+export interface WebhookCreateInput {
+	url: string;
+	name?: string;
+}
+export interface WebhookListResult {
+	endpoints: WebhookEndpoint[];
+	total: number;
+}
+export interface WebhookTestResult {
+	success: boolean;
+	statusCode?: number;
+	message?: string;
+}
+export interface CourierListResult {
+	couriers: CourierInfo[];
+}
+declare class TrackingResource {
+	private readonly http;
+	constructor(http: HttpClient);
+	/**
+	 * 택배 조회 (공개 API, 계정 불필요)
+	 * @param items 조회할 택배 목록 (1건도 배열로)
+	 * @param includeProgresses 진행 내역 포함 여부 (기본값: true)
+	 */
+	get(items: TrackingRequestInput["items"], includeProgresses?: boolean): Promise<TrackingResponse>;
+	/**
+	 * 단건 택배 조회 (편의 메서드)
+	 */
+	getOne(courierCode: string, trackingNumber: string, options?: {
+		clientId?: string;
+		includeProgresses?: boolean;
+	}): Promise<TrackingResponse>;
+}
+declare class SubscriptionsResource {
+	private readonly http;
+	constructor(http: HttpClient);
+	/**
+	 * 택배 구독 생성
+	 * 상태 변경 시 등록된 웹훅 엔드포인트로 알림 전송
+	 */
+	create(data: SubscriptionCreateInput): Promise<TrackingSubscription>;
+	/**
+	 * 택배 구독 목록 조회
+	 */
+	list(options?: {
+		status?: string;
+		page?: number;
+		pageSize?: number;
+	}): Promise<SubscriptionListResult>;
+	/**
+	 * 택배 구독 상세 조회
+	 */
+	retrieve(subscriptionId: string): Promise<TrackingSubscription>;
+	/**
+	 * 택배 구독 취소
+	 */
+	cancel(subscriptionId: string): Promise<void>;
+}
+declare class WebhooksResource {
+	private readonly http;
+	constructor(http: HttpClient);
+	/**
+	 * 웹훅 엔드포인트 등록
+	 */
+	create(data: WebhookCreateInput): Promise<WebhookEndpoint>;
+	/**
+	 * 웹훅 엔드포인트 목록 조회
+	 */
+	list(): Promise<WebhookListResult>;
+	/**
+	 * 웹훅 엔드포인트 상세 조회
+	 */
+	retrieve(endpointId: string): Promise<WebhookEndpoint>;
+	/**
+	 * 웹훅 엔드포인트 삭제
+	 */
+	delete(endpointId: string): Promise<void>;
+	/**
+	 * 웹훅 엔드포인트 테스트 전송
+	 */
+	test(endpointId: string): Promise<WebhookTestResult>;
+}
+declare class CouriersResource {
+	private readonly http;
+	constructor(http: HttpClient);
+	/**
+	 * 지원 택배사 목록 조회
+	 */
+	list(): Promise<CourierListResult>;
+}
+/**
+ * DeliverySaaS API Client
+ *
+ * @example
+ * ```typescript
+ * import { DeliverySaasClient } from 'deliveryapi'
+ *
+ * const client = new DeliverySaasClient({
+ *   apiKey: 'your-api-key',
+ *   secretKey: 'your-secret-key',
+ * })
+ *
+ * // 택배 조회
+ * const result = await client.tracking.getOne('LOTTE', '1234567890')
+ *
+ * // 구독 생성
+ * const subscription = await client.subscriptions.create({
+ *   courierCode: 'LOTTE',
+ *   trackingNumber: '1234567890',
+ *   endpointId: 'ep_xxx',
+ * })
+ * ```
+ */
+export declare class DeliverySaasClient {
+	readonly tracking: TrackingResource;
+	readonly subscriptions: SubscriptionsResource;
+	readonly webhooks: WebhooksResource;
+	readonly couriers: CouriersResource;
+	constructor(config: DeliverySaasClientConfig);
+}
+export declare class DeliverySaasError extends Error {
+	readonly statusCode: number;
+	readonly code?: string | undefined;
+	constructor(message: string, statusCode: number, code?: string | undefined);
+}
+export declare class AuthenticationError extends DeliverySaasError {
+	constructor(message?: string);
+}
+export declare class RateLimitError extends DeliverySaasError {
+	constructor(message?: string);
+}
+export declare class NotFoundError extends DeliverySaasError {
+	constructor(message?: string);
+}
+
+export {
+	TrackingItem as TrackingResponseItem,
+};
+
+export {};