opedd 0.1.0__py3-none-any.whl

opedd/__init__.py

@@ -0,0 +1,173 @@
+"""Official Python SDK for the Opedd content licensing API (buyer-side).
+
+Quick start:
+
+    from opedd import Opedd
+
+    client = Opedd(buyer_token="opedd_buyer_live_...")
+
+    article = client.content.get("article-uuid")
+    print(article["title"], article["author"], article["word_count"])
+
+See https://docs.opedd.com/cookbook.md for end-to-end walkthroughs.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ._exceptions import (
+    OpeddAuthError,
+    OpeddError,
+    OpeddNotFoundError,
+    OpeddRateLimitError,
+    OpeddServerError,
+    OpeddValidationError,
+)
+from ._http import HttpClient
+from .audit import AuditNamespace
+from .compliance import ComplianceNamespace
+from .content import ContentNamespace
+from .feed import FeedNamespace
+from .licenses import LicensesNamespace
+
+__version__ = "0.1.0"
+__schema_version__ = "phase-11-m4"
+
+__all__ = [
+    "Opedd",
+    "OpeddAuthError",
+    "OpeddError",
+    "OpeddNotFoundError",
+    "OpeddRateLimitError",
+    "OpeddServerError",
+    "OpeddValidationError",
+    "__schema_version__",
+    "__version__",
+]
+
+
+class Opedd:
+    """Opedd buyer-side API client.
+
+    Args:
+        buyer_token: An ``opedd_buyer_live_<32-hex>`` or ``opedd_buyer_test_<32-hex>``
+            token issued by ``POST /enterprise-auth``. Used for ``/content-delivery``
+            and ``/enterprise-license`` calls.
+        buyer_jwt: A Supabase session JWT for the buyer portal. Used for
+            ``/buyer-audit`` and ``/buyer-compliance-report`` calls.
+        access_key: An ``eak_*`` enterprise access key. Some endpoints
+            (``/enterprise-license`` GET) accept this directly via ``?access_key=``
+            query param, no token exchange required.
+        base_url: Override the API base URL (default ``https://api.opedd.com``).
+            Useful for local testing or staging environments.
+        timeout: HTTP timeout in seconds. Default 300 (long enough for NDJSON streaming).
+
+    Notes:
+        At least one of ``buyer_token``, ``buyer_jwt``, or ``access_key`` must be
+        provided. Different endpoints accept different credentials — see method
+        docstrings for which credential each method requires.
+
+        Env-var fallbacks: ``OPEDD_BUYER_TOKEN``, ``OPEDD_BUYER_JWT``,
+        ``OPEDD_ACCESS_KEY``, ``OPEDD_BASE_URL``.
+
+    Example:
+
+        client = Opedd(buyer_token="opedd_buyer_live_...")
+        article = client.content.get("uuid")
+
+        for row in client.feed.stream_ndjson(limit=5000):
+            train_model.ingest(row)
+
+        dossier = client.compliance.report(from_="2026-04-01", to="2026-04-30")
+    """
+
+    def __init__(
+        self,
+        buyer_token: str | None = None,
+        buyer_jwt: str | None = None,
+        access_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 300.0,
+    ) -> None:
+        self.buyer_token = buyer_token or os.environ.get("OPEDD_BUYER_TOKEN")
+        self.buyer_jwt = buyer_jwt or os.environ.get("OPEDD_BUYER_JWT")
+        self.access_key = access_key or os.environ.get("OPEDD_ACCESS_KEY")
+        self.base_url = (base_url or os.environ.get("OPEDD_BASE_URL") or "https://api.opedd.com").rstrip("/")
+        self.timeout = timeout
+
+        if not any([self.buyer_token, self.buyer_jwt, self.access_key]):
+            raise OpeddError(
+                "Opedd client requires at least one of: buyer_token, buyer_jwt, access_key. "
+                "See https://docs.opedd.com/python-sdk.md for the credential matrix."
+            )
+
+        self._http = HttpClient(self.base_url, timeout=timeout)
+
+        self.content = ContentNamespace(self)
+        self.feed = FeedNamespace(self)
+        self.audit = AuditNamespace(self)
+        self.compliance = ComplianceNamespace(self)
+        self.licenses = LicensesNamespace(self)
+
+    @classmethod
+    def from_access_key(
+        cls,
+        access_key: str,
+        buyer_email: str,
+        base_url: str | None = None,
+    ) -> Opedd:
+        """Exchange an eak_* access key for a bearer token, return an authenticated client.
+
+        Calls ``POST /enterprise-auth`` under the hood. Useful when you only
+        have the access key emailed to you after license purchase.
+        """
+        import httpx
+
+        base = (base_url or os.environ.get("OPEDD_BASE_URL") or "https://api.opedd.com").rstrip("/")
+        resp = httpx.post(
+            f"{base}/enterprise-auth",
+            json={"access_key": access_key, "buyer_email": buyer_email},
+            timeout=30.0,
+        )
+        if resp.status_code != 200:
+            raise OpeddAuthError(
+                f"access_key exchange failed: {resp.status_code} {resp.text}",
+                status_code=resp.status_code,
+            )
+        body = resp.json()
+        bearer_token = body.get("data", {}).get("bearer_token") or body.get("bearer_token")
+        if not bearer_token:
+            raise OpeddAuthError(
+                f"access_key exchange returned no bearer_token: {body}",
+            )
+        return cls(buyer_token=bearer_token, access_key=access_key, base_url=base_url)
+
+    def _bearer_headers(self) -> dict[str, str]:
+        """Build Authorization headers for endpoints that accept buyer_token."""
+        if not self.buyer_token:
+            raise OpeddAuthError("This method requires buyer_token. Pass it at construction or set OPEDD_BUYER_TOKEN.")
+        return {"Authorization": f"Bearer {self.buyer_token}"}
+
+    def _jwt_headers(self) -> dict[str, str]:
+        """Build Authorization headers for endpoints that accept Supabase JWT."""
+        if not self.buyer_jwt:
+            raise OpeddAuthError("This method requires buyer_jwt. Pass it at construction or set OPEDD_BUYER_JWT.")
+        return {"Authorization": f"Bearer {self.buyer_jwt}"}
+
+    def _access_key_params(self) -> dict[str, str]:
+        """Build query params for endpoints that accept ?access_key=."""
+        if not self.access_key:
+            raise OpeddAuthError("This method requires access_key. Pass it at construction or set OPEDD_ACCESS_KEY.")
+        return {"access_key": self.access_key}
+
+    def close(self) -> None:
+        """Close the underlying HTTP client connection pool."""
+        self._http.close()
+
+    def __enter__(self) -> Opedd:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

opedd/_exceptions.py

@@ -0,0 +1,80 @@
+"""Exception types raised by the Opedd SDK.
+
+All Opedd-specific errors inherit from ``OpeddError``. Each subclass corresponds
+to a backend HTTP status class so callers can catch precisely:
+
+    try:
+        client.content.get(uuid)
+    except OpeddRateLimitError as e:
+        time.sleep(e.retry_after_seconds)
+        retry()
+    except OpeddNotFoundError:
+        log.warning("article gone; skipping")
+    except OpeddError as e:
+        # Catch-all for anything else
+        log.error(e)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class OpeddError(Exception):
+    """Base class for all Opedd SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.body = body
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.status_code:
+            parts.append(f"(HTTP {self.status_code})")
+        if self.request_id:
+            parts.append(f"[request_id={self.request_id}]")
+        return " ".join(parts)
+
+
+class OpeddAuthError(OpeddError):
+    """401/403 — authentication or authorization failure."""
+
+
+class OpeddNotFoundError(OpeddError):
+    """404 — resource not found."""
+
+
+class OpeddValidationError(OpeddError):
+    """400/422 — request body or params malformed."""
+
+
+class OpeddRateLimitError(OpeddError):
+    """429 — rate limit exceeded.
+
+    Attributes:
+        retry_after_seconds: Backend-provided retry hint (None if not surfaced).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_seconds: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class OpeddServerError(OpeddError):
+    """5xx — server error. Usually safe to retry."""

opedd/_http.py

@@ -0,0 +1,143 @@
+"""HTTP client wrapper that handles auth, response unwrapping, and error mapping.
+
+Wire-format contract (mirrors backend convention):
+- Successful response body is flat (no nested ``data.data`` envelope on most endpoints).
+- Error response: ``{"success": false, "error": "..."}`` or ``{"success": false, "error": {"code": "...", "message": "...", "details": {...}}}``.
+- ``X-Opedd-Request-Id`` header carried back for forensic correlation.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from ._exceptions import (
+    OpeddAuthError,
+    OpeddError,
+    OpeddNotFoundError,
+    OpeddRateLimitError,
+    OpeddServerError,
+    OpeddValidationError,
+)
+
+
+class HttpClient:
+    """Thin wrapper around httpx.Client that normalizes auth + errors."""
+
+    def __init__(self, base_url: str, timeout: float = 300.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._client = httpx.Client(timeout=timeout)
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """GET ``base_url + path``, return parsed JSON body. Raises on non-2xx."""
+        resp = self._client.get(
+            f"{self.base_url}{path}",
+            params=params,
+            headers=headers,
+        )
+        return self._parse(resp)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """POST ``base_url + path``, return parsed JSON body. Raises on non-2xx."""
+        resp = self._client.post(
+            f"{self.base_url}{path}",
+            json=json_body,
+            params=params,
+            headers=headers,
+        )
+        return self._parse(resp)
+
+    def stream_ndjson(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> Iterator[dict[str, Any]]:
+        """GET ``base_url + path`` and yield each NDJSON line as a parsed dict.
+
+        Yields per-article rows AND the trailing ``_meta`` row (the caller is
+        expected to recognize ``"_meta" in row`` and act accordingly).
+        """
+        with self._client.stream(
+            "GET",
+            f"{self.base_url}{path}",
+            params=params,
+            headers=headers,
+        ) as resp:
+            if resp.status_code != 200:
+                resp.read()
+                self._raise_for_status(resp)
+            for line in resp.iter_lines():
+                if not line:
+                    continue
+                yield json.loads(line)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _parse(self, resp: httpx.Response) -> dict[str, Any]:
+        if resp.status_code >= 400:
+            self._raise_for_status(resp)
+        try:
+            return resp.json()
+        except json.JSONDecodeError as e:
+            raise OpeddError(
+                f"Non-JSON response: {resp.text[:500]}",
+                status_code=resp.status_code,
+            ) from e
+
+    def _raise_for_status(self, resp: httpx.Response) -> None:
+        """Map backend error response to typed exception."""
+        request_id = resp.headers.get("X-Opedd-Request-Id")
+
+        try:
+            body: dict[str, Any] = resp.json()
+        except (json.JSONDecodeError, ValueError):
+            body = {"error": resp.text[:500] or f"HTTP {resp.status_code}"}
+
+        error_field = body.get("error")
+        if isinstance(error_field, dict):
+            message = error_field.get("message") or error_field.get("code") or f"HTTP {resp.status_code}"
+        elif isinstance(error_field, str):
+            message = error_field
+        else:
+            message = body.get("message") or f"HTTP {resp.status_code}"
+
+        kwargs = {
+            "status_code": resp.status_code,
+            "request_id": request_id,
+            "body": body,
+        }
+
+        if resp.status_code in (401, 403):
+            raise OpeddAuthError(message, **kwargs)
+        if resp.status_code == 404:
+            raise OpeddNotFoundError(message, **kwargs)
+        if resp.status_code in (400, 422):
+            raise OpeddValidationError(message, **kwargs)
+        if resp.status_code == 429:
+            retry_after: int | None = None
+            if isinstance(body.get("retry_after_seconds"), int):
+                retry_after = body["retry_after_seconds"]
+            raise OpeddRateLimitError(message, retry_after_seconds=retry_after, **kwargs)
+        if resp.status_code >= 500:
+            raise OpeddServerError(message, **kwargs)
+        raise OpeddError(message, **kwargs)

opedd/audit.py

@@ -0,0 +1,68 @@
+"""client.audit — per-event audit browse with on-chain inclusion proofs.
+
+Endpoint: ``GET /buyer-audit``
+
+Auth: Supabase JWT (buyer_jwt).
+
+For procurement-defense-grade dossiers, use ``client.compliance.report()`` —
+``/buyer-audit`` is the lighter-weight per-event browse endpoint.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from . import Opedd
+
+
+class AuditNamespace:
+    """Per-event audit access for licensed buyers."""
+
+    def __init__(self, client: Opedd) -> None:
+        self._client = client
+
+    def events(
+        self,
+        *,
+        from_: str | None = None,
+        to: str | None = None,
+        event_type: str | None = None,
+        cursor: str | None = None,
+        limit: int = 100,
+    ) -> dict[str, Any]:
+        """Browse per-event audit rows.
+
+        Args:
+            from_: ISO-8601 timestamp lower bound (inclusive).
+            to: ISO-8601 timestamp upper bound (inclusive).
+            event_type: Filter to a specific event class
+                (e.g., ``"content_access"``, ``"bulk_content_access"``,
+                ``"compliance_report_generated"``).
+            cursor: Opaque cursor for pagination.
+            limit: Max rows per response. Default 100, max bounded by backend.
+
+        Returns:
+            Dict containing ``events[]`` array, each row with ``event_id``,
+            ``event_type``, ``retrieved_at``, ``article`` (when applicable),
+            ``license_terms``, and ``attestation`` block (with ``inclusion_proof``
+            when ``blockchain_status='confirmed'``).
+
+        Window cap: 30 days (vs 90-day cap on ``client.compliance.report()``).
+        Rate limit: 100/min per buyer.
+        """
+        params: dict[str, Any] = {"limit": limit}
+        if from_:
+            params["from"] = from_
+        if to:
+            params["to"] = to
+        if event_type:
+            params["event_type"] = event_type
+        if cursor:
+            params["cursor"] = cursor
+
+        return self._client._http.get(
+            "/buyer-audit",
+            params=params,
+            headers=self._client._jwt_headers(),
+        )

opedd/compliance.py

@@ -0,0 +1,88 @@
+"""client.compliance — procurement-defense compliance dossiers.
+
+Endpoint: ``GET /buyer-compliance-report``
+
+Auth: Supabase JWT (buyer_jwt).
+
+The dossier is the buyer-side procurement-defense artifact. Every retrieval
+within the date range, mapped to license terms, with Tempo Merkle attestation
+hashes inline + on-chain verification URLs. Audit-defensibility under
+EU AI Act Article 53 + CDSM Article 4 + post-Anthropic-settlement scrutiny.
+
+See https://docs.opedd.com/cookbook-compliance-dossier.md for end-to-end usage.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from . import Opedd
+
+
+class ComplianceNamespace:
+    """Procurement-defense compliance dossier access."""
+
+    def __init__(self, client: Opedd) -> None:
+        self._client = client
+
+    def report(
+        self,
+        *,
+        from_: str,
+        to: str,
+        cursor: str | None = None,
+    ) -> dict[str, Any]:
+        """Generate a compliance dossier covering [from_, to].
+
+        Args:
+            from_: ISO-8601 timestamp lower bound (inclusive).
+            to: ISO-8601 timestamp upper bound (inclusive).
+            cursor: Opaque cursor for pagination across windows > the natural
+                response size.
+
+        Returns:
+            Dict with these top-level keys:
+
+            - ``dossier_metadata.buyer`` — buyer identity
+            - ``dossier_metadata.window`` — confirmed window (echo of from/to)
+            - ``dossier_metadata.summary`` — total_retrievals, unique_articles,
+              unique_publishers, event_class_breakdown
+            - ``dossier_metadata.platform`` — schema_version, contract_version
+            - ``dossier_metadata.compliance_framework_anchors`` — boolean flags
+              for EU AI Act Article 53, CDSM Article 4(3), on-chain attestation,
+              TDM reservation; plus ``framework_documentation_url``
+            - ``retrievals[]`` — array of per-row dossier entries (25+ fields each)
+            - ``_meta.audit_event_id`` — references the self-audit row written
+              before the dossier was returned (chain-of-custody)
+            - ``_meta.next_cursor`` — pagination cursor or None
+            - ``_meta.schema_version`` — pinned to ``phase-11-m4``
+            - ``_meta.request_id``
+
+        Window cap: 90 days per request. For annual audits, paginate across 4
+        quarterly windows.
+
+        Rate limit: 30/min per buyer.
+
+        Self-audit invariant: every successful call writes one ``license_events``
+        row with ``event_type='compliance_report_generated'`` BEFORE returning
+        the dossier. The trailing ``_meta.audit_event_id`` references this row.
+
+        Bulk fan-out: ``bulk_content_access`` envelopes expand into N retrieval
+        rows by iterating the envelope's ``metadata.article_ids[]``. All N rows
+        share the same ``on_chain_attestation.merkle_root``
+        (``attestation_granularity: "envelope"``).
+        """
+        params: dict[str, Any] = {
+            "from": from_,
+            "to": to,
+            "format": "json",
+        }
+        if cursor:
+            params["cursor"] = cursor
+
+        return self._client._http.get(
+            "/buyer-compliance-report",
+            params=params,
+            headers=self._client._jwt_headers(),
+        )

opedd/content.py

@@ -0,0 +1,50 @@
+"""client.content — fetch licensed article content.
+
+Endpoint: ``GET /content-delivery``
+
+Auth: buyer_token (sandbox returns truncated content; live returns full).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from . import Opedd
+
+
+class ContentNamespace:
+    """Article retrieval for licensed buyers."""
+
+    def __init__(self, client: Opedd) -> None:
+        self._client = client
+
+    def get(self, article_id: str) -> dict[str, Any]:
+        """Fetch a single article by UUID.
+
+        Args:
+            article_id: Article UUID (from publisher-directory or feed listings).
+
+        Returns:
+            Dict with at least these keys (Phase 11 M2 RAG-extended shape):
+            ``id``, ``title``, ``content``, ``url``, ``published_at``, ``author``,
+            ``language``, ``word_count``, ``content_hash``, ``image_urls``,
+            ``canonical_url``, ``tags``, ``publisher``, ``sandbox`` (bool).
+
+        Note:
+            ``content`` is truncated to 500 chars when ``sandbox=True``.
+            For full content, use a live ``opedd_buyer_live_*`` token.
+
+            NULL on optional fields (author / language / image_urls / canonical_url /
+            tags) means "data unavailable for this article," NOT "explicitly empty."
+            Treat as data-missing; do not interpret as anti-match.
+        """
+        body = self._client._http.get(
+            "/content-delivery",
+            params={"article_id": article_id},
+            headers=self._client._bearer_headers(),
+        )
+        # /content-delivery returns flat shape (no nested data envelope on success)
+        if "data" in body and isinstance(body["data"], dict):
+            return body["data"]
+        return body

opedd/feed.py

@@ -0,0 +1,133 @@
+"""client.feed — paginated + streaming access to licensed catalogs.
+
+Endpoint: ``GET /enterprise-license``
+
+Auth: ``?access_key=eak_*`` query param (no token exchange required).
+
+Two methods:
+- ``list(...)`` — returns a single dict response (up to ``limit`` articles).
+- ``stream_ndjson(...)`` — generator yielding articles one at a time, suitable
+  for streaming bulk-ingest pipelines without holding the full corpus in memory.
+
+The ``?since=`` parameter filters to articles with ``published_at > since`` —
+the buyer-side delta-feed pattern. See
+https://docs.opedd.com/cookbook-delta-feed-polling.md for the polling cookbook.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from . import Opedd
+
+
+class FeedNamespace:
+    """Catalog feeds for licensed buyers."""
+
+    def __init__(self, client: Opedd) -> None:
+        self._client = client
+
+    def list(
+        self,
+        *,
+        since: str | None = None,
+        cursor: str | None = None,
+        limit: int = 200,
+    ) -> dict[str, Any]:
+        """Fetch one page of licensed articles in JSON format.
+
+        Args:
+            since: ISO-8601 timestamp. Returns articles with ``published_at > since``.
+                Optional; omit to get the full licensed catalog.
+            cursor: Opaque cursor from the previous response's ``next_cursor``.
+            limit: Max articles per response. Default 200, max 200 in JSON mode.
+
+        Returns:
+            Dict shape:
+                {
+                    "success": True,
+                    "data": {
+                        "articles": [{...}, ...],
+                        "next_cursor": "opaque-string" | None,
+                        "count": int,
+                        "truncated": bool,
+                    },
+                    "_meta": {"schema_version": "...", "request_id": "..."},
+                }
+
+        Use ``stream_ndjson`` for >200-article bulk ingest.
+        """
+        params: dict[str, Any] = {
+            **self._client._access_key_params(),
+            "format": "json",
+            "limit": limit,
+        }
+        if since:
+            params["since"] = since
+        if cursor:
+            params["cursor"] = cursor
+
+        return self._client._http.get("/enterprise-license", params=params)
+
+    def stream_ndjson(
+        self,
+        *,
+        since: str | None = None,
+        cursor: str | None = None,
+        limit: int = 5000,
+    ) -> Iterator[dict[str, Any]]:
+        """Stream licensed articles as NDJSON, one dict per article.
+
+        Auto-paginates across multiple HTTP requests until ``_meta.truncated == false``.
+        Yields per-article dicts only; the ``_meta`` trailing row is consumed internally.
+
+        Args:
+            since: ISO-8601 timestamp. Returns articles with ``published_at > since``.
+            cursor: Opaque cursor from a previous response's ``next_cursor``. Usually
+                omitted on first call; the generator handles cursor propagation.
+            limit: Max articles per HTTP request. Default 5000 (NDJSON cap).
+                Total returned is unbounded across pagination.
+
+        Yields:
+            One article dict per yield, matching the
+            ``GET /enterprise-license?format=ndjson`` per-line shape.
+
+        Example:
+
+            for article in client.feed.stream_ndjson(since="2026-05-01", limit=5000):
+                train_model.ingest(article["content"], metadata=article)
+
+        Audit trail: every streamed article emits one ``usage_records`` row
+        (sentinel ``stripe_usage_record_id = 'bulk-export:<request_id>:<article_id>'``;
+        analytics-only, not metered-billable). One ``license_events`` envelope row
+        per HTTP call; the trailing ``_meta.audit_event_id`` is logged for forensic
+        correlation but not yielded.
+        """
+        current_cursor = cursor
+
+        while True:
+            params: dict[str, Any] = {
+                **self._client._access_key_params(),
+                "format": "ndjson",
+                "limit": limit,
+            }
+            if since:
+                params["since"] = since
+            if current_cursor:
+                params["cursor"] = current_cursor
+
+            meta: dict[str, Any] | None = None
+            for row in self._client._http.stream_ndjson("/enterprise-license", params=params):
+                if "_meta" in row:
+                    meta = row["_meta"]
+                    continue
+                yield row
+
+            if not meta or not meta.get("truncated"):
+                return
+            next_cursor = meta.get("next_cursor")
+            if not next_cursor:
+                return
+            current_cursor = next_cursor

opedd/licenses.py

@@ -0,0 +1,94 @@
+"""client.licenses — purchase + list enterprise licenses.
+
+Endpoint: ``POST /enterprise-license`` (purchase), ``GET /buyer-account`` (list).
+
+Auth: ``POST`` is unauthenticated (returns a Stripe ``client_secret`` for payment
+completion); ``GET`` requires Supabase JWT.
+
+For the full purchase flow (sandbox → catalog → license → access key →
+bearer token), see https://docs.opedd.com/cookbook-rag-bulk-export.md.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from . import Opedd
+
+
+class LicensesNamespace:
+    """Enterprise license purchase + listing."""
+
+    def __init__(self, client: Opedd) -> None:
+        self._client = client
+
+    def purchase(
+        self,
+        *,
+        publisher_ids: list[str],
+        buyer_email: str,
+        buyer_org: str,
+        billing_type: str = "annual",
+        license_tier: str = "rag",
+        duration_months: int = 12,
+        scope: str = "custom",
+        filter_rules: dict[str, Any] | None = None,
+        buyer_webhook_url: str | None = None,
+    ) -> dict[str, Any]:
+        """Create an enterprise license and return Stripe payment intent.
+
+        Args:
+            publisher_ids: Array of publisher UUIDs. Required for ``scope='custom'``.
+                Ignored for ``scope='platform_wide'`` or ``scope='filtered'``
+                (resolved server-side from ``filter_rules`` / opted-in publishers).
+            buyer_email: Email to deliver the access key (eak_*) after payment.
+            buyer_org: Buyer organization name for billing + audit ledger.
+            billing_type: ``"annual"``, ``"monthly"``, or ``"annual_plus_monthly"``.
+            license_tier: ``"rag"`` (= ``ai_retrieval``), ``"training"``
+                (= ``ai_training``), ``"inference"`` (= ``ai_retrieval``),
+                ``"full_ai"`` (= ``ai_retrieval`` + ``ai_training``).
+            duration_months: Length of license. Default 12.
+            scope: ``"custom"``, ``"platform_wide"``, or ``"filtered"`` (Phase 10).
+            filter_rules: Required when ``scope='filtered'``. See Phase 10 docs
+                for ``excluded_publisher_ids`` / ``direct_license_carveouts`` /
+                ``categories`` / ``max_price_per_event`` schema.
+            buyer_webhook_url: Optional. HMAC-SHA256 signed webhook for
+                ``content.published`` events on covered publishers.
+
+        Returns:
+            Dict with ``enterprise_license_id``, ``stripe_client_secret``,
+            ``checkout_url``.
+
+        After payment completion, the buyer receives an ``eak_*`` access key
+        via email; use ``Opedd.from_access_key()`` to authenticate.
+        """
+        body: dict[str, Any] = {
+            "publisher_ids": publisher_ids,
+            "buyer_email": buyer_email,
+            "buyer_org": buyer_org,
+            "billing_type": billing_type,
+            "license_tier": license_tier,
+            "duration_months": duration_months,
+            "scope": scope,
+        }
+        if filter_rules:
+            body["filter_rules"] = filter_rules
+        if buyer_webhook_url:
+            body["buyer_webhook_url"] = buyer_webhook_url
+
+        return self._client._http.post("/enterprise-license", json_body=body)
+
+    def list(self) -> dict[str, Any]:
+        """List licenses owned by the authenticated buyer (Supabase JWT auth).
+
+        Returns the ``enterprise_buyers`` row + masked API key list. Plaintext
+        access keys are NEVER returned post-issuance; only ``key_prefix`` (12 chars).
+
+        For full mid-lifecycle license details (filter_rules, billing, payouts),
+        consult the buyer portal at opedd.com/buyer.
+        """
+        return self._client._http.get(
+            "/buyer-account",
+            headers=self._client._jwt_headers(),
+        )

opedd-0.1.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: opedd
+Version: 0.1.0
+Summary: Official Python SDK for the Opedd content licensing API (buyer-side)
+Project-URL: Homepage, https://opedd.com
+Project-URL: Documentation, https://docs.opedd.com
+Project-URL: Repository, https://github.com/Opedd/opedd-python
+Project-URL: Issues, https://github.com/Opedd/opedd-python/issues
+Project-URL: Changelog, https://github.com/Opedd/opedd-python/blob/main/CHANGELOG.md
+Author-email: Opedd <support@opedd.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai-licensing,ai-training,content-licensing,opedd,rag
+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.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.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opedd
+
+[![PyPI](https://img.shields.io/pypi/v/opedd.svg)](https://pypi.org/project/opedd/)
+[![Python](https://img.shields.io/pypi/pyversions/opedd.svg)](https://pypi.org/project/opedd/)
+[![License](https://img.shields.io/pypi/l/opedd.svg)](https://github.com/Opedd/opedd-python/blob/main/LICENSE)
+
+Official Python SDK for the [Opedd](https://opedd.com) content licensing API (buyer-side).
+
+Opedd is programmatic licensing infrastructure between AI buyers and publishers — rights, usage tracking, and payment. "Stripe for content licensing."
+
+## Install
+
+```bash
+pip install opedd
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+from opedd import Opedd
+
+client = Opedd(buyer_token="opedd_buyer_live_...")
+
+# Fetch a single licensed article
+article = client.content.get("article-uuid")
+print(article["title"], article["author"], article["word_count"])
+
+# Stream the full licensed catalog as NDJSON
+client = Opedd(access_key="eak_xxx", buyer_email="eng@yourlab.com")
+for row in client.feed.stream_ndjson(limit=5000):
+    train_model.ingest(row["content"], metadata=row)
+
+# Pull a procurement-defense compliance dossier
+client = Opedd(buyer_jwt="eyJhbGc...")
+dossier = client.compliance.report(from_="2026-04-01", to="2026-04-30")
+print(f"Retrievals: {dossier['dossier_metadata']['summary']['total_retrievals']}")
+```
+
+For end-to-end walkthroughs, see the [cookbook](https://docs.opedd.com/cookbook.md).
+
+## Credentials
+
+The SDK supports three credential types depending on which endpoint you call:
+
+| Endpoint | Credential | Construction |
+|---|---|---|
+| `client.content.get(...)` | Bearer buyer token | `Opedd(buyer_token="opedd_buyer_live_...")` |
+| `client.feed.list(...)` / `client.feed.stream_ndjson(...)` | Access key (query param) | `Opedd(access_key="eak_...")` |
+| `client.audit.events(...)` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+| `client.compliance.report(...)` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+| `client.licenses.purchase(...)` | None (returns Stripe `client_secret`) | `Opedd(buyer_token="...")` |
+| `client.licenses.list()` | Supabase JWT | `Opedd(buyer_jwt="eyJhbGc...")` |
+
+Multiple credentials can be supplied at once and the SDK selects the correct one per endpoint.
+
+### Env-var fallbacks
+
+The constructor reads from these env vars when arguments are omitted:
+
+- `OPEDD_BUYER_TOKEN`
+- `OPEDD_BUYER_JWT`
+- `OPEDD_ACCESS_KEY`
+- `OPEDD_BASE_URL` (default `https://api.opedd.com`)
+
+### Exchanging an access key for a bearer token
+
+```python
+client = Opedd.from_access_key(
+    access_key="eak_xyz...",
+    buyer_email="eng@yourlab.com",
+)
+# client.buyer_token is now set; you can call /content-delivery
+```
+
+## API surface
+
+```python
+client.content.get(article_id)
+
+client.feed.list(since=None, cursor=None, limit=200)
+client.feed.stream_ndjson(since=None, cursor=None, limit=5000)  # generator
+
+client.audit.events(from_=None, to=None, event_type=None, cursor=None, limit=100)
+
+client.compliance.report(from_, to, cursor=None)
+
+client.licenses.purchase(publisher_ids, buyer_email, buyer_org, ...)
+client.licenses.list()
+```
+
+All methods return dicts matching the backend wire format. See [docs.opedd.com](https://docs.opedd.com) for full response shapes.
+
+## Error handling
+
+```python
+from opedd import (
+    OpeddError,
+    OpeddAuthError,
+    OpeddNotFoundError,
+    OpeddRateLimitError,
+    OpeddServerError,
+    OpeddValidationError,
+)
+
+try:
+    article = client.content.get(uuid)
+except OpeddRateLimitError as e:
+    time.sleep(e.retry_after_seconds or 60)
+    retry()
+except OpeddAuthError:
+    refresh_token()
+except OpeddNotFoundError:
+    log.warning("article gone; skipping")
+except OpeddError as e:
+    log.error(f"{e} request_id={e.request_id}")
+```
+
+Every error carries `status_code`, `request_id`, and `body` for forensic correlation.
+
+## Schema version pinning
+
+The SDK ships pinned to backend schema version **`phase-11-m4`** (`opedd.__schema_version__`).
+
+When the backend bumps `X-Opedd-Schema-Version`, the SDK ships a follow-up release within 1 sprint per the [schema-pin invariant](https://github.com/Opedd/opedd-backend/blob/main/INVARIANTS.md#python-sdk--mcp-server-pin-to-backend-x-opedd-schema-version-phase-11-m6).
+
+Additive field bumps are absorbed transparently (dict pass-through). Subtractive or rename bumps require an SDK release; ensure your `requirements.txt` pins to a tested version.
+
+## Tests
+
+Two test suites:
+
+### Unit tests (run in CI, no live API calls)
+
+```bash
+pip install -e ".[dev]"
+pytest tests/test_unit.py
+```
+
+29+ unit tests covering: client construction, credential precedence, env-var fallback, auth-header building per credential type, HTTP error mapping (401/403/404/400/422/429/5xx), NDJSON streaming + cursor pagination, all 5 namespaces' request shapes.
+
+### Integration tests (manual, before each release)
+
+```bash
+export OPEDD_BUYER_JWT="..."     # for /buyer-audit + /buyer-compliance-report
+export OPEDD_BUYER_TOKEN="..."   # for /content-delivery
+export OPEDD_ACCESS_KEY="..."    # for /enterprise-license GET feed
+pytest --integration
+```
+
+Live tests against `api.opedd.com`. Read-only. Skipped by default (require `--integration` flag).
+
+Per [release discipline](./RELEASE.md), integration tests must pass locally before any version tag is pushed. CI does NOT run integration tests — per institutional risk discipline, autonomous CI runs against production state can pollute `usage_records`, distort metered-publisher payouts, and fire production API calls at scale.
+
+## Development
+
+```bash
+git clone https://github.com/Opedd/opedd-python.git
+cd opedd-python
+pip install -e ".[dev]"
+pytest tests/test_unit.py            # unit only (default)
+pytest --integration                  # unit + integration (requires env vars)
+ruff check src/ tests/                # lint
+mypy src/                             # type-check
+```
+
+## Contributing
+
+Issues and PRs welcome at [github.com/Opedd/opedd-python](https://github.com/Opedd/opedd-python). For broader questions about Opedd as a platform, email [support@opedd.com](mailto:support@opedd.com).
+
+## License
+
+[MIT](./LICENSE)
+
+## See also
+
+- [docs.opedd.com](https://docs.opedd.com) — full API reference + cookbook
+- [opedd-mcp](https://github.com/Opedd/opedd-mcp) — Model Context Protocol server for Claude Desktop / Cursor
+- [opedd-backend](https://github.com/Opedd/opedd-backend) — backend implementation (private)

opedd-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+opedd/__init__.py,sha256=pyN7WVjuW4di_8bhJdz9snqu3jvhyLfPe1xwlrLaw4w,6333
+opedd/_exceptions.py,sha256=nT7gY-j1wXaMnoC_JKjvfBx0RUYOfrCCsId6nFnALUM,2052
+opedd/_http.py,sha256=COCXOYeEabd_R0BA2YRdUR8LYy0vSRkXKZDjvFqSK5Q,4838
+opedd/audit.py,sha256=qAU__LFJ8CYIW9Tw4uVZktplIzR9gNu7lqCBROp2FFQ,2150
+opedd/compliance.py,sha256=xk7OVvdPW51Uh_49uxQ78JywFWRWWrlKNYUV5xETM2A,3333
+opedd/content.py,sha256=WxeVaOpq5cQKDjQY_HdHR21kEdKc8Hahz64jYZ0V4y4,1754
+opedd/feed.py,sha256=fPs8O8FsadBu_UWRj8AyOPhAbclA_ZNb9RRJzQhVOnE,4747
+opedd/licenses.py,sha256=rNQ7S3Cy1c8sURvNl07vaf0Ui_fPDRXzFBKTifIMSww,3794
+opedd-0.1.0.dist-info/METADATA,sha256=tje7FPxqcEE8uwuVka56RrZfCuTxmcUgLmEK2nRjlno,7773
+opedd-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+opedd-0.1.0.dist-info/licenses/LICENSE,sha256=IbYpWsfu73IMY9ZCby-TdGlVibF7BIeNyeyhQwSVT5w,1062
+opedd-0.1.0.dist-info/RECORD,,

opedd-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

opedd-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Opedd
+
+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.