periplus-python-sdk 0.9.0__py3-none-any.whl → 0.11.0__py3-none-any.whl

periplus_python_sdk-0.11.0.dist-info/METADATA

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: periplus-python-sdk
+Version: 0.11.0
+Summary: Typed Periplus platform client with SQL and notebook integration
+License-Expression: AGPL-3.0-only
+Project-URL: Repository, https://github.com/elei-io/periplus
+Project-URL: Issues, https://github.com/elei-io/periplus/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: licensing/LICENSE
+License-File: licensing/NOTICE
+License-File: licensing/README.md
+License-File: licensing/THIRD_PARTY_NOTICES.md
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: sqlalchemy<3,>=2.0
+Provides-Extra: notebook
+Requires-Dist: marimo[sql]>=0.24.1; extra == "notebook"
+Dynamic: license-file
+
+# Periplus Python SDK
+
+Typed organization operations and SQL access through the Periplus HTTP API.
+The 0.11.0 platform interface requires the matching API release. It includes
+the source-snapshot metadata introduced in 0.10.0 alongside customer operations.
+Install from PyPI:
+
+```sh
+python -m pip install --upgrade periplus-python-sdk
+```
+
+```python
+from periplus_sdk import Client
+
+with Client("https://api.periplus.dev", api_key="ppl_…") as client:
+    result = client.execute(
+        "SELECT capture_id, url FROM public_v1.captures LIMIT ?", [10]
+    )
+    print(result.columns, result.rows)
+```
+
+The default origin is `https://api.periplus.dev`. Use `PERIPLUS_API_URL` to override it and `PERIPLUS_API_KEY` to
+supply your personal organization API key. A key with `organization:sql:exec`
+is required. Database usernames/passwords and anonymous access are not supported.
+Use HTTPS outside loopback development. Connect directly to the API origin,
+not the public marketing site.
+
+Version 0.9.0 requires personal API keys instead of database credentials. Create
+a key in the app's Settings → My API keys. It inherits your current access in
+that organization; SQL requires your membership to have `organization:sql:exec`.
+For local development, install `./clients/periplus-python-sdk` from the repository
+root and connect to `http://localhost:8000`.
+
+`AsyncClient` accepts the same options. `prepare` explains a SELECT; `execute`
+returns typed columns/rows for read-only queries. `schema()` returns
+visible tables, column types/descriptions and helper documentation. All SQL uses
+`POST /api/v1/sql`; schema discovery uses `GET /api/v1/schema`. ClickHouse enforces
+permissions. The SDK never retries automatically, including failed queries.
+
+Public HTML joins use `parse_id` and `node_index`; `document_id` identifies exact
+raw bytes. Public shorthand uses the `public_v1` schema.
+
+In 0.10.0, `result.source_snapshot` is a typed `SourceSnapshot` containing
+`layout_id` (UUID) and `publication_epoch` (integer), or `None` when no build-bound
+public corpus was read. Buffered, asynchronous, streamed and DB-API results share
+this contract. Compare both fields, not just the epoch. The identity describes
+the public corpus inputs, not any native staff/external inputs. It does not retain
+the data or request historical reads. This replaces the old nullable integer field;
+use this SDK version with the corresponding API release.
+
+For notebook/SQLAlchemy integration:
+
+```python
+from periplus_sdk import sql_api
+from sqlalchemy import text
+
+engine = sql_api.create_engine(base_url="http://localhost:8000", api_key="ppl_…")
+with engine.connect() as connection:
+    print(connection.execute(text("SELECT url FROM public_v1.captures LIMIT 5")).all())
+engine.dispose()
+```
+
+Marimo discovers accessible tables, views, typed columns and comments through the
+schema endpoint. Reflection does not execute SQL. One SQLAlchemy Inspector caches
+its metadata; call `inspector.clear_cache()` to refresh it. Missing metadata raises
+an error rather than presenting an apparently complete empty schema.
+
+The DB-API connection advertises the ClickHouse dialect and converts native
+nullable integer, decimal, date and datetime types. Nested types retain JSON wire
+values. Writes are not exposed through the query API. There are no client
+transactions; each statement is independent.
+Streaming cursors expose incomplete/truncated results explicitly; configure
+`allow_partial` only when partial results suit the application.
+
+See [the public schema](../../docs/SCHEMA.md) and [query boundary](../../docs/QUERY.md).
+
+## Organization resources
+
+The same key selects your organization and inherits your live membership access.
+`Client` and `AsyncClient` expose the same namespaces:
+
+| Namespace | Operations |
+| --- | --- |
+| `identity`, `availability` | `get` |
+| `discovery` | `create`, `get`, `list`, `iter`, `arrivals`, `cancel` |
+| `retention`, `monitoring` | `create`, `preview`, `activate`, `get`, `list`, `iter`, `members`, `update`, `pause`, `resume`, `delete` |
+| `saved_queries` | `create`, `get`, `list`, `iter`, `rename`, `delete` |
+| `members` | `list`, `update_role`, `remove` |
+| `invitations` | `list`, `create`, `cancel` |
+| `api_keys` | `create`, `list`, `iter`, `revoke` |
+| `usage` | `get` |
+| `query_history` | `list`, `iter`, `get`, `summary` |
+| `audit` | `list`, `iter` |
+
+```python
+from periplus_sdk import Client
+
+with Client() as client:
+    preview = client.retention.preview(
+        name="Research sources", days=90,
+        sql="SELECT capture_id FROM captures WHERE domain(url) = ?",
+        parameters=["example.com"],
+    )
+    print(preview.id, preview.capture_count, preview.sample)
+    # Review the selection before calling:
+    # active = client.retention.activate(preview)
+```
+
+SQL previews persist inactive, frozen selections; activation never reruns SQL.
+Explicit IDs/URLs passed to `create` activate immediately. Monitoring URLs must
+already be known in the corpus. Use `members` and its `next_cursor` for complete
+membership: policy detail contains a sample. Updates/deletion accept a fetched
+`Policy` or an ID with `expected_version`; conflicts are never retried.
+
+Paginated lists return `Page[T]` (`items`, `next_cursor`). Pass cursors unchanged
+or use `iter()`; membership/invitation lists are bounded snapshots instead.
+Offset-based lists can shift during concurrent changes. Query history and arrivals
+use keyset cursors. UTC usage ranges have an exclusive end date, at most 93 days.
+Query history is best-effort and expires after 30 days; it is not a billing ledger.
+
+`ApiError` includes HTTP status, code, optional request ID, validation fields and
+Retry-After seconds. `TransportError` means the outcome of a write can be unknown.
+Keep creation IDs to reconcile; never blindly retry. Key creation is one-time:
+`created.secret.get_secret_value()` reveals the secret and must only be used for
+secure storage. Its ordinary representation is masked. Lost secrets cannot be
+recovered.
+
+For async streaming, use `async with await client.stream(sql) as stream` followed
+by `async for batch in stream`. Streams validate completion and close on early
+exit, errors, and cancellation. No threads or background polling are introduced.

