Metadata-Version: 2.4
Name: facet-sdk
Version: 0.1.0
Summary: Facet Terminal Python SDK — typed client generated from openapi/openapi.yaml plus an ergonomic discovery + auth wrapper.
Project-URL: Homepage, https://facet.llc
Project-URL: Repository, https://github.com/lynz-tonomi/facet
Project-URL: Issues, https://github.com/lynz-tonomi/facet/issues
Author-email: Facet <hello@facet.llc>
License: Apache-2.0
License-File: LICENSE
Keywords: agent,commerce,facet,openapi,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: attrs>=21.3.0
Requires-Dist: httpx<0.29.0,>=0.20.0
Requires-Dist: python-dateutil>=2.8.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: openapi-python-client==0.28.4; extra == 'dev'
Requires-Dist: pytest-httpx>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# facet-sdk (Python)

Python SDK for the [Facet Terminal](https://facet.llc) — the per-merchant
HTTP contract that every Facet deployment exposes.

The typed request/response surface is **generated from `openapi/openapi.yaml`**
via [`openapi-python-client`](https://github.com/openapi-generators/openapi-python-client).
A thin ergonomic wrapper at `facet_sdk` provides defaults (User-Agent,
timeout) and an authenticated-client factory.

> Phase 8 of `openapi-as-contract`. The wire surface is spec-driven —
> never edit `src/facet_terminal_client/` by hand. Run
> `bash scripts/regenerate.sh` after `scripts/build-openapi.sh` to pull
> in the latest spec.

## Install

```bash
pip install facet-sdk
```

## Quickstart

```python
from facet_sdk import create_terminal_client
from facet_terminal_client.api.protocol_core import get_health, get_capabilities

client = create_terminal_client("https://terminal.facet.llc")

health = get_health.sync(client=client)
# `health` is a HealthResponse, a FacetErrorEnvelope, or None

caps = get_capabilities.sync(client=client)
```

## Authenticated calls (KYA token)

Endpoints in the four-verb commerce primitive surface (search, quote,
reserve, settle) and most tool surfaces require a KYA bearer token:

```python
from facet_sdk import create_terminal_client
from facet_terminal_client.api.protocol_core import quote
from facet_terminal_client.models import QuoteRequest

client = create_terminal_client(
    "https://terminal.facet.llc",
    kya_token="kya-bearer-from-skyfire-or-similar",
)

resp = quote.sync(client=client, body=QuoteRequest(sku="abc", quantity=1))
```

## Architecture

| Layer              | Module                                                 | What it is                                                                      |
| ------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------- |
| Ergonomic helpers  | `facet_sdk`                                            | Hand-written wrappers (`create_terminal_client`). Stable API.                   |
| Typed wire surface | `facet_terminal_client.api.*`                          | Auto-generated per-endpoint functions. **Do not edit.**                         |
| Typed schemas      | `facet_terminal_client.models.*`                       | Auto-generated attrs classes for every `components.schemas.*`. **Do not edit.** |
| Generated client   | `facet_terminal_client.Client` / `AuthenticatedClient` | Auto-generated httpx-backed dispatch class.                                     |

## Regenerating from the spec

```bash
# Prerequisite: openapi-python-client on PATH
pipx install openapi-python-client==0.28.4

# Regenerate just sdk-python:
bash packages/sdk-python/scripts/regenerate.sh

# Or regenerate all three language SDKs from the spec:
bash scripts/regenerate-sdks.sh
```

The regen scripts are idempotent — running twice produces no diff
unless `openapi/openapi.yaml` changed.

## Tests

```bash
# Unit tests (offline):
pip install -e .[dev]
pytest

# Smoke tests against a live Facet Terminal (gated by marker):
pytest -m smoke

# Override the smoke target:
FACET_SMOKE_BASE_URL=https://my-merchant.example.com pytest -m smoke
```

## License

Apache-2.0.
