scorm-dispatch-client 0.1.0__tar.gz

scorm_dispatch_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Alfocea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scorm_dispatch_client-0.1.0/PKG-INFO

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: scorm-dispatch-client
+Version: 0.1.0
+Summary: Async Python client for the scorm-dispatch API
+Keywords: scorm,scorm-dispatch,lms,elearning,httpx,asyncio,client
+Author: Daniel Alfocea
+Author-email: Daniel Alfocea <me@danielalfocea.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Education
+Classifier: Typing :: Typed
+Requires-Dist: httpx2>=2.13
+Requires-Dist: pydantic>=2.10
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/cr0hn/scorm-dispatch-python
+Project-URL: Repository, https://github.com/cr0hn/scorm-dispatch-python
+Project-URL: Issues, https://github.com/cr0hn/scorm-dispatch-python/issues
+Description-Content-Type: text/markdown
+
+# scorm-dispatch-client
+
+> LLM? Read [`llms.txt`](llms.txt) first: a concise manual of every method, error and a full example.
+
+Async Python client for scorm-dispatch, the service that
+builds lightweight SCORM packages from a neutral JSON course and, at run time, validates partners by id and
+`Origin` and hands out short-lived signed URLs.
+
+- Async only, on `httpx2`. Python 3.11+.
+- Fully typed (`py.typed`, mypy strict). Requests are `TypedDict`s, responses are frozen pydantic models.
+- Covers the admin API, the public runtime endpoint and the health routes.
+- One exception, `ScormDispatchError`, carrying the HTTP status and the RFC 9457 problem body.
+
+## Install
+
+```sh
+pip install scorm-dispatch-client
+# or straight from git
+pip install "scorm-dispatch-client @ git+https://github.com/cr0hn/scorm-dispatch-python"
+```
+
+## Quickstart
+
+```python
+import asyncio
+from scorm_dispatch import Client
+
+
+async def main() -> None:
+    async with Client("https://scorm.example.com", "ADMIN_API_KEY") as sd:
+        await sd.put_partner(
+            "northwind",
+            {
+                "name": "Northwind Academy",
+                "contactEmail": "learning@northwind.example",
+                "seatCap": 500,
+                "allowedOrigins": ["https://lms.northwind.example"],
+                "active": True,
+            },
+        )
+        await sd.put_asset(
+            "vid-walkthrough", {"kind": "video", "uri": "stream-bunny://6f1c2a9e-..."}
+        )
+        zip_bytes = await sd.create_package(
+            "northwind",
+            "2004",
+            {
+                "id": "intro",
+                "title": "Intro",
+                "version": "1",
+                "language": "en",
+                "modules": [
+                    {
+                        "title": "Start",
+                        "lessons": [
+                            {
+                                "id": "l1",
+                                "title": "Welcome",
+                                "type": "text",
+                                "html": "<p>Hello</p>",
+                            },
+                            {
+                                "id": "l2",
+                                "title": "Video",
+                                "type": "video",
+                                "assetKey": "vid-walkthrough",
+                            },
+                        ],
+                    }
+                ],
+            },
+        )
+        open("intro.zip", "wb").write(zip_bytes)
+
+
+asyncio.run(main())
+```
+
+## Methods
+
+`Client(base_url, admin_key, *, http_client=None, timeout=30.0)`. Use it as `async with`, or call `aclose()`.
+
+| Method | Route | Returns |
+|---|---|---|
+| `put_partner(partner_id, partner)` | `PUT /v1/partners/{id}` | `Partner` |
+| `get_partner(partner_id)` | `GET /v1/partners/{id}` | `Partner` |
+| `list_partners(*, limit=50, offset=0)` | `GET /v1/partners` | `PartnerList` |
+| `put_asset(asset_key, asset)` | `PUT /v1/assets/{key}` | `Asset` (has `asset_id`) |
+| `get_asset(asset_key)` | `GET /v1/assets/{key}` | `Asset` |
+| `create_package(partner_id, scorm_version, course)` | `POST /v1/packages` | `bytes` (the zip) |
+| `get_usage_report(month)` | `GET /v1/reports/usage` | `UsageReport` |
+| `get_usage_report_csv(month)` | same, `Accept: text/csv` | `str` |
+| `get_runtime_asset(asset_id, *, partner, learner, origin)` | `GET /v1/runtime/assets/{id}` | `RuntimeAsset` |
+| `healthz()` / `readyz()` | `GET /healthz`, `/readyz` | `None` (raises if not ok) |
+
+Examples of the less obvious ones:
+
+```python
+page = await sd.list_partners(limit=100)
+for p in page.items:
+    print(p.partner_id, p.seat_cap, p.active)
+
+report = await sd.get_usage_report("2026-11")  # month is YYYY-MM
+csv_text = await sd.get_usage_report_csv("2026-11")
+
+# What a package does in the browser; useful to check a partner's setup.
+# It sends the Origin you pass and never the admin key.
+asset = await sd.get_runtime_asset(
+    "Zk3p9QwL7xYb2NcVd8TfRa",
+    partner="northwind",
+    learner="student-1",
+    origin="https://lms.northwind.example",
+)
+print(asset.kind, asset.url, asset.expires_at)
+```
+
+## Error handling
+
+Every non-2xx answer raises `ScormDispatchError`:
+
+```python
+from scorm_dispatch import ScormDispatchError
+
+try:
+    await sd.create_package("northwind", "2004", course)
+except ScormDispatchError as e:
+    e.status  # int: 400, 401, 403, 404, 409, 413, 422, 429, 5xx
+    e.problem  # Problem: type, title, status, detail, errors
+    e.field_errors  # 422 only: [FieldError(path="course.modules[0]...", message="...")]
+    e.retry_after  # 429 only: seconds, from Retry-After (seconds or HTTP-date form)
+```
+
+| Status | Meaning |
+|---|---|
+| 400 | malformed request or parameter |
+| 401 | wrong admin key |
+| 403 | runtime: partner unknown/inactive or `Origin` not allowed |
+| 404 | partner, asset or runtime asset not found |
+| 409 | asset `kind` cannot change |
+| 413 | package body above the server's limit |
+| 422 | validation failed; see `field_errors` |
+| 429 | rate limit; wait `retry_after` seconds |
+
+A non-problem body (for example a proxy's HTML page) still raises, with the text in `problem.detail`.
+A 2xx body that does not parse also raises `ScormDispatchError` (title `Unparseable response body`).
+Unknown enum values in responses (for example a new asset `kind`) are accepted as plain strings.
+Network failures are `httpx2` exceptions and are not wrapped.
+
+**Redirects are never followed**: a 3xx answer raises `ScormDispatchError` naming the redirect target, even if
+you pass an `http_client` with `follow_redirects=True`. This keeps the Bearer key on the configured host.
+Fix `base_url` instead.
+
+## Timeouts and retries
+
+`timeout` (seconds) applies to every request. If you omit it, an owned client uses 30 and an injected
+`http_client` keeps its own timeout; pass `timeout` explicitly to override it. **The client never retries**: `PUT` upserts are
+idempotent and safe for you to retry; `POST /v1/packages` is a pure function of its body, also safe.
+Back off on 429 using `retry_after`. To tune pooling or add transport-level retries, pass your own
+`httpx2.AsyncClient` as `http_client` (you then own and close it).
+
+## Typing
+
+Request bodies are `TypedDict`s with the wire (camelCase) keys: your type checker catches typos and wrong
+lesson shapes. Responses are frozen pydantic models with snake_case attributes and parsed datetimes.
+Unknown response fields are ignored, so a newer server does not break an older client.
+
+## Versioning and compatibility
+
+The client follows semantic versioning. It is built and tested against the contract in
+[`spec/openapi.yaml`](spec/openapi.yaml) (API 1.x); a 1.x server is expected to work with any 0.x/1.x client.
+
+What each suite checks:
+
+- **Unit** (`tests/test_unit.py`): the exact requests the client builds and how it maps answers and errors,
+  against an in-memory transport; 100% line and branch coverage is enforced.
+- **Contract** (`tests/test_contract.py`): the requests the client builds, and hand-written sample responses,
+  are validated against `spec/openapi.yaml`. The samples are written by hand, so this proves the client agrees
+  with the spec, not that the server does.
+- **Integration** (`tests/test_integration.py`): the real server (built from source, with Postgres behind
+  PgBouncer and MinIO) answers every public method and error status. This is what covers real responses.
+
+## Development
+
+```sh
+make check          # lint, mypy, unit+contract on Python 3.11-3.14, integration
+make matrix         # only unit+contract on every supported Python (each in its own .venv-3.X)
+make integration    # needs Docker, Go, and the server source: SCORM_DISPATCH_SRC=../scorm-dispatch
+```
+
+The integration suite builds the real server, starts Postgres behind PgBouncer and MinIO with
+testcontainers, and runs every public method and documented error status against it. It fails, not skips,
+if the server source is missing.
+
+## Contributing
+
+Issues and pull requests welcome. CI (`.github/workflows/ci.yml`) runs lint, mypy and unit+contract on
+Python 3.11-3.14. It cannot run the integration suite, which needs the private server source: run
+`make integration` locally before sending a change. Keep `make check` green; a change in behaviour needs a unit test and an
+integration test. When the server API changes, copy its `api/openapi.yaml` to `spec/openapi.yaml`.
+
+## Security
+
+Report vulnerabilities privately to me@danielalfocea.com. Never put the admin key in a browser: this client
+is for server-side use. Runtime calls are made by packages in browsers, not by this client in production.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

scorm_dispatch_client-0.1.0/README.md

@@ -0,0 +1,208 @@
+# scorm-dispatch-client
+
+> LLM? Read [`llms.txt`](llms.txt) first: a concise manual of every method, error and a full example.
+
+Async Python client for scorm-dispatch, the service that
+builds lightweight SCORM packages from a neutral JSON course and, at run time, validates partners by id and
+`Origin` and hands out short-lived signed URLs.
+
+- Async only, on `httpx2`. Python 3.11+.
+- Fully typed (`py.typed`, mypy strict). Requests are `TypedDict`s, responses are frozen pydantic models.
+- Covers the admin API, the public runtime endpoint and the health routes.
+- One exception, `ScormDispatchError`, carrying the HTTP status and the RFC 9457 problem body.
+
+## Install
+
+```sh
+pip install scorm-dispatch-client
+# or straight from git
+pip install "scorm-dispatch-client @ git+https://github.com/cr0hn/scorm-dispatch-python"
+```
+
+## Quickstart
+
+```python
+import asyncio
+from scorm_dispatch import Client
+
+
+async def main() -> None:
+    async with Client("https://scorm.example.com", "ADMIN_API_KEY") as sd:
+        await sd.put_partner(
+            "northwind",
+            {
+                "name": "Northwind Academy",
+                "contactEmail": "learning@northwind.example",
+                "seatCap": 500,
+                "allowedOrigins": ["https://lms.northwind.example"],
+                "active": True,
+            },
+        )
+        await sd.put_asset(
+            "vid-walkthrough", {"kind": "video", "uri": "stream-bunny://6f1c2a9e-..."}
+        )
+        zip_bytes = await sd.create_package(
+            "northwind",
+            "2004",
+            {
+                "id": "intro",
+                "title": "Intro",
+                "version": "1",
+                "language": "en",
+                "modules": [
+                    {
+                        "title": "Start",
+                        "lessons": [
+                            {
+                                "id": "l1",
+                                "title": "Welcome",
+                                "type": "text",
+                                "html": "<p>Hello</p>",
+                            },
+                            {
+                                "id": "l2",
+                                "title": "Video",
+                                "type": "video",
+                                "assetKey": "vid-walkthrough",
+                            },
+                        ],
+                    }
+                ],
+            },
+        )
+        open("intro.zip", "wb").write(zip_bytes)
+
+
+asyncio.run(main())
+```
+
+## Methods
+
+`Client(base_url, admin_key, *, http_client=None, timeout=30.0)`. Use it as `async with`, or call `aclose()`.
+
+| Method | Route | Returns |
+|---|---|---|
+| `put_partner(partner_id, partner)` | `PUT /v1/partners/{id}` | `Partner` |
+| `get_partner(partner_id)` | `GET /v1/partners/{id}` | `Partner` |
+| `list_partners(*, limit=50, offset=0)` | `GET /v1/partners` | `PartnerList` |
+| `put_asset(asset_key, asset)` | `PUT /v1/assets/{key}` | `Asset` (has `asset_id`) |
+| `get_asset(asset_key)` | `GET /v1/assets/{key}` | `Asset` |
+| `create_package(partner_id, scorm_version, course)` | `POST /v1/packages` | `bytes` (the zip) |
+| `get_usage_report(month)` | `GET /v1/reports/usage` | `UsageReport` |
+| `get_usage_report_csv(month)` | same, `Accept: text/csv` | `str` |
+| `get_runtime_asset(asset_id, *, partner, learner, origin)` | `GET /v1/runtime/assets/{id}` | `RuntimeAsset` |
+| `healthz()` / `readyz()` | `GET /healthz`, `/readyz` | `None` (raises if not ok) |
+
+Examples of the less obvious ones:
+
+```python
+page = await sd.list_partners(limit=100)
+for p in page.items:
+    print(p.partner_id, p.seat_cap, p.active)
+
+report = await sd.get_usage_report("2026-11")  # month is YYYY-MM
+csv_text = await sd.get_usage_report_csv("2026-11")
+
+# What a package does in the browser; useful to check a partner's setup.
+# It sends the Origin you pass and never the admin key.
+asset = await sd.get_runtime_asset(
+    "Zk3p9QwL7xYb2NcVd8TfRa",
+    partner="northwind",
+    learner="student-1",
+    origin="https://lms.northwind.example",
+)
+print(asset.kind, asset.url, asset.expires_at)
+```
+
+## Error handling
+
+Every non-2xx answer raises `ScormDispatchError`:
+
+```python
+from scorm_dispatch import ScormDispatchError
+
+try:
+    await sd.create_package("northwind", "2004", course)
+except ScormDispatchError as e:
+    e.status  # int: 400, 401, 403, 404, 409, 413, 422, 429, 5xx
+    e.problem  # Problem: type, title, status, detail, errors
+    e.field_errors  # 422 only: [FieldError(path="course.modules[0]...", message="...")]
+    e.retry_after  # 429 only: seconds, from Retry-After (seconds or HTTP-date form)
+```
+
+| Status | Meaning |
+|---|---|
+| 400 | malformed request or parameter |
+| 401 | wrong admin key |
+| 403 | runtime: partner unknown/inactive or `Origin` not allowed |
+| 404 | partner, asset or runtime asset not found |
+| 409 | asset `kind` cannot change |
+| 413 | package body above the server's limit |
+| 422 | validation failed; see `field_errors` |
+| 429 | rate limit; wait `retry_after` seconds |
+
+A non-problem body (for example a proxy's HTML page) still raises, with the text in `problem.detail`.
+A 2xx body that does not parse also raises `ScormDispatchError` (title `Unparseable response body`).
+Unknown enum values in responses (for example a new asset `kind`) are accepted as plain strings.
+Network failures are `httpx2` exceptions and are not wrapped.
+
+**Redirects are never followed**: a 3xx answer raises `ScormDispatchError` naming the redirect target, even if
+you pass an `http_client` with `follow_redirects=True`. This keeps the Bearer key on the configured host.
+Fix `base_url` instead.
+
+## Timeouts and retries
+
+`timeout` (seconds) applies to every request. If you omit it, an owned client uses 30 and an injected
+`http_client` keeps its own timeout; pass `timeout` explicitly to override it. **The client never retries**: `PUT` upserts are
+idempotent and safe for you to retry; `POST /v1/packages` is a pure function of its body, also safe.
+Back off on 429 using `retry_after`. To tune pooling or add transport-level retries, pass your own
+`httpx2.AsyncClient` as `http_client` (you then own and close it).
+
+## Typing
+
+Request bodies are `TypedDict`s with the wire (camelCase) keys: your type checker catches typos and wrong
+lesson shapes. Responses are frozen pydantic models with snake_case attributes and parsed datetimes.
+Unknown response fields are ignored, so a newer server does not break an older client.
+
+## Versioning and compatibility
+
+The client follows semantic versioning. It is built and tested against the contract in
+[`spec/openapi.yaml`](spec/openapi.yaml) (API 1.x); a 1.x server is expected to work with any 0.x/1.x client.
+
+What each suite checks:
+
+- **Unit** (`tests/test_unit.py`): the exact requests the client builds and how it maps answers and errors,
+  against an in-memory transport; 100% line and branch coverage is enforced.
+- **Contract** (`tests/test_contract.py`): the requests the client builds, and hand-written sample responses,
+  are validated against `spec/openapi.yaml`. The samples are written by hand, so this proves the client agrees
+  with the spec, not that the server does.
+- **Integration** (`tests/test_integration.py`): the real server (built from source, with Postgres behind
+  PgBouncer and MinIO) answers every public method and error status. This is what covers real responses.
+
+## Development
+
+```sh
+make check          # lint, mypy, unit+contract on Python 3.11-3.14, integration
+make matrix         # only unit+contract on every supported Python (each in its own .venv-3.X)
+make integration    # needs Docker, Go, and the server source: SCORM_DISPATCH_SRC=../scorm-dispatch
+```
+
+The integration suite builds the real server, starts Postgres behind PgBouncer and MinIO with
+testcontainers, and runs every public method and documented error status against it. It fails, not skips,
+if the server source is missing.
+
+## Contributing
+
+Issues and pull requests welcome. CI (`.github/workflows/ci.yml`) runs lint, mypy and unit+contract on
+Python 3.11-3.14. It cannot run the integration suite, which needs the private server source: run
+`make integration` locally before sending a change. Keep `make check` green; a change in behaviour needs a unit test and an
+integration test. When the server API changes, copy its `api/openapi.yaml` to `spec/openapi.yaml`.
+
+## Security
+
+Report vulnerabilities privately to me@danielalfocea.com. Never put the admin key in a browser: this client
+is for server-side use. Runtime calls are made by packages in browsers, not by this client in production.
+
+## License
+
+MIT, see [LICENSE](LICENSE).

scorm_dispatch_client-0.1.0/pyproject.toml

@@ -0,0 +1,69 @@
+[project]
+name = "scorm-dispatch-client"
+version = "0.1.0"
+description = "Async Python client for the scorm-dispatch API"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Daniel Alfocea", email = "me@danielalfocea.com" }]
+keywords = ["scorm", "scorm-dispatch", "lms", "elearning", "httpx", "asyncio", "client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Education",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx2>=2.13",
+    "pydantic>=2.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/cr0hn/scorm-dispatch-python"
+Repository = "https://github.com/cr0hn/scorm-dispatch-python"
+Issues = "https://github.com/cr0hn/scorm-dispatch-python/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=9",
+    "pytest-asyncio>=1.0",
+    "ruff>=0.15",
+    "mypy>=2",
+    "openapi-core>=0.19",
+    "pyyaml>=6",
+    "types-pyyaml",
+    "testcontainers>=4.9",
+    "pytest-cov>=6",
+]
+
+[build-system]
+requires = ["uv_build>=0.11,<0.14"]
+build-backend = "uv_build"
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src"]
+plugins = ["pydantic.mypy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+pythonpath = ["."]
+markers = ["integration: builds the Go binary and needs Docker (make python-sdk-check)"]
+
+[tool.uv.build-backend]
+module-name = "scorm_dispatch"
+
+[tool.coverage.run]
+source = ["scorm_dispatch"]
+branch = true

scorm_dispatch_client-0.1.0/src/scorm_dispatch/__init__.py

@@ -0,0 +1,29 @@
+"""Async Python client for scorm-dispatch. Start with `Client`."""
+
+from scorm_dispatch.client import Client
+from scorm_dispatch.errors import ScormDispatchError
+from scorm_dispatch.models import (
+    Asset,
+    AssetInput,
+    Course,
+    Partner,
+    PartnerInput,
+    PartnerList,
+    Problem,
+    RuntimeAsset,
+    UsageReport,
+)
+
+__all__ = [
+    "Asset",
+    "AssetInput",
+    "Client",
+    "Course",
+    "Partner",
+    "PartnerInput",
+    "PartnerList",
+    "Problem",
+    "RuntimeAsset",
+    "ScormDispatchError",
+    "UsageReport",
+]

scorm_dispatch_client-0.1.0/src/scorm_dispatch/client.py

@@ -0,0 +1,230 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from types import TracebackType
+from typing import Self, TypeVar
+from urllib.parse import quote
+
+import httpx2
+from pydantic import BaseModel, ValidationError
+
+from scorm_dispatch.errors import ScormDispatchError
+from scorm_dispatch.models import (
+    Asset,
+    AssetInput,
+    Course,
+    PackageRequest,
+    Partner,
+    PartnerInput,
+    PartnerList,
+    Problem,
+    RuntimeAsset,
+    ScormVersion,
+    UsageReport,
+)
+
+
+def _seg(value: str) -> str:
+    return quote(value, safe="")
+
+
+class Client:
+    """Async client of one scorm-dispatch deployment.
+
+    Pass `http_client` to share a connection pool (you then close it yourself); otherwise the
+    client owns one and `aclose()` / `async with` closes it. `timeout` (seconds) defaults to 30
+    for an owned client and to the injected client's own timeout; set it to override either.
+    Redirects are never followed, so the admin key cannot leave `base_url`.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        admin_key: str,
+        *,
+        http_client: httpx2.AsyncClient | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        self._base = base_url.rstrip("/")
+        self._admin_key = admin_key
+        self._owns_http = http_client is None
+        self._http = http_client or httpx2.AsyncClient(timeout=30.0 if timeout is None else timeout)
+        self._timeout = timeout
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context; returns the client."""
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        """Close the client (only the HTTP client it owns)."""
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the HTTP client, unless it was injected."""
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        admin: bool = True,
+        params: Mapping[str, str | int] | None = None,
+        headers: Mapping[str, str] | None = None,
+        json: object = None,
+    ) -> httpx2.Response:
+        h = dict(headers or {})
+        if admin:  # the runtime and health routes are public: never leak the key there
+            h["Authorization"] = f"Bearer {self._admin_key}"
+        response = await self._http.request(
+            method,
+            self._base + path,
+            params=params,
+            headers=h,
+            json=json,
+            timeout=httpx2.USE_CLIENT_DEFAULT if self._timeout is None else self._timeout,
+            follow_redirects=False,
+        )
+        if response.is_success:
+            return response
+        raise _error(response)
+
+    # --- partners ---------------------------------------------------------------------------
+
+    async def put_partner(self, partner_id: str, partner: PartnerInput) -> Partner:
+        """Idempotent upsert; replaces every field."""
+        r = await self._send("PUT", f"/v1/partners/{_seg(partner_id)}", json=partner)
+        return _parse(Partner, r)
+
+    async def get_partner(self, partner_id: str) -> Partner:
+        """Fetch one partner (404 if missing)."""
+        r = await self._send("GET", f"/v1/partners/{_seg(partner_id)}")
+        return _parse(Partner, r)
+
+    async def list_partners(self, *, limit: int = 50, offset: int = 0) -> PartnerList:
+        """One page of partners ordered by id; `limit` 1-200."""
+        r = await self._send("GET", "/v1/partners", params={"limit": limit, "offset": offset})
+        return _parse(PartnerList, r)
+
+    # --- assets -----------------------------------------------------------------------------
+
+    async def put_asset(self, asset_key: str, asset: AssetInput) -> Asset:
+        """Idempotent upsert; `assetId` never changes once created."""
+        r = await self._send("PUT", f"/v1/assets/{_seg(asset_key)}", json=asset)
+        return _parse(Asset, r)
+
+    async def get_asset(self, asset_key: str) -> Asset:
+        """Fetch one asset (404 if missing)."""
+        r = await self._send("GET", f"/v1/assets/{_seg(asset_key)}")
+        return _parse(Asset, r)
+
+    # --- packages and reports ---------------------------------------------------------------
+
+    async def create_package(
+        self, partner_id: str, scorm_version: ScormVersion, course: Course
+    ) -> bytes:
+        """Generate a SCORM package; returns the zip."""
+        body: PackageRequest = {
+            "partnerId": partner_id,
+            "scormVersion": scorm_version,
+            "course": course,
+        }
+        r = await self._send("POST", "/v1/packages", json=body)
+        return r.content
+
+    async def get_usage_report(self, month: str) -> UsageReport:
+        """Active learners per partner for `month` (`YYYY-MM`)."""
+        r = await self._send("GET", "/v1/reports/usage", params={"month": month})
+        return _parse(UsageReport, r)
+
+    async def get_usage_report_csv(self, month: str) -> str:
+        """Same report as `get_usage_report`, as RFC 4180 CSV text."""
+        r = await self._send(
+            "GET", "/v1/reports/usage", params={"month": month}, headers={"Accept": "text/csv"}
+        )
+        return r.content.decode("utf-8")
+
+    # --- runtime and operations -------------------------------------------------------------
+
+    async def get_runtime_asset(
+        self, asset_id: str, *, partner: str, learner: str, origin: str
+    ) -> RuntimeAsset:
+        """What a package does in the browser. Public route: sends `Origin`, never the key."""
+        r = await self._send(
+            "GET",
+            f"/v1/runtime/assets/{_seg(asset_id)}",
+            admin=False,
+            params={"partner": partner, "learner": learner},
+            headers={"Origin": origin},
+        )
+        return _parse(RuntimeAsset, r)
+
+    async def healthz(self) -> None:
+        """Process alive. Raises `ScormDispatchError` otherwise."""
+        await self._send("GET", "/healthz", admin=False)
+
+    async def readyz(self) -> None:
+        """Database reachable. Raises `ScormDispatchError` (503) otherwise."""
+        await self._send("GET", "/readyz", admin=False)
+
+
+_M = TypeVar("_M", bound=BaseModel)
+
+
+def _parse(model: type[_M], response: httpx2.Response) -> _M:
+    try:
+        return model.model_validate_json(response.content)
+    except ValidationError as exc:
+        problem = Problem(
+            title="Unparseable response body",
+            status=response.status_code,
+            detail=f"{model.__name__}: {exc.error_count()} validation error(s)",
+        )
+        raise ScormDispatchError(response.status_code, problem) from exc
+
+
+def _retry_after(value: str | None) -> int | None:
+    """Seconds from a `Retry-After` header, in its delta-seconds or HTTP-date form."""
+    if not value:
+        return None
+    if value.isascii() and value.isdigit():
+        return int(value)
+    try:
+        when = parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    if when.tzinfo is None:  # "-0000" means UTC with unknown local zone
+        when = when.replace(tzinfo=UTC)
+    return max(0, int((when - datetime.now(UTC)).total_seconds()))
+
+
+def _error(response: httpx2.Response) -> ScormDispatchError:
+    if 300 <= response.status_code < 400:
+        target = response.headers.get("Location")
+        where = f"to {target}" if target else "(no Location header)"
+        problem = Problem(
+            title="Unexpected redirect",
+            status=response.status_code,
+            detail=f"The server answered with a redirect {where}. The SDK never follows "
+            "redirects, so the admin key stays on the configured host; fix base_url.",
+        )
+        return ScormDispatchError(response.status_code, problem)
+    try:
+        problem = Problem.model_validate_json(response.content)
+    except ValidationError:  # a proxy's HTML page, an empty body, JSON that is no Problem...
+        problem = Problem(
+            title=response.reason_phrase,
+            status=response.status_code,
+            detail=response.text[:500] or None,
+        )
+    return ScormDispatchError(
+        response.status_code, problem, _retry_after(response.headers.get("Retry-After"))
+    )

scorm_dispatch_client-0.1.0/src/scorm_dispatch/errors.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Self
+
+from scorm_dispatch.models import FieldError, Problem
+
+
+class ScormDispatchError(Exception):
+    """Any non-2xx answer. Branch on `status`:
+
+    400 malformed request, 401 bad admin key, 403 runtime access refused, 404 not found,
+    409 conflict (asset kind change), 422 validation (see `field_errors`), 429 rate limit
+    (see `retry_after`), 5xx server side.
+    """
+
+    def __init__(self, status: int, problem: Problem, retry_after: int | None = None) -> None:
+        self.status = status
+        self.problem = problem
+        self.retry_after = retry_after
+        message = f"{status} {problem.title}"
+        super().__init__(f"{message}: {problem.detail}" if problem.detail else message)
+
+    def __reduce__(self) -> tuple[type[Self], tuple[int, Problem, int | None]]:
+        # Exception.__reduce__ would replay the single formatted message as args: unpicklable.
+        return (type(self), (self.status, self.problem, self.retry_after))
+
+    @property
+    def field_errors(self) -> list[FieldError]:
+        """Per-field problems of a 422; empty for every other status."""
+        return self.problem.errors or []

scorm_dispatch_client-0.1.0/src/scorm_dispatch/models.py

@@ -0,0 +1,244 @@
+"""Typed bodies of the scorm-dispatch API.
+
+Requests are TypedDicts with the wire (camelCase) keys, so a literal reads like the docs.
+Responses are frozen pydantic models: they validate what the server sent and expose
+snake_case attributes.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, TypedDict
+
+from pydantic import BaseModel, ConfigDict
+from pydantic.alias_generators import to_camel
+
+AssetKind = Literal["video", "file"]
+ScormVersion = Literal["1.2", "2004"]
+
+
+# --- request bodies -------------------------------------------------------------------------
+
+
+class PartnerInput(TypedDict):
+    """Body of `put_partner`; replaces every field of the partner."""
+
+    name: str
+    contactEmail: str
+    seatCap: int
+    allowedOrigins: list[str]
+    active: bool
+
+
+class AssetInput(TypedDict):
+    """Body of `put_asset`; `kind` cannot change once the asset exists."""
+
+    kind: AssetKind
+    uri: str
+
+
+class Option(TypedDict):
+    """One answer option of a question."""
+
+    id: str
+    html: str
+
+
+class Question(TypedDict):
+    """A `single` (one correct option) or `multiple` choice question."""
+
+    id: str
+    type: Literal["single", "multiple"]
+    promptHtml: str
+    options: list[Option]
+    correct: list[str]
+
+
+class Quiz(TypedDict):
+    """A quiz lesson body; at most one quiz per course may be `final`."""
+
+    final: bool
+    passingScore: int
+    questions: list[Question]
+
+
+class TextLesson(TypedDict):
+    """Lesson with sanitised HTML."""
+
+    id: str
+    title: str
+    type: Literal["text"]
+    html: str
+
+
+class VideoLesson(TypedDict):
+    """Lesson that plays a registered video asset."""
+
+    id: str
+    title: str
+    type: Literal["video"]
+    assetKey: str
+
+
+class FileLesson(TypedDict):
+    """Lesson that offers a registered file asset."""
+
+    id: str
+    title: str
+    type: Literal["file"]
+    assetKey: str
+    fileName: str
+
+
+class QuizLesson(TypedDict):
+    """Lesson that holds a quiz."""
+
+    id: str
+    title: str
+    type: Literal["quiz"]
+    quiz: Quiz
+
+
+Lesson = TextLesson | VideoLesson | FileLesson | QuizLesson
+
+
+class Module(TypedDict):
+    """A titled group of lessons."""
+
+    title: str
+    lessons: list[Lesson]
+
+
+class Course(TypedDict):
+    """The neutral course format sent to `create_package`."""
+
+    id: str
+    title: str
+    version: str
+    language: str
+    modules: list[Module]
+
+
+class PackageRequest(TypedDict):
+    """Body of `POST /v1/packages`."""
+
+    partnerId: str
+    scormVersion: ScormVersion
+    course: Course
+
+
+# --- responses ------------------------------------------------------------------------------
+
+
+class _Response(BaseModel):
+    # Unknown fields are ignored: a newer server must not break an older client.
+    model_config = ConfigDict(alias_generator=to_camel, populate_by_name=True, frozen=True)
+
+
+class Partner(_Response):
+    """A content partner as stored by the server."""
+
+    partner_id: str
+    name: str
+    contact_email: str
+    seat_cap: int
+    allowed_origins: list[str]
+    active: bool
+    created_at: datetime
+    updated_at: datetime
+
+
+class PartnerList(_Response):
+    """One page of partners and the total count."""
+
+    items: list[Partner]
+    total: int
+
+
+class Asset(_Response):
+    """A registered video or file; `asset_id` is opaque and stable."""
+
+    asset_key: str
+    asset_id: str
+    kind: str  # `AssetKind` today; a plain str so a new server kind does not break parsing
+    uri: str
+    created_at: datetime
+    updated_at: datetime
+
+
+class RuntimeAsset(_Response):
+    """Short-lived signed URL for an asset."""
+
+    kind: str  # see `Asset.kind`
+    url: str
+    expires_at: datetime
+
+
+class RejectedOrigin(_Response):
+    """An origin refused by the runtime and how many times."""
+
+    origin: str
+    count: int
+
+
+class PartnerUsage(_Response):
+    """Usage of one partner in one month."""
+
+    partner_id: str
+    name: str
+    seat_cap: int
+    active_learners: int
+    rejected_origins: list[RejectedOrigin]
+
+
+class UsageReport(_Response):
+    """Active learners per partner for one month."""
+
+    month: str
+    partners: list[PartnerUsage]
+
+
+class FieldError(_Response):
+    """One validation problem and the path of the offending field."""
+
+    path: str
+    message: str
+
+
+class Problem(_Response):
+    """RFC 9457 body. `errors` is present on 422 only."""
+
+    type: str = "about:blank"
+    title: str
+    status: int
+    detail: str | None = None
+    instance: str | None = None
+    errors: list[FieldError] | None = None
+
+
+__all__ = [
+    "Asset",
+    "AssetInput",
+    "AssetKind",
+    "Course",
+    "FieldError",
+    "FileLesson",
+    "Lesson",
+    "Module",
+    "Option",
+    "PackageRequest",
+    "Partner",
+    "PartnerInput",
+    "PartnerList",
+    "PartnerUsage",
+    "Problem",
+    "Question",
+    "Quiz",
+    "QuizLesson",
+    "RejectedOrigin",
+    "RuntimeAsset",
+    "ScormVersion",
+    "TextLesson",
+    "UsageReport",
+    "VideoLesson",
+]