periplus_python_sdk-0.11.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+periplus_python_sdk-0.11.0.dist-info/licenses/licensing/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+periplus_python_sdk-0.11.0.dist-info/licenses/licensing/NOTICE,sha256=W4W3pzZe-a0ebw4MxgWVmFGj7NSGL1qj8hFx4YG9iF0,105
+periplus_python_sdk-0.11.0.dist-info/licenses/licensing/README.md,sha256=NABTC2wm2Y9iRNMnlMeyVMA2dsAw7XRmCrsV1B2TQdk,1996
+periplus_python_sdk-0.11.0.dist-info/licenses/licensing/THIRD_PARTY_NOTICES.md,sha256=cuA1RaKPfcq5bOMFHTLiTaxjaySKlOqoU5WhHqV8h4U,9643
+periplus_sdk/__init__.py,sha256=awbiP1tubzF5wIt8ffEb82KuuAs8Y2-5kydvZOYncjs,821
+periplus_sdk/async_resources.py,sha256=ao6X3UhBwfxdBo4NRQYxTws4uFSQyjHb_qJ7e2lcURs,15375
+periplus_sdk/async_stream.py,sha256=O5hO_w_-ooQuDV1fOZRX4Qei1-w7Wri8eIlsn3yCpGQ,4592
+periplus_sdk/client.py,sha256=OMIeZnw241I23timweqMYvvv-vGfMeMje3ksiKvWftU,13637
+periplus_sdk/dbapi.py,sha256=dkJA-DkrMtcgMGjLQ5Vv8-pb6riRrAaG4Yqrn22uRZY,12064
+periplus_sdk/errors.py,sha256=nnbmRzEu1GEFGeKNsLqEo6pHCFu0oFy__5t-yBLO2hw,965
+periplus_sdk/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+periplus_sdk/resources.py,sha256=i4JCemsLFUdaH_54JRIl6HVMrW8UIVA7q-AaBFXe-uA,14820
+periplus_sdk/resources_types.py,sha256=Wy6TbNSv5pEG6_gbaE4paZTJyQB-IA3Zbgq8Ns9ZV6s,6135
+periplus_sdk/selection.py,sha256=9MdqJF817wuMXSNmeFKoxCzL_tkh7ZmNI2Aie5AKFRo,1343
+periplus_sdk/sql_api.py,sha256=uUWdwMRSZFMNXXy3-yLozcuT6WluvT6BTjYDB0lNrAU,1917
+periplus_sdk/sqlalchemy.py,sha256=XE_OzdDh9OZ8goWWRoKlBzp7Q0FM-eS9-hjH7Ofzy-E,6292
+periplus_sdk/stream.py,sha256=6Ytb6FkP3Y5C4sDA_SDdU0MJHBQdgHde1lNM6YxHdIQ,5560
+periplus_sdk/types.py,sha256=TSaQRjN5vng_yV4hjZV03s5sU_RHL874qJe40-Hb1KQ,3644
+periplus_python_sdk-0.11.0.dist-info/METADATA,sha256=V4EGzlbbSWPNz-8NKujkkxfnS_iPbFkNIY6LXoG-P8g,6957
+periplus_python_sdk-0.11.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+periplus_python_sdk-0.11.0.dist-info/entry_points.txt,sha256=Pr14L_7AhLinq-4qDxB4awFVubrvR1BEfkaFVRpdCbU,73
+periplus_python_sdk-0.11.0.dist-info/top_level.txt,sha256=o41t5TzwgoxzSmbKoP6olWW1FyEAGWVYTjeoKadBK40,13
+periplus_python_sdk-0.11.0.dist-info/RECORD,,

