deliveryapi 1.0.0__tar.gz

deliveryapi-1.0.0/.gitignore

@@ -0,0 +1,26 @@
+# Dependencies
+node_modules/
+
+# Build outputs
+dist/
+lib/
+.output/
+.nuxt/
+.astro/
+
+# Environment variables (민감정보)
+.env
+.env.*
+!.env.example
+
+# Firebase
+.firebase/
+**/serviceAccountKey*.json
+**/serviceAccount*.json
+
+# macOS
+.DS_Store
+
+# IDE
+.vscode/
+.idea/

deliveryapi-1.0.0/PKG-INFO

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

deliveryapi-1.0.0/README.md

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

deliveryapi-1.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "deliveryapi"
+version = "1.0.0"
+description = "Official Python SDK for the DeliveryAPI courier tracking platform"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["delivery", "courier", "tracking", "webhook", "korea", "sdk"]
+authors = [{ name = "DeliveryAPI", email = "support@deliveryapi.co.kr" }]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+
+dependencies = [
+  "httpx>=0.27.0",
+  "typing_extensions>=4.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "respx>=0.21",
+  "mypy>=1.9",
+  "ruff>=0.4",
+]
+
+[project.urls]
+Homepage = "https://deliveryapi.co.kr"
+Documentation = "https://docs.deliveryapi.co.kr"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/deliveryapi"]
+
+[tool.ruff]
+src = ["src"]
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

deliveryapi-1.0.0/src/deliveryapi/__init__.py

@@ -0,0 +1,84 @@
+"""DeliverySaaS Python SDK.
+
+Quick start::
+
+    from deliveryapi import DeliverySaasClient
+
+    client = DeliverySaasClient(api_key="pk_...", secret_key="sk_...")
+    result = client.tracking.get_one("LOTTE", "1234567890")
+    print(result["results"][0]["data"]["deliveryStatus"])
+"""
+from __future__ import annotations
+
+from ._client import AsyncDeliverySaasClient, DeliverySaasClient
+from ._exceptions import (
+    AuthenticationError,
+    DeliverySaasError,
+    NotFoundError,
+    RateLimitError,
+)
+from ._types import (
+    CourierDeliveryStatus,
+    CourierInfo,
+    CourierListResult,
+    SubscriptionCreateInput,
+    SubscriptionListResult,
+    TrackingCacheInfo,
+    TrackingError,
+    TrackingErrorCode,
+    TrackingItem,
+    TrackingProgress,
+    TrackingResponse,
+    TrackingResult,
+    TrackingSummary,
+    TrackingSubscription,
+    UnifiedTrackingResponse,
+    WebhookCreateInput,
+    WebhookEndpoint,
+    WebhookListResult,
+    WebhookPayload,
+    WebhookPayloadData,
+    WebhookTestResult,
+)
+from ._webhook import WebhookSignatureError, verify_webhook_signature
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # Clients
+    "DeliverySaasClient",
+    "AsyncDeliverySaasClient",
+    # Exceptions
+    "DeliverySaasError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    # Webhook utils
+    "verify_webhook_signature",
+    "WebhookSignatureError",
+    # Types — tracking
+    "CourierDeliveryStatus",
+    "TrackingItem",
+    "TrackingProgress",
+    "TrackingResult",
+    "TrackingError",
+    "TrackingErrorCode",
+    "TrackingCacheInfo",
+    "TrackingSummary",
+    "TrackingResponse",
+    "UnifiedTrackingResponse",
+    # Types — couriers
+    "CourierInfo",
+    "CourierListResult",
+    # Types — webhooks
+    "WebhookCreateInput",
+    "WebhookEndpoint",
+    "WebhookListResult",
+    "WebhookTestResult",
+    "WebhookPayload",
+    "WebhookPayloadData",
+    # Types — subscriptions
+    "SubscriptionCreateInput",
+    "TrackingSubscription",
+    "SubscriptionListResult",
+]

