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

periplus_python_sdk-0.12.1.dist-info/METADATA

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: periplus-python-sdk
+Version: 0.12.1
+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.12.0 platform interface requires the matching API release. It replaces the
+discovery, retention and monitoring namespaces with captures, crawls, pins and
+schedules, and includes the source-snapshot metadata introduced in 0.10.0.
+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 Developer key in the app's Access → SDK & API. 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. Buffered SQL reads retry HTTP 502, 503 and 504 up to twice with bounded
+backoff starting in 0.12.1. Set `sql_retries=0` to disable this, or choose up to three retries. Each
+attempt may observe a newer corpus snapshot. Mutations, transport failures and
+streamed queries are not retried automatically.
+
+Public HTML joins use `capture_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
+
+A Developer key selects your organization and uses your live membership access. Agent keys authenticate only to the hosted MCP endpoint, not this SDK.
+`Client` and `AsyncClient` expose the same namespaces:
+
+| Namespace | Operations |
+| --- | --- |
+| `identity`, `availability` | `get` |
+| `captures`, `crawls` | `create`, `get`, `list`, `iter`, `pages`, `cancel` |
+| `pins` | `create`, `get`, `list`, `iter`, `captures`, `update`, `delete` |
+| `schedules` | `create`, `get`, `list`, `iter`, `pages`, `captures`, `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` |
+
+Choose the resource by what you know and how long you need it:
+
+| Resource | Use it when |
+| --- | --- |
+| `captures` | You know the URLs (1–100) and need them in SQL now |
+| `crawls` | You know a starting point, not the URLs |
+| `pins` | You need exact captures for longer than seven days |
+| `schedules` | You need the same pages again later |
+
+```python
+from periplus_sdk import Client
+
+with Client() as client:
+    capture = client.captures.create(urls=["https://example.com/pricing"])
+    capture = client.captures.get(capture, wait_seconds=30)
+    if capture.finished and capture.queryable:
+        for page in client.captures.pages(capture).items:
+            print(page.url, page.status, page.capture_id)
+
+    crawl = client.crawls.create(seeds=["https://example.com/docs/"], page_limit=200,
+                                 allowed_paths=["/docs/*"])
+
+    pin = client.pins.create(
+        name="Research sources", days=90,
+        sql="SELECT capture_id FROM captures WHERE domain(url) = ?",
+        parameters=["example.com"],
+    )
+    schedule = client.schedules.create(name="Pricing", every_days=7,
+                                       urls=["https://example.com/pricing"])
+    print(pin.captures, schedule.projected_pages_per_month)
+```
+
+Every capture is kept for seven days after collection unless a pin keeps it. A
+capture always fetches again and never returns an existing capture, so check
+coverage with SQL first. `request_id` (a capture or crawl `id`) is what you
+ordered; each page's `capture_id` is what the crawler produced and is the SQL key.
+`get(..., wait_seconds=N)` returns as soon as the request is finished and queryable,
+or after at most 30 seconds; the SDK never polls on its own.
+
+Pins and schedules accept explicit IDs/URLs or one read-only SQL query with
+parameters, and are active immediately. SQL runs once at creation and its exact
+result is locked in; running the same query beforehand is only an estimate.
+Schedule URLs need not be in the corpus. `pin_days` on a capture, crawl or schedule
+pins each successful capture it produces and requires `organization:pins:write`.
+`pins.update` changes `days` (moving every capture's expiry by the difference) or
+the name; `schedules.update` changes `every_days` or the name. Both accept a fetched
+object or an ID with `expected_version`; conflicts are never retried. Deletion needs
+no version: deleting a pin removes future protection, not captures.
+
+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, request
+page feeds and scheduled capture feeds use opaque keyset cursors. UTC usage ranges have an exclusive end date, at most 93 days. Usage reports pages
+captured (broken down by capture, crawl or schedule), challenge-resolution pages and
+pinned capture-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.12.1.dist-info/RECORD

@@ -0,0 +1,22 @@
+periplus_python_sdk-0.12.1.dist-info/licenses/licensing/LICENSE,sha256=DZak_2itbUtvHzD3E7GNUYSRK6jdOJ-GqncQ2weavLA,34523
+periplus_python_sdk-0.12.1.dist-info/licenses/licensing/NOTICE,sha256=W4W3pzZe-a0ebw4MxgWVmFGj7NSGL1qj8hFx4YG9iF0,105
+periplus_python_sdk-0.12.1.dist-info/licenses/licensing/README.md,sha256=NABTC2wm2Y9iRNMnlMeyVMA2dsAw7XRmCrsV1B2TQdk,1996
+periplus_python_sdk-0.12.1.dist-info/licenses/licensing/THIRD_PARTY_NOTICES.md,sha256=-egdv-dVsKhyRE2pPaHZgg4XYdpQfpH0VwM-sHYjUTg,9643
+periplus_sdk/__init__.py,sha256=QzgQOvgN2YBTr6Vf65uCwKzAPjjnxsq4kdXy2XWxRAs,1020
+periplus_sdk/async_resources.py,sha256=iSs3w-T6iCbQroWHU4aplKqVlnB7MCUlEf_na0FPym8,20073
+periplus_sdk/async_stream.py,sha256=O5hO_w_-ooQuDV1fOZRX4Qei1-w7Wri8eIlsn3yCpGQ,4592
+periplus_sdk/client.py,sha256=zVt1uso8LXQuwjVjOz3Nm9PH8bCAv1ZwLbuAvSj5BAI,15592
+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=JX7UEs4aHx_n2yErFdnDqaRHrsJtFSrWfSw1EaFm0vA,19680
+periplus_sdk/resources_types.py,sha256=_UBaTWaut8xq9jDcrJKZdswTDFjSi179P7V6LFjOhQU,8949
+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.12.1.dist-info/METADATA,sha256=IbyLcCvef30Umg7LyHPed2lyKRzBPGKsnDTdiKLIN_U,9198
+periplus_python_sdk-0.12.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+periplus_python_sdk-0.12.1.dist-info/entry_points.txt,sha256=Pr14L_7AhLinq-4qDxB4awFVubrvR1BEfkaFVRpdCbU,73
+periplus_python_sdk-0.12.1.dist-info/top_level.txt,sha256=o41t5TzwgoxzSmbKoP6olWW1FyEAGWVYTjeoKadBK40,13
+periplus_python_sdk-0.12.1.dist-info/RECORD,,

{periplus_python_sdk-0.9.0.dist-info → periplus_python_sdk-0.12.1.dist-info}/licenses/licensing/THIRD_PARTY_NOTICES.md

@@ -7,7 +7,7 @@ The Periplus license does not replace these terms.
 
 ## Selectolax and Lexbor
 
-The backend pins Selectolax 0.4.11 (MIT) and its bundled Lexbor 3.1.0
+The backend pins Selectolax 0.4.12 (MIT) and its bundled Lexbor 3.1.0
 (Apache-2.0). The DOM adapter's read-only native layouts follow Lexbor's DOM and
 HTML interface headers. Selectolax retains its packaged MIT license; Periplus
 includes Lexbor's license and notice under `licensing/third-party/lexbor/`

periplus_sdk/__init__.py

@@ -1,9 +1,13 @@
-"""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 (FollowRule, QueryCondition, Page, Request, RequestPage, Pin, PinCapture, Schedule, SchedulePage, Member,
+                              Invitation, ApiKey, CreatedApiKey, Identity, Usage)
 
 __all__ = ["connect", "AsyncClient", "Client", "ApiError", "ConfigurationError", "PeriplusError",
            "ResponseError", "TransportError", "Diagnostic", "PreparedQuery", "QueryHelper",
-           "QueryHelpers", "QueryResult"]
+           "QueryHelpers", "QueryResult", "FollowRule", "QueryCondition", "Page", "Request", "RequestPage", "Pin", "PinCapture",
+           "Schedule", "SchedulePage", "Member", "Invitation",
+           "ApiKey", "CreatedApiKey", "Identity", "Usage", "SourceSnapshot"]

periplus_sdk/async_resources.py

@@ -0,0 +1,366 @@
+"""Async customer operations; the same contract as resources.py."""
+from __future__ import annotations
+from collections.abc import AsyncIterator, Sequence
+from datetime import date, datetime
+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, AuditEvent, Availability, CreatedApiKey, Identity, Invitation, Member, Members,
+    FollowRule, Page, Pin, PinCapture, QueryExecution, QueryUsage, Request, RequestPagesPage, Role,
+    SavedQuery, Schedule, SchedulePage, 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 versioned_ref(value: Pin | Schedule | str | UUID, expected_version: int | None, model: type):
+    if isinstance(value, (Pin, Schedule)):
+        if not isinstance(value, model):
+            raise ValueError(f"Expected a {model.__name__}")
+        return value.id, value.version if expected_version is None else expected_version
+    if expected_version is None:
+        raise ValueError("An ID requires expected_version; fetch the resource before changing it")
+    return value, expected_version
+
+
+def object_id(value) -> str:
+    return path_id(value.id if isinstance(value, (Request, Pin, Schedule)) else value)
+
+
+def selection(ids_name: str, ids: Sequence | None, sql: str | None, parameters: Sequence[JsonValue]) -> dict:
+    if (ids is None) == (sql is None):
+        raise ValueError(f"Choose either {ids_name} or sql")
+    if sql is None:
+        if parameters:
+            raise ValueError("parameters require sql")
+        return {ids_name: [str(value) for value in ids]}
+    return {"sql": sql, "parameters": list(parameters)}
+
+
+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 RequestResource(PagedResource[Request]):
+    """Shared reads for captures and crawls: one request view and one page feed."""
+    noun: Literal["captures", "crawls"]
+
+    async def list(self, *, finished: bool | None = None, cursor: str | None = None,
+             limit: int = 20) -> Page[Request]:
+        return await self._client._resource_request("GET", self.noun, Page[Request],
+            params={"finished": finished, "offset": page_offset(cursor), "limit": page_size(limit)})
+
+    async def get(self, id: Request | str | UUID, *, wait_seconds: int = 0) -> Request:
+        """Return as soon as the request is finished and queryable, or after `wait_seconds` (0-30).
+
+        Waiting never delays capture. The SDK does not poll; call again to keep waiting."""
+        if not 0 <= wait_seconds <= 30:
+            raise ValueError("wait_seconds must be between 0 and 30")
+        return await self._client._resource_request("GET", f"{self.noun}/{object_id(id)}", Request,
+            params={"wait_seconds": wait_seconds or None})
+
+    async def pages(self, id: Request | str | UUID, *,
+              status: Literal["captured", "failed", "pending"] | None = None,
+              search: str | None = None, host: str | None = None, depth: int | None = None,
+              failure_code: str | None = None, render_incomplete: bool | None = None,
+              cursor: str | None = None, limit: int = 20) -> RequestPagesPage:
+        """Requested pages, newest first; `capture_id` is the SQL key. Pass cursors unchanged.
+
+        Failure-code filtering scans a bounded window, so an empty page can still have a cursor.
+        `render_incomplete=True` lists captured pages whose HTML was only a loading placeholder."""
+        return await self._client._resource_request("GET", f"{self.noun}/{object_id(id)}/pages", RequestPagesPage,
+            params={"status": status, "search": search, "host": host, "depth": depth,
+                    "failure_code": failure_code, "render_incomplete": render_incomplete,
+                    "cursor": cursor, "limit": page_size(limit)})
+
+    async def cancel(self, id: Request | str | UUID) -> Request:
+        """Stop remaining work. Captures already made are kept."""
+        return await self._client._resource_request("POST", f"{self.noun}/{object_id(id)}/cancel", Request)
+
+
+class CapturesResource(RequestResource):
+    noun = "captures"
+
+    async def create(self, *, urls: Sequence[str], pin_days: int | None = None,
+               id: UUID | None = None) -> Request:
+        """Fetch 1-100 known URLs once, now.
+
+        Always fetches again and never returns an existing capture: check coverage with SQL
+        first. `pin_days` pins each successful capture (requires organization:pins:write).
+        Keep `id` to reconcile an uncertain write; the same ID and input return the same request."""
+        return await self._client._resource_request("POST", "captures", Request, json={
+            "id": str(id or uuid4()), "urls": list(urls),
+            **({"pin_days": pin_days} if pin_days is not None else {})})
+
+
+class CrawlsResource(RequestResource):
+    noun = "crawls"
+
+    async def admission_preview(self, *, seeds: Sequence[str], accepted_queue_wait_seconds: int | None = None) -> Availability:
+        return await self._client._resource_request("POST", "access/crawl-preview", Availability, json={
+            "seed_urls": list(seeds), "accepted_queue_wait_seconds": accepted_queue_wait_seconds})
+
+    async def create(self, *, seeds: Sequence[str], page_limit: int, max_depth: int = 2,
+               follow_scope: Literal["starting_sites", "linked_sites"] = "starting_sites",
+               allowed_hosts: Sequence[str] = (), excluded_hosts: Sequence[str] = (),
+               allowed_paths: Sequence[str] = (), excluded_paths: Sequence[str] = (),
+               follow_rules: Sequence[FollowRule | dict] = (),
+               accepted_queue_wait_seconds: int | None = None,
+               pin_days: int | None = None, id: UUID | None = None) -> Request:
+        """Follow links from seeds when the URLs are not known yet.
+
+        `page_limit` means up to N pages including seeds, not guaranteed coverage. `max_depth`
+        is at least 1; use `captures.create` for known URLs. Hosts include subdomains; path
+        patterns match the whole URL-encoded path and only `*` is special."""
+        return await self._client._resource_request("POST", "crawls", Request, json={
+            "id": str(id or uuid4()), "seeds": list(seeds), "page_limit": page_limit,
+            "max_depth": max_depth, "follow_scope": follow_scope,
+            **({"accepted_queue_wait_seconds": accepted_queue_wait_seconds} if accepted_queue_wait_seconds is not None else {}),
+            "allowed_hosts": list(allowed_hosts), "excluded_hosts": list(excluded_hosts),
+            "allowed_paths": list(allowed_paths), "excluded_paths": list(excluded_paths),
+            "follow_rules": [rule.model_dump(exclude_none=True) if isinstance(rule, FollowRule) else rule
+                             for rule in follow_rules],
+            **({"pin_days": pin_days} if pin_days is not None else {})})
+
+
+class PinsResource(PagedResource[Pin]):
+    async def create(self, *, name: str, days: int, capture_ids: Sequence[str | UUID] | None = None,
+               sql: str | None = None, parameters: Sequence[JsonValue] = (),
+               saved_query_id: str | UUID | None = None, id: UUID | None = None) -> Pin:
+        """Keep exact captures for `days`, active immediately.
+
+        Pass `capture_ids`, one read-only `sql` query returning `capture_id`, or the
+        `saved_query_id` of such a query in your organization. SQL runs once at creation and its
+        exact result is locked in; running it beforehand is only an estimate. Membership never
+        changes. SQL selection also requires organization:sql:exec; a saved query also
+        requires organization:sql:read."""
+        if saved_query_id is not None:
+            if capture_ids is not None or sql is not None:
+                raise ValueError("Choose one of capture_ids, sql or saved_query_id")
+            source = {"saved_query_id": str(saved_query_id), "parameters": list(parameters)}
+        else:
+            source = selection("capture_ids", capture_ids, sql, parameters)
+        return await self._client._resource_request("POST", "pins", Pin, json={
+            "id": str(id or uuid4()), "name": name, "days": days, **source})
+
+    async def list(self, *, cursor: str | None = None, limit: int = 20) -> Page[Pin]:
+        return await self._client._resource_request("GET", "pins", Page[Pin],
+            params={"offset": page_offset(cursor), "limit": page_size(limit)})
+
+    async def get(self, id: Pin | str | UUID) -> Pin:
+        return await self._client._resource_request("GET", f"pins/{object_id(id)}", Pin)
+
+    async def captures(self, id: Pin | str | UUID, *, cursor: str | None = None,
+                 limit: int = 100) -> Page[PinCapture]:
+        """Pinned captures with each one's expiry."""
+        return await self._client._resource_request("GET", f"pins/{object_id(id)}/captures", Page[PinCapture],
+            params={"offset": page_offset(cursor), "limit": page_size(limit)})
+
+    async def update(self, pin: Pin | str | UUID, *, name: str | None = None, days: int | None = None,
+               expected_version: int | None = None) -> Pin:
+        """Rename, or change `days`: every capture's expiry moves by the difference."""
+        id, version = versioned_ref(pin, expected_version, Pin)
+        return await self._client._resource_request("PATCH", f"pins/{path_id(id)}", Pin, json={
+            "expected_version": version,
+            **{key: value for key, value in {"name": name, "days": days}.items() if value is not None}})
+
+    async def delete(self, id: Pin | str | UUID) -> None:
+        """Remove future protection. Captures and past usage are not deleted."""
+        return await self._client._resource_request("DELETE", f"pins/{object_id(id)}", None)
+
+
+class SchedulesResource(PagedResource[Schedule]):
+    async def create(self, *, name: str, every_days: int, urls: Sequence[str] | None = None,
+               sql: str | None = None, parameters: Sequence[JsonValue] = (),
+               pin_days: int | None = None, id: UUID | None = None) -> Schedule:
+        """Capture a fixed URL list every `every_days`, active immediately.
+
+        Pass `urls` (they need not be in the corpus) or one read-only `sql` query returning a
+        `url` column; SQL runs once and its URLs are locked in. Scheduled runs follow no links.
+        `pin_days` pins every successful scheduled capture (requires organization:pins:write)."""
+        return await self._client._resource_request("POST", "schedules", Schedule, json={
+            "id": str(id or uuid4()), "name": name, "every_days": every_days,
+            **selection("urls", urls, sql, parameters),
+            **({"pin_days": pin_days} if pin_days is not None else {})})
+
+    async def list(self, *, cursor: str | None = None, limit: int = 20) -> Page[Schedule]:
+        return await self._client._resource_request("GET", "schedules", Page[Schedule],
+            params={"offset": page_offset(cursor), "limit": page_size(limit)})
+
+    async def get(self, id: Schedule | str | UUID) -> Schedule:
+        return await self._client._resource_request("GET", f"schedules/{object_id(id)}", Schedule)
+
+    async def pages(self, id: Schedule | str | UUID, *, search: str | None = None,
+              cursor: str | None = None, limit: int = 100) -> Page[SchedulePage]:
+        """Scheduled URLs with their latest success, failure and next due time."""
+        return await self._client._resource_request("GET", f"schedules/{object_id(id)}/pages", Page[SchedulePage],
+            params={"search": search, "offset": page_offset(cursor), "limit": page_size(limit)})
+
+    async def captures(self, id: Schedule | str | UUID, *, status: Literal["captured", "failed"] | None = None,
+                 search: str | None = None, render_incomplete: bool | None = None,
+                 cursor: str | None = None, limit: int = 20) -> RequestPagesPage:
+        """Results of scheduled runs, newest first, in the request page-feed shape."""
+        return await self._client._resource_request("GET", f"schedules/{object_id(id)}/captures", RequestPagesPage,
+            params={"status": status, "search": search, "render_incomplete": render_incomplete,
+                    "cursor": cursor, "limit": page_size(limit)})
+
+    async def update(self, schedule: Schedule | str | UUID, *, name: str | None = None,
+               every_days: int | None = None, expected_version: int | None = None) -> Schedule:
+        id, version = versioned_ref(schedule, expected_version, Schedule)
+        return await self._client._resource_request("PATCH", f"schedules/{path_id(id)}", Schedule, json={
+            "expected_version": version, **{key: value for key, value in
+                {"name": name, "every_days": every_days}.items() if value is not None}})
+
+    async def pause(self, id: Schedule | str | UUID) -> Schedule:
+        """Stop new runs; an unstarted run is cancelled, started captures finish."""
+        return await self._client._resource_request("POST", f"schedules/{object_id(id)}/pause", Schedule)
+
+    async def resume(self, id: Schedule | str | UUID) -> Schedule:
+        return await self._client._resource_request("POST", f"schedules/{object_id(id)}/resume", Schedule)
+
+    async def delete(self, id: Schedule | str | UUID) -> None:
+        """Remove the schedule. Captures it produced are kept."""
+        return await self._client._resource_request("DELETE", f"schedules/{object_id(id)}", None)
+
+
+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 = "developer") -> 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, profile: Literal["developer", "agent"] = "developer", expires_at: datetime | 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, **({"profile": profile} if profile != "developer" else {}),
+                  **({"expires_at": expires_at.isoformat()} if expires_at is not None else {})})
+
+    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})