periplus_sdk/__init__.py

@@ -1,9 +1,11 @@
-"""Read-only Python clients for the public Periplus query API."""
+"""Typed organization operations and read-only SQL through the Periplus API."""
 from .dbapi import connect
 from .client import AsyncClient, Client
 from .errors import ApiError, ConfigurationError, PeriplusError, ResponseError, TransportError
-from .types import Diagnostic, PreparedQuery, QueryHelper, QueryHelpers, QueryResult
+from .types import Diagnostic, PreparedQuery, QueryHelper, QueryHelpers, QueryResult, SourceSnapshot
+from .resources_types import Page, Policy, Discovery, Member, Invitation, ApiKey, CreatedApiKey, Identity, Usage
 
 __all__ = ["connect", "AsyncClient", "Client", "ApiError", "ConfigurationError", "PeriplusError",
            "ResponseError", "TransportError", "Diagnostic", "PreparedQuery", "QueryHelper",
-           "QueryHelpers", "QueryResult"]
+           "QueryHelpers", "QueryResult", "Page", "Policy", "Discovery", "Member", "Invitation",
+           "ApiKey", "CreatedApiKey", "Identity", "Usage", "SourceSnapshot"]

periplus_sdk/async_resources.py

@@ -0,0 +1,298 @@
+"""Async customer operations; the same contract as resources.py."""
+from __future__ import annotations
+from collections.abc import AsyncIterator, Sequence
+from datetime import date
+from typing import Generic, Literal, TypeVar
+from urllib.parse import quote
+from uuid import UUID, uuid4
+
+from pydantic import JsonValue
+
+from .resources_types import (
+    ApiKey, ArrivalsPage, AuditEvent, Availability, CreatedApiKey, Discovery,
+    Identity, Invitation, Member, Members, Page, Policy, PolicyMember,
+    QueryExecution, QueryUsage, Role, SavedQuery, Usage,
+)
+
+
+def path_id(value: str | UUID) -> str:
+    return quote(str(value), safe="")
+
+
+def page_offset(cursor: str | None) -> int:
+    if cursor is None:
+        return 0
+    if not cursor.isascii() or not cursor.isdecimal():
+        raise ValueError("Invalid page cursor")
+    return int(cursor)
+
+
+def page_size(limit: int) -> int:
+    if not 1 <= limit <= 100:
+        raise ValueError("Page size must be between 1 and 100")
+    return limit
+
+
+def policy_ref(policy: Policy | str | UUID, expected_version: int | None, kind: str):
+    if isinstance(policy, Policy):
+        if policy.kind != kind:
+            raise ValueError("Policy belongs to a different resource")
+        return policy.id, policy.version if expected_version is None else expected_version
+    if expected_version is None:
+        raise ValueError("An ID requires expected_version; fetch the policy before changing it")
+    return policy, expected_version
+
+
+def member_ref(member: Member | str, expected_role: Role | None):
+    if isinstance(member, Member):
+        return member.id, expected_role if expected_role is not None else member.role
+    if expected_role is None:
+        raise ValueError("An ID requires expected_role; fetch membership before changing it")
+    return member, expected_role
+
+
+class Resource:
+    def __init__(self, client):
+        self._client = client
+
+T = TypeVar("T")
+
+
+class PagedResource(Resource, Generic[T]):
+    async def iter(self, **filters) -> AsyncIterator[T]:
+        """Lazily iterate list pages. No snapshot is implied while resources change."""
+        cursor = filters.pop("cursor", None)
+        while True:
+            page = await self.list(cursor=cursor, **filters)
+            for item in page.items:
+                yield item
+            if page.next_cursor is None:
+                return
+            if page.next_cursor == cursor:
+                raise ValueError("Server returned a non-advancing cursor")
+            cursor = page.next_cursor
+
+
+class IdentityResource(Resource):
+    async def get(self) -> Identity:
+        return await self._client._resource_request("GET", "identity", Identity)
+
+
+class AvailabilityResource(Resource):
+    async def get(self) -> Availability:
+        return await self._client._resource_request("GET", "access", Availability)
+
+
+class DiscoveryResource(PagedResource[Discovery]):
+    async def select_urls(self, sql: str, parameters: Sequence[JsonValue] = ()) -> list[str]:
+        """Resolve a complete starting-page selection without creating discovery."""
+        from .selection import starting_urls
+        return starting_urls(await self._client.execute(sql, parameters))
+
+    async def create(self, *, urls: Sequence[str], link_depth: int = 2, page_limit: int = 10_000,
+               follow_external_links: bool = False, allowed_hosts: Sequence[str] = (),
+               excluded_hosts: Sequence[str] = (), allowed_paths: Sequence[str] = (),
+               excluded_paths: Sequence[str] = (), retain_days: int | None = None,
+               id: UUID | None = None) -> Discovery:
+        return await self._client._resource_request("POST", "discoveries", Discovery, json={
+            "id": str(id or uuid4()), "specification": {
+                "seed_urls": list(urls), "max_depth": link_depth, "page_limit": page_limit,
+                "follow_scope": "linked_sites" if follow_external_links else "starting_sites",
+                "allowed_hosts": list(allowed_hosts), "excluded_hosts": list(excluded_hosts),
+                "allowed_paths": list(allowed_paths), "excluded_paths": list(excluded_paths),
+                "retain_days": retain_days}})
+
+    async def list(self, *, cursor: str | None = None, limit: int = 20,
+             status: Literal["active", "paused", "settled"] | None = None) -> Page[Discovery]:
+        return await self._client._resource_request("GET", "discoveries", Page[Discovery],
+            params={"offset": page_offset(cursor), "limit": page_size(limit), "status": status})
+
+    async def get(self, id: str | UUID) -> Discovery:
+        return await self._client._resource_request("GET", f"discoveries/{path_id(id)}", Discovery)
+
+    async def cancel(self, id: str | UUID) -> Discovery:
+        return await self._client._resource_request("POST", f"discoveries/{path_id(id)}/actions",
+            Discovery, json={"action": "cancel"})
+
+    async def arrivals(self, id: str | UUID, *, cursor: str | None = None, limit: int = 20) -> ArrivalsPage:
+        return await self._client._resource_request("GET", f"discoveries/{path_id(id)}/arrivals",
+            ArrivalsPage, params={"cursor": cursor, "limit": page_size(limit)})
+
+
+class PolicyResource(PagedResource[Policy]):
+    kind: Literal["retention", "refresh"]
+
+    async def list(self, *, cursor: str | None = None, limit: int = 20,
+             include_drafts: bool = True) -> Page[Policy]:
+        return await self._client._resource_request("GET", "page-policies", Page[Policy],
+            params={"kind": self.kind, "offset": page_offset(cursor), "limit": page_size(limit),
+                    "include_drafts": include_drafts})
+
+    async def get(self, id: str | UUID) -> Policy:
+        return await self._client._resource_request("GET", f"page-policies/{path_id(id)}", Policy,
+            params={"kind": self.kind, "members_limit": 20})
+
+    async def members(self, id: str | UUID, *, cursor: str | None = None, limit: int = 100) -> Page[PolicyMember]:
+        return await self._client._resource_request("GET", f"page-policies/{path_id(id)}/members",
+            Page[PolicyMember], params={"kind": self.kind, "offset": page_offset(cursor), "limit": page_size(limit)})
+
+    async def _create(self, name, days, selection, retain_days, id) -> Policy:
+        return await self._client._resource_request("POST", "page-policies", Policy, json={
+            "id": str(id or uuid4()), "kind": self.kind, "name": name, "days": days,
+            "selection": selection, "retain_days": retain_days})
+
+    async def _action(self, policy, action, expected_version) -> Policy:
+        id, version = policy_ref(policy, expected_version, self.kind)
+        return await self._client._resource_request("POST", f"page-policies/{path_id(id)}/actions", Policy,
+            params={"kind": self.kind}, json={"action": action, "expected_version": version})
+
+    async def activate(self, policy: Policy | str | UUID, *, expected_version: int | None = None) -> Policy:
+        """Activate the persisted SQL selection without executing SQL again."""
+        return await self._action(policy, "activate", expected_version)
+
+    async def pause(self, policy: Policy | str | UUID, *, expected_version: int | None = None) -> Policy:
+        return await self._action(policy, "pause", expected_version)
+
+    async def resume(self, policy: Policy | str | UUID, *, expected_version: int | None = None) -> Policy:
+        """Resume without restarting the original retention period."""
+        return await self._action(policy, "resume", expected_version)
+
+    async def delete(self, policy: Policy | str | UUID, *, expected_version: int | None = None) -> None:
+        id, version = policy_ref(policy, expected_version, self.kind)
+        return await self._client._resource_request("DELETE", f"page-policies/{path_id(id)}", None,
+            params={"kind": self.kind, "expected_version": version})
+
+    async def _update(self, policy, expected_version, fields) -> Policy:
+        id, version = policy_ref(policy, expected_version, self.kind)
+        return await self._client._resource_request("PATCH", f"page-policies/{path_id(id)}", Policy,
+            params={"kind": self.kind}, json={"expected_version": version, **fields})
+
+
+class RetentionResource(PolicyResource):
+    kind = "retention"
+
+    async def create(self, *, name: str, capture_ids: Sequence[str | UUID], days: int,
+               id: UUID | None = None) -> Policy:
+        """Protect explicit capture IDs immediately."""
+        return await self._create(name, days, {"capture_ids": [str(id) for id in capture_ids]}, None, id)
+
+    async def preview(self, *, name: str, sql: str, days: int,
+                parameters: Sequence[JsonValue] = (), id: UUID | None = None) -> Policy:
+        """Save an inactive, frozen SQL selection. Call activate separately."""
+        return await self._create(name, days, {"sql": sql, "parameters": list(parameters)}, None, id)
+
+    async def update(self, policy: Policy | str | UUID, *, name: str | None = None,
+               days: int | None = None, expected_version: int | None = None) -> Policy:
+        return await self._update(policy, expected_version,
+            {key: value for key, value in {"name": name, "days": days}.items() if value is not None})
+
+
+class MonitoringResource(PolicyResource):
+    kind = "refresh"
+
+    async def create(self, *, name: str, urls: Sequence[str], interval_days: int,
+               retain_days: int | None = None, id: UUID | None = None) -> Policy:
+        """Monitor exact known corpus URLs immediately; does not follow links."""
+        return await self._create(name, interval_days, {"urls": list(urls)}, retain_days, id)
+
+    async def preview(self, *, name: str, sql: str, interval_days: int,
+                parameters: Sequence[JsonValue] = (), retain_days: int | None = None,
+                id: UUID | None = None) -> Policy:
+        return await self._create(name, interval_days, {"sql": sql, "parameters": list(parameters)}, retain_days, id)
+
+    async def update(self, policy: Policy | str | UUID, *, name: str | None = None,
+               interval_days: int | None = None, retain_days: int | None = None,
+               clear_retention: bool = False, expected_version: int | None = None) -> Policy:
+        if clear_retention and retain_days is not None:
+            raise ValueError("Choose retain_days or clear_retention, not both")
+        fields = {key: value for key, value in {"name": name, "days": interval_days,
+                  "retain_days": retain_days}.items() if value is not None}
+        if clear_retention:
+            fields["retain_days"] = None
+        return await self._update(policy, expected_version, fields)
+
+
+class SavedQueriesResource(PagedResource[SavedQuery]):
+    async def list(self, *, search: str = "", cursor: str | None = None) -> Page[SavedQuery]:
+        return await self._client._resource_request("GET", "saved-queries", Page[SavedQuery],
+            params={"search": search, "offset": page_offset(cursor)})
+
+    async def get(self, id: str | UUID) -> SavedQuery:
+        return await self._client._resource_request("GET", f"saved-queries/{path_id(id)}", SavedQuery)
+
+    async def create(self, *, name: str, sql: str, id: UUID | None = None) -> SavedQuery:
+        return await self._client._resource_request("POST", "saved-queries", SavedQuery,
+            json={"id": str(id or uuid4()), "name": name, "sql": sql})
+
+    async def rename(self, id: str | UUID, *, name: str) -> SavedQuery:
+        return await self._client._resource_request("PATCH", f"saved-queries/{path_id(id)}", SavedQuery, json={"name": name})
+
+    async def delete(self, id: str | UUID) -> None:
+        return await self._client._resource_request("DELETE", f"saved-queries/{path_id(id)}", None)
+
+
+class MembersResource(Resource):
+    async def list(self) -> Members:
+        """Organization membership and invitation snapshot, including owner guards."""
+        return await self._client._resource_request("GET", "members", Members)
+
+    async def update_role(self, member: Member | str, *, role: Role, expected_role: Role | None = None) -> None:
+        member_id, current_role = member_ref(member, expected_role)
+        return await self._client._resource_request("PUT", f"members/{path_id(member_id)}", None,
+            json={"action": role, "expected_role": current_role})
+
+    async def remove(self, member: Member | str, *, expected_role: Role | None = None) -> None:
+        member_id, current_role = member_ref(member, expected_role)
+        return await self._client._resource_request("PUT", f"members/{path_id(member_id)}", None,
+            json={"action": "remove", "expected_role": current_role})
+
+
+class InvitationsResource(Resource):
+    async def list(self) -> list[Invitation]:
+        return (await self._client._resource_request("GET", "members", Members)).invitations
+
+    async def create(self, *, email: str, role: Role = "member") -> None:
+        return await self._client._resource_request("POST", "members/invitations", None,
+            json={"email": email, "role": role})
+
+    async def cancel(self, id: str) -> None:
+        return await self._client._resource_request("DELETE", f"members/invitations/{path_id(id)}", None)
+
+
+class ApiKeysResource(PagedResource[ApiKey]):
+    async def list(self, *, cursor: str | None = None, limit: int = 20) -> Page[ApiKey]:
+        return await self._client._resource_request("GET", "api-keys", Page[ApiKey],
+            params={"offset": page_offset(cursor), "limit": page_size(limit)})
+
+    async def create(self, *, name: str, id: UUID | None = None) -> CreatedApiKey:
+        """Secret is returned once; access via secret.get_secret_value()."""
+        return await self._client._resource_request("POST", "api-keys", CreatedApiKey,
+            json={"id": str(id or uuid4()), "name": name})
+
+    async def revoke(self, id: str | UUID) -> None:
+        return await self._client._resource_request("DELETE", f"api-keys/{path_id(id)}", None)
+
+
+class UsageResource(Resource):
+    async def get(self, *, start: date | None = None, end: date | None = None) -> Usage:
+        """UTC dates; end is exclusive. Usage is consumption, not an invoice."""
+        return await self._client._resource_request("GET", "usage", Usage, params={"start": start, "end": end})
+
+
+class QueryHistoryResource(PagedResource[QueryExecution]):
+    async def summary(self, *, start: date | None = None, end: date | None = None) -> QueryUsage:
+        return await self._client._resource_request("GET", "usage/queries", QueryUsage, params={"start": start, "end": end})
+
+    async def list(self, *, cursor: str | None = None, limit: int = 50) -> Page[QueryExecution]:
+        return await self._client._resource_request("GET", "usage/query-history", Page[QueryExecution],
+            params={"cursor": cursor, "limit": page_size(limit)})
+
+    async def get(self, id: str | UUID) -> QueryExecution:
+        return await self._client._resource_request("GET", f"usage/queries/{path_id(id)}", QueryExecution)
+
+
+class AuditResource(PagedResource[AuditEvent]):
+    async def list(self, *, cursor: str | None = None, action: str | None = None,
+             outcome: str | None = None) -> Page[AuditEvent]:
+        return await self._client._resource_request("GET", "audit", Page[AuditEvent],
+            params={"offset": page_offset(cursor), "action": action, "outcome": outcome})

