deliveryapi 0.1.0

package/README.md

@@ -0,0 +1,252 @@
+# deliveryapi
+
+Official JavaScript/TypeScript SDK for the [DeliveryAPI](https://deliveryapi.co.kr) — Korea's unified courier tracking API.
+
+## Installation
+
+```bash
+npm install deliveryapi
+# or
+yarn add deliveryapi
+# or
+pnpm add deliveryapi
+```
+
+## Quick Start
+
+```typescript
+import { DeliverySaasClient } from 'deliveryapi'
+
+const client = new DeliverySaasClient({
+  apiKey: 'your-api-key',
+  secretKey: 'your-secret-key',
+})
+```
+
+API keys can be issued at [deliveryapi.co.kr](https://deliveryapi.co.kr).
+
+---
+
+## Tracking
+
+### Single tracking
+
+```typescript
+const result = await client.tracking.getOne('LOTTE', '1234567890')
+
+console.log(result.results[0].status)     // 'DELIVERED'
+console.log(result.results[0].progresses) // delivery history
+```
+
+### Multiple tracking at once
+
+```typescript
+const result = await client.tracking.get([
+  { courierCode: 'LOTTE', trackingNumber: '1234567890' },
+  { courierCode: 'CJ', trackingNumber: '9876543210' },
+])
+
+for (const item of result.results) {
+  console.log(item.trackingNumber, item.status)
+}
+```
+
+### Without delivery history (faster)
+
+```typescript
+const result = await client.tracking.getOne('CJ', '1234567890', {
+  includeProgresses: false,
+})
+```
+
+---
+
+## Webhook Endpoints
+
+Register a URL to receive real-time delivery status change notifications.
+
+### Register endpoint
+
+```typescript
+const endpoint = await client.webhooks.create({
+  url: 'https://your-server.com/webhook',
+  name: 'Production Webhook',
+})
+
+console.log(endpoint.id) // 'ep_xxxxxxxxxxxx'
+```
+
+### List endpoints
+
+```typescript
+const { endpoints } = await client.webhooks.list()
+```
+
+### Test endpoint
+
+```typescript
+const result = await client.webhooks.test('ep_xxxxxxxxxxxx')
+console.log(result.success) // true
+```
+
+### Delete endpoint
+
+```typescript
+await client.webhooks.delete('ep_xxxxxxxxxxxx')
+```
+
+---
+
+## Tracking Subscriptions
+
+Subscribe to a tracking number and receive webhook notifications when status changes.
+
+### Create subscription
+
+```typescript
+const subscription = await client.subscriptions.create({
+  courierCode: 'LOTTE',
+  trackingNumber: '1234567890',
+  endpointId: 'ep_xxxxxxxxxxxx',
+})
+
+console.log(subscription.id) // 'sub_xxxxxxxxxxxx'
+```
+
+### Subscribe to specific statuses only
+
+```typescript
+const subscription = await client.subscriptions.create({
+  courierCode: 'CJ',
+  trackingNumber: '9876543210',
+  endpointId: 'ep_xxxxxxxxxxxx',
+  subscribedStatuses: ['IN_TRANSIT', 'DELIVERED'],
+})
+```
+
+### List subscriptions
+
+```typescript
+const { subscriptions, total } = await client.subscriptions.list({
+  status: 'ACTIVE',
+  page: 1,
+  pageSize: 20,
+})
+```
+
+### Retrieve subscription
+
+```typescript
+const subscription = await client.subscriptions.retrieve('sub_xxxxxxxxxxxx')
+console.log(subscription.status) // 'ACTIVE'
+```
+
+### Cancel subscription
+
+```typescript
+await client.subscriptions.cancel('sub_xxxxxxxxxxxx')
+```
+
+---
+
+## Couriers
+
+### List supported couriers
+
+```typescript
+const { couriers } = await client.couriers.list()
+
+for (const courier of couriers) {
+  console.log(courier.code, courier.name) // 'LOTTE', '롯데택배'
+}
+```
+
+---
+
+## Webhook Payload
+
+When a tracking status changes, your endpoint receives a POST request with the following payload:
+
+```typescript
+import type { WebhookPayload } from 'deliveryapi'
+
+app.post('/webhook', (req, res) => {
+  const payload: WebhookPayload = req.body
+
+  console.log(payload.subscriptionId)
+  console.log(payload.courierCode)
+  console.log(payload.trackingNumber)
+  console.log(payload.status)       // 'DELIVERED'
+  console.log(payload.changedAt)    // ISO 8601 timestamp
+
+  res.sendStatus(200)
+})
+```
+
+---
+
+## Error Handling
+
+```typescript
+import {
+  DeliverySaasClient,
+  AuthenticationError,
+  RateLimitError,
+  NotFoundError,
+  DeliverySaasError,
+} from 'deliveryapi'
+
+try {
+  const result = await client.tracking.getOne('LOTTE', '1234567890')
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // Invalid API key or secret key
+    console.error('Authentication failed')
+  } else if (error instanceof RateLimitError) {
+    // Request limit exceeded
+    console.error('Rate limit exceeded, retry later')
+  } else if (error instanceof NotFoundError) {
+    // Resource not found
+    console.error('Not found')
+  } else if (error instanceof DeliverySaasError) {
+    // Other API errors
+    console.error(error.message, error.statusCode)
+  }
+}
+```
+
+---
+
+## TypeScript
+
+Full TypeScript support is included out of the box.
+
+```typescript
+import type {
+  TrackingResponse,
+  TrackingSubscription,
+  WebhookEndpoint,
+  WebhookPayload,
+  CourierDeliveryStatus,
+} from 'deliveryapi'
+```
+
+---
+
+## Supported Couriers
+
+| Code | Name |
+|------|------|
+| `LOTTE` | 롯데택배 |
+| `CJ` | CJ대한통운 |
+| `HANJIN` | 한진택배 |
+| `POST` | 우체국택배 |
+| `LOGEN` | 로젠택배 |
+
+Full list available via `client.couriers.list()`.
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,210 @@
+'use strict';
+
+// src/errors.ts
+var DeliverySaasError = class extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.name = "DeliverySaasError";
+  }
+};
+var AuthenticationError = class extends DeliverySaasError {
+  constructor(message = "Invalid API key or secret key") {
+    super(message, 401, "AUTHENTICATION_ERROR");
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends DeliverySaasError {
+  constructor(message = "Rate limit exceeded") {
+    super(message, 429, "RATE_LIMIT_ERROR");
+    this.name = "RateLimitError";
+  }
+};
+var NotFoundError = class extends DeliverySaasError {
+  constructor(message = "Resource not found") {
+    super(message, 404, "NOT_FOUND");
+    this.name = "NotFoundError";
+  }
+};
+
+// src/http.ts
+var HttpClient = class {
+  constructor(apiKey, secretKey, baseUrl) {
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.authHeader = `Bearer ${apiKey}:${secretKey}`;
+  }
+  async get(path, params) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => url.searchParams.set(key, value));
+    }
+    return this.request("GET", url.toString());
+  }
+  async post(path, body) {
+    return this.request("POST", `${this.baseUrl}${path}`, body);
+  }
+  async patch(path, body) {
+    return this.request("PATCH", `${this.baseUrl}${path}`, body);
+  }
+  async delete(path) {
+    return this.request("DELETE", `${this.baseUrl}${path}`);
+  }
+  async request(method, url, body) {
+    const headers = {
+      Authorization: this.authHeader,
+      "Content-Type": "application/json"
+    };
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    const json = await response.json();
+    if (!response.ok) {
+      if (response.status === 401) throw new AuthenticationError(json.message);
+      if (response.status === 404) throw new NotFoundError(json.message);
+      if (response.status === 429) throw new RateLimitError(json.message);
+      throw new DeliverySaasError(json.message ?? "Request failed", response.status, json.error);
+    }
+    if (!json.isSuccess) {
+      throw new DeliverySaasError(json.message ?? "API returned failure", response.status, json.error);
+    }
+    return json.data;
+  }
+};
+
+// src/resources/tracking.ts
+var TrackingResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 택배 조회 (공개 API, 계정 불필요)
+   * @param items 조회할 택배 목록 (1건도 배열로)
+   * @param includeProgresses 진행 내역 포함 여부 (기본값: true)
+   */
+  async get(items, includeProgresses = true) {
+    return this.http.post("/v1/courier/track", {
+      items,
+      includeProgresses
+    });
+  }
+  /**
+   * 단건 택배 조회 (편의 메서드)
+   */
+  async getOne(courierCode, trackingNumber, options) {
+    return this.get(
+      [{ courierCode, trackingNumber, clientId: options?.clientId }],
+      options?.includeProgresses ?? true
+    );
+  }
+};
+
+// src/resources/subscriptions.ts
+var SubscriptionsResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 택배 구독 생성
+   * 상태 변경 시 등록된 웹훅 엔드포인트로 알림 전송
+   */
+  async create(data) {
+    return this.http.post("/v1/tracking/subscriptions", data);
+  }
+  /**
+   * 택배 구독 목록 조회
+   */
+  async list(options) {
+    const params = {};
+    if (options?.status) params["status"] = options.status;
+    if (options?.page) params["page"] = String(options.page);
+    if (options?.pageSize) params["pageSize"] = String(options.pageSize);
+    return this.http.get("/v1/tracking/subscriptions", params);
+  }
+  /**
+   * 택배 구독 상세 조회
+   */
+  async retrieve(subscriptionId) {
+    return this.http.get(`/v1/tracking/subscriptions/${subscriptionId}`);
+  }
+  /**
+   * 택배 구독 취소
+   */
+  async cancel(subscriptionId) {
+    await this.http.delete(`/v1/tracking/subscriptions/${subscriptionId}`);
+  }
+};
+
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 웹훅 엔드포인트 등록
+   */
+  async create(data) {
+    return this.http.post("/v1/webhook-v2/endpoints", data);
+  }
+  /**
+   * 웹훅 엔드포인트 목록 조회
+   */
+  async list() {
+    return this.http.get("/v1/webhook-v2/endpoints");
+  }
+  /**
+   * 웹훅 엔드포인트 상세 조회
+   */
+  async retrieve(endpointId) {
+    return this.http.get(`/v1/webhook-v2/endpoints/${endpointId}`);
+  }
+  /**
+   * 웹훅 엔드포인트 삭제
+   */
+  async delete(endpointId) {
+    await this.http.delete(`/v1/webhook-v2/endpoints/${endpointId}`);
+  }
+  /**
+   * 웹훅 엔드포인트 테스트 전송
+   */
+  async test(endpointId) {
+    return this.http.post(`/v1/webhook-v2/endpoints/${endpointId}/test`);
+  }
+};
+
+// src/resources/couriers.ts
+var CouriersResource = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * 지원 택배사 목록 조회
+   */
+  async list() {
+    return this.http.get("/v1/courier/list");
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.deliveryapi.co.kr";
+var DeliverySaasClient = class {
+  constructor(config) {
+    const http = new HttpClient(
+      config.apiKey,
+      config.secretKey,
+      config.baseUrl ?? DEFAULT_BASE_URL
+    );
+    this.tracking = new TrackingResource(http);
+    this.subscriptions = new SubscriptionsResource(http);
+    this.webhooks = new WebhooksResource(http);
+    this.couriers = new CouriersResource(http);
+  }
+};
+
+exports.AuthenticationError = AuthenticationError;
+exports.DeliverySaasClient = DeliverySaasClient;
+exports.DeliverySaasError = DeliverySaasError;
+exports.NotFoundError = NotFoundError;
+exports.RateLimitError = RateLimitError;