deliveryapi 0.1.4 → 0.2.0

package/README.md

@@ -1,252 +0,0 @@
-# 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