periplus_sdk/async_stream.py

@@ -0,0 +1,104 @@
+"""Asynchronous incremental query frames with explicit completion checks."""
+import json
+import httpx
+from pydantic import JsonValue, ValidationError
+from .errors import ApiError, ResponseError, TransportError
+from .stream import MEDIA_TYPE, StreamResult, Rows, Completion
+
+
+class AsyncQueryStream:
+    """One response, consumed a batch at a time. Close early to cancel delivery."""
+
+    @classmethod
+    async def open(cls, response: httpx.Response, *, allow_partial: bool = False):
+        self = cls()
+        self.response = response
+        self.allow_partial = allow_partial
+        self.closed = False
+        self._count = 0
+        self._lines = response.aiter_lines()
+        try:
+            if response.headers.get("content-type", "").split(";")[0] != MEDIA_TYPE:
+                raise ResponseError("Expected a streaming query response.")
+            frame = await self._frame()
+            if frame.get("type") != "metadata":
+                raise ResponseError("Query stream is missing metadata.")
+            self.result = StreamResult.model_validate(frame)
+            if len(self.result.columns) != len(self.result.types):
+                raise ResponseError("Query columns and types have inconsistent widths.")
+        except ValidationError:
+            await self.aclose()
+            raise ResponseError("Invalid query stream metadata.") from None
+        except BaseException:
+            await self.aclose()
+            raise
+
+        return self
+
+    async def _frame(self):
+        try:
+            async for line in self._lines:
+                if not line.strip():
+                    continue
+                frame = json.loads(line)
+                if not isinstance(frame, dict):
+                    raise ResponseError("Invalid query stream frame.")
+                if frame.get("type") == "error":
+                    raise ApiError(frame.get("detail", "Query stream failed."),
+                                   status_code=frame.get("status", 500), code=frame.get("code"))
+                return frame
+        except httpx.RequestError:
+            raise TransportError("Query stream interrupted; the result is incomplete.") from None
+        except ValueError:
+            raise ResponseError("Invalid query stream frame.") from None
+        raise ResponseError("Query stream ended without completion; the result is incomplete.")
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self) -> list[list[JsonValue]]:
+        if self.closed:
+            if not self.result.complete:
+                raise ResponseError("Query stream closed before completion; the result is incomplete.")
+            if self.result.truncated and not self.allow_partial:
+                raise ResponseError("Query result exceeded its budget and is incomplete.")
+            raise StopAsyncIteration
+        try:
+            frame = await self._frame()
+            if frame.get("type") == "rows":
+                rows = Rows.model_validate(frame).rows
+                if any(len(row) != len(self.result.columns) for row in rows):
+                    raise ResponseError("Query row has an inconsistent width.")
+                self._count += len(rows)
+                return rows
+            completion = Completion.model_validate(frame)
+            if completion.row_count != self._count:
+                raise ResponseError("Query completion row count does not match delivered rows.")
+            for name, value in completion.model_dump(exclude={"type"}).items():
+                setattr(self.result, name, value)
+            self.result.complete = True
+            await self.aclose()
+            if completion.truncated and not self.allow_partial:
+                budget = completion.truncation_reason
+                limit = self.result.limits.get(budget, "unknown")
+                raise ApiError(f"Query result is incomplete: {budget} ({limit}) reached after {self._count} rows. "
+                               "Narrow the query or ask the administrator to increase this budget.",
+                               status_code=422, code="result_limit")
+            raise StopAsyncIteration
+        except ValidationError:
+            await self.aclose()
+            raise ResponseError("Invalid query stream frame.") from None
+        except BaseException:
+            await self.aclose()
+            raise
+
+    async def aclose(self):
+        if not self.closed:
+            self.closed = True
+            await self.response.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.aclose()