Metadata-Version: 2.4
Name: deliveryapi
Version: 1.0.0
Summary: Official Python SDK for the DeliveryAPI courier tracking platform
Project-URL: Homepage, https://deliveryapi.co.kr
Project-URL: Documentation, https://docs.deliveryapi.co.kr
Author-email: DeliveryAPI <support@deliveryapi.co.kr>
License: MIT
Keywords: courier,delivery,korea,sdk,tracking,webhook
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# deliveryapi — Python SDK

Official Python SDK for the [DeliveryAPI](https://deliveryapi.co.kr) courier tracking and webhook platform.

## Installation

```bash
pip install deliveryapi
```

## Quick Start

```python
from deliveryapi import DeliverySaasClient

client = DeliverySaasClient(
    api_key="pk_live_...",
    secret_key="sk_live_...",
)

# Query a single tracking number
result = client.tracking.get_one("LOTTE", "1234567890")
item = result["results"][0]
if item["success"]:
    print(item["data"]["deliveryStatus"])  # e.g. "IN_TRANSIT"

# Batch query
result = client.tracking.get([
    {"courierCode": "LOTTE", "trackingNumber": "1234567890"},
    {"courierCode": "cj",    "trackingNumber": "9876543210"},
])
print(result["summary"])
```

## Async Support

```python
import asyncio
from deliveryapi import AsyncDeliverySaasClient

async def main():
    async with AsyncDeliverySaasClient(
        api_key="pk_live_...",
        secret_key="sk_live_...",
    ) as client:
        result = await client.tracking.get_one("LOTTE", "1234567890")
        print(result)

asyncio.run(main())
```

## Webhook Signature Verification

```python
from deliveryapi import verify_webhook_signature, WebhookSignatureError

# Flask example
@app.route("/webhook", methods=["POST"])
def handle_webhook():
    try:
        verify_webhook_signature(
            payload=request.get_data(as_text=True),
            signature=request.headers["X-Webhook-Signature"],
            timestamp=request.headers["X-Webhook-Timestamp"],
            secret="whsec_...",
        )
    except WebhookSignatureError:
        return "Invalid signature", 400

    event = request.json
    print(event["data"]["currentStatus"])
    return "", 200
```

## Error Handling

```python
from deliveryapi import (
    DeliverySaasClient,
    DeliverySaasError,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

client = DeliverySaasClient(api_key="pk_...", secret_key="sk_...")

try:
    result = client.tracking.get_one("LOTTE", "1234567890")
except AuthenticationError:
    print("Invalid API credentials")
except RateLimitError:
    print("Rate limit exceeded — slow down requests")
except NotFoundError:
    print("Resource not found")
except DeliverySaasError as e:
    print(f"API error {e.status_code}: {e}")
```

## Webhook Management

```python
# Register an endpoint
endpoint = client.webhooks.create({
    "url": "https://my-server.com/webhook",
    "name": "Production server",
})
print(endpoint["id"])  # e.g. "ep_..."

# Create a subscription
sub = client.subscriptions.create({
    "courierCode": "LOTTE",
    "trackingNumber": "1234567890",
    "endpointId": endpoint["id"],
})
print(sub["id"])  # e.g. "sub_..."

# List and cancel
subs = client.subscriptions.list(status="active")
client.subscriptions.cancel(sub["id"])
```

## Supported Couriers

```python
couriers = client.couriers.list()
for c in couriers["couriers"]:
    print(c["id"], c["displayName"])
```

## License

MIT