deliveryapi-1.0.0/src/deliveryapi/_client.py

@@ -0,0 +1,125 @@
+"""Main client classes for the DeliverySaaS API."""
+from __future__ import annotations
+
+from ._http import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, AsyncHttpClient, HttpClient
+from .resources.couriers import AsyncCouriersResource, CouriersResource
+from .resources.subscriptions import AsyncSubscriptionsResource, SubscriptionsResource
+from .resources.tracking import AsyncTrackingResource, TrackingResource
+from .resources.webhooks import AsyncWebhooksResource, WebhooksResource
+
+
+class DeliverySaasClient:
+    """Synchronous DeliverySaaS API client.
+
+    Args:
+        api_key: Your API key (``pk_live_...`` or ``pk_test_...``).
+        secret_key: Your secret key (``sk_live_...`` or ``sk_test_...``).
+        base_url: Override the API base URL (useful for local emulator).
+        timeout: HTTP request timeout in seconds (default: 30).
+
+    Example::
+
+        from deliveryapi import DeliverySaasClient
+
+        client = DeliverySaasClient(
+            api_key="pk_live_...",
+            secret_key="sk_live_...",
+        )
+
+        # List supported couriers
+        couriers = client.couriers.list()
+
+        # Query tracking status
+        result = client.tracking.get_one("LOTTE", "1234567890")
+
+        # Manage webhook endpoints
+        endpoint = client.webhooks.create({"url": "https://my.server/webhook"})
+
+        # Create a subscription
+        sub = client.subscriptions.create({
+            "courierCode": "LOTTE",
+            "trackingNumber": "1234567890",
+            "endpointId": endpoint["id"],
+        })
+
+    Context manager::
+
+        with DeliverySaasClient(api_key="...", secret_key="...") as client:
+            result = client.tracking.get_one("LOTTE", "1234567890")
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        secret_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        http = HttpClient(api_key, secret_key, base_url, timeout)
+        self.tracking = TrackingResource(http)
+        self.couriers = CouriersResource(http)
+        self.webhooks = WebhooksResource(http)
+        self.subscriptions = SubscriptionsResource(http)
+        self._http = http
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> DeliverySaasClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncDeliverySaasClient:
+    """Async DeliverySaaS API client (requires asyncio).
+
+    Args:
+        api_key: Your API key (``pk_live_...`` or ``pk_test_...``).
+        secret_key: Your secret key (``sk_live_...`` or ``sk_test_...``).
+        base_url: Override the API base URL (useful for local emulator).
+        timeout: HTTP request timeout in seconds (default: 30).
+
+    Example::
+
+        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())
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        secret_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        http = AsyncHttpClient(api_key, secret_key, base_url, timeout)
+        self.tracking = AsyncTrackingResource(http)
+        self.couriers = AsyncCouriersResource(http)
+        self.webhooks = AsyncWebhooksResource(http)
+        self.subscriptions = AsyncSubscriptionsResource(http)
+        self._http = http
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP connection pool."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncDeliverySaasClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

deliveryapi-1.0.0/src/deliveryapi/_exceptions.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+
+class DeliverySaasError(Exception):
+    """Base exception for all DeliverySaaS API errors."""
+
+    def __init__(self, message: str, status_code: int, code: str | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+
+
+class AuthenticationError(DeliverySaasError):
+    def __init__(self, message: str = "Invalid API key or secret key") -> None:
+        super().__init__(message, 401, "AUTHENTICATION_ERROR")
+
+
+class RateLimitError(DeliverySaasError):
+    def __init__(self, message: str = "Rate limit exceeded") -> None:
+        super().__init__(message, 429, "RATE_LIMIT_ERROR")
+
+
+class NotFoundError(DeliverySaasError):
+    def __init__(self, message: str = "Resource not found") -> None:
+        super().__init__(message, 404, "NOT_FOUND")