Metadata-Version: 2.4
Name: tracing-platform-sdk
Version: 1.0.1
Summary: Official Python SDK for the Tracing Platform
Author-email: Tracing Platform <sdk@tracingplatform.com>
License: MIT
Project-URL: Homepage, https://www.tracingplatform.com
Project-URL: Documentation, https://docs.tracingplatform.com
Project-URL: Repository, https://github.com/tracing-platform/sdk-python
Project-URL: Issues, https://github.com/tracing-platform/sdk-python/issues
Keywords: tracing,epcis,supply-chain,did,blockchain,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-core>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"

# Tracing Platform Python SDK

Official Python SDK for the [Tracing Platform](https://www.tracingplatform.com) — EPCIS 2.0 supply chain traceability with DID + Blockchain anchoring.

## Installation

```bash
pip install tracing-platform-sdk
```

## Requirements

- Python 3.8+
- `aiohttp >= 3.8.0`
- `pydantic >= 2.0.0`

## Quick Start

```python
import asyncio
from tracing_sdk import TracingClient, TracingClientOptions

async def main():
    client = TracingClient(TracingClientOptions(
        base_url="https://api.tracingplatform.com",
        client_id="your_client_id",
        client_secret="your_client_secret",
    ))

    # Commission a new LOT
    event = await client.commission.create({
        "signerDidHash": "did:neo:abc123",
        "productId": 1,
        "lotCode": "LOT-2024-001",
        "quantity": 100,
        "uom": "KGM",
        "productionDate": "2024-01-15",
        "bizLocation": "urn:epc:id:sgln:...",
        "bizStep": "commissioning",
        "disposition": "active",
        "readPoint": "urn:epc:id:sgln:...",
    })
    print(event)

asyncio.run(main())
```

## Authentication

The SDK uses **OAuth2 client_credentials** flow automatically:

```python
client = TracingClient(TracingClientOptions(
    base_url="https://api.tracingplatform.com",
    client_id="your_client_id",       # from API Credentials page
    client_secret="your_client_secret",
    scopes=["commission.write", "shipping.read"],  # optional — omit for full access
))
```

Tokens are cached and refreshed automatically.

## Available Modules

| Module | Access | Description |
|--------|--------|-------------|
| `client.commission` | `commission.read/write` | LOT genesis events |
| `client.aggregation` | `aggregation.read/write` | Pack/unpack containers |
| `client.shipping` | `shipping.read/write` | Shipment creation + ASN |
| `client.receiving` | `receiving.read/write` | QC + custody transfer |
| `client.transformation` | `transformation.read/write` | Input LOTs → Output LOT |
| `client.recall` | `recall.read/write` | Recall alerts management |
| `client.custody` | `custody.read` | Custody ledger overview |
| `client.traceability` | `traceability.read` | LOT timeline + tree |
| `client.anchor` | `anchor.read` | Blockchain verification |
| `client.products` | `products.read/write` | Product catalog |
| `client.did_profile` | `did_profile.read/write` | DID + location management |
| `client.members` | `members.read/write` | Team member management |
| `client.auth` | — | Token introspection |
| `client.ops` | `ops.write` | Batch supply chain operations |

## Error Handling

```python
from tracing_sdk import TracingClient, AuthError, ValidationError, NotFoundError

try:
    event = await client.commission.create(...)
except AuthError:
    print("Invalid credentials or expired token")
except ValidationError as e:
    print(f"Validation failed: {e}")
except NotFoundError:
    print("Resource not found")
```

## Pagination

```python
from tracing_sdk import PaginationHelper

# Fetch all pages automatically
all_events = await PaginationHelper.fetch_all(
    client.commission.list,
    params={"page": 1, "limit": 50},
)
```

## License

MIT
