@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/dist/representation-tree.js

@@ -53,7 +53,7 @@ export function publicTree(tree, representation, documentRoutes, mode = 'light',
         if (node.type === 'docReaderSection') {
             const children = node.children.flatMap(walk);
             return representation === 'markdown' ? [paragraph({ type: 'strong', children: [text(`For ${node.description}.`)] }), ...children]
-                : [element('section', { className: ['reader-section'], 'data-reader-filters': JSON.stringify(node.selection) }, children)];
+                : [element('section', { className: ['reader-section'], 'data-reader-filters': JSON.stringify(node.selection), 'data-reader-print-label': `For ${node.description}.` }, children)];
         }
         if (node.type === 'docReaderChoice') {
             if (representation === 'markdown') {
@@ -66,6 +66,10 @@ export function publicTree(tree, representation, documentRoutes, mode = 'light',
         if (node.type === 'docReaderFilter') {
             return representation === 'markdown' ? [] : [element('div', { className: ['reader-filter-slot'], 'data-reader-filter': JSON.stringify(node.control) }, [])];
         }
+        if (node.type === 'table' && node.data?.referenceTableLabel && representation === 'html') {
+            const table = { ...node, children: node.children.flatMap(walk) };
+            return [element('div', { className: ['code-reference-table-scroll'], role: 'region', 'aria-label': node.data.referenceTableLabel, tabIndex: 0 }, [table])];
+        }
         if (node.type === 'docTable') {
             const table = node.children.flatMap(walk);
             if (representation === 'markdown')

package/dist/server.d.ts

@@ -1,4 +1,6 @@
 import { type Server, type ServerResponse } from 'node:http';
+export declare function canonicalSitePath(url: string): string;
+export declare function privateSitePath(pathname: string): boolean;
 export type PreviewStatus = {
     profile?: string;
     profileDigest?: string;

package/dist/server.js

@@ -1,11 +1,22 @@
 import { loadMcpRuntime, createMcpHttpHandler } from './mcp-http.js';
 import { bridgeMcp } from './mcp-node.js';
+import { loadPdfRuntime, createPdfHttpHandler } from './pdf-http.js';
 import { notFoundPage, addNotFoundTwin } from './not-found.js';
 import { createServer } from 'node:http';
 import { readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { homeUrl, negotiatedDocument } from './negotiation.js';
-const types = { '.html': 'text/html; charset=utf-8', '.md': 'text/markdown; charset=utf-8', '.xml': 'application/xml; charset=utf-8', '.json': 'application/json', '.yaml': 'application/yaml', '.yml': 'application/yaml', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.txt': 'text/plain; charset=utf-8', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.svg': 'image/svg+xml', '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.otf': 'font/otf' };
+export function canonicalSitePath(url) {
+    const decoded = decodeURIComponent(new URL(url, 'http://localhost').pathname).replace(/\\/g, '/');
+    if (decoded.includes('\0') || decoded.split('/').some(segment => segment === '..' || segment === '.'))
+        throw new Error('Invalid path');
+    return decoded.replace(/\/{2,}/g, '/');
+}
+export function privateSitePath(pathname) {
+    const internal = pathname.toLowerCase().replace(/\/+$/, '');
+    return ['/mcp-runtime.json', '/pdf-runtime.json', '/__shoalrun/mcp-data', '/__shoalrun/pdf-data'].some(privatePath => internal === privatePath || internal.startsWith(privatePath + '/'));
+}
+const types = { '.pdf': 'application/pdf', '.html': 'text/html; charset=utf-8', '.md': 'text/markdown; charset=utf-8', '.xml': 'application/xml; charset=utf-8', '.json': 'application/json', '.yaml': 'application/yaml', '.yml': 'application/yaml', '.css': 'text/css; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.txt': 'text/plain; charset=utf-8', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.svg': 'image/svg+xml', '.woff2': 'font/woff2', '.woff': 'font/woff', '.ttf': 'font/ttf', '.otf': 'font/otf' };
 const escapeHtml = (value) => value.replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[character]));
 const scriptJson = (value) => JSON.stringify(value).replace(/</g, '\\u003c');
 export function previewMarkup(basePath, preview) {
@@ -58,6 +69,9 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
     let mcp = await loadMcpRuntime(root);
     let mcpHandler = mcp ? createMcpHttpHandler(mcp) : undefined;
     let mcpBuild = mcp?.runtime.buildId;
+    let pdf = await loadPdfRuntime(root);
+    let pdfHandler = pdf ? createPdfHttpHandler(pdf) : undefined;
+    let pdfBuild = initialState.manifest.buildId;
     async function siteFile(route) {
         const file = path.resolve(root, `.${route}`);
         if (file !== root && !file.startsWith(`${root}${path.sep}`))
@@ -73,9 +87,7 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
         let pathname = '';
         let recoveryState = initialState;
         try {
-            pathname = decodeURIComponent(new URL(request.url ?? '/', 'http://localhost').pathname);
-            if (pathname.includes('\0') || pathname.split('/').includes('..'))
-                throw new Error('Invalid path');
+            pathname = canonicalSitePath(request.url ?? '/');
             const { headers, manifest, redirects, search, errorHtml, home, routes } = liveClients ? await loadState() : initialState;
             recoveryState = { headers, manifest, redirects, search, errorHtml, home, routes };
             const basePath = manifest.basePath ?? '';
@@ -85,12 +97,28 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
                 mcpHandler = next ? createMcpHttpHandler(next) : undefined;
                 mcpBuild = manifest.buildId;
             }
-            const internalPath = pathname.toLowerCase().replace(/\/+$/, '');
-            if (internalPath === '/mcp-runtime.json' || internalPath === '/__shoalrun/mcp-data' || internalPath.startsWith('/__shoalrun/mcp-data/')) {
+            if (privateSitePath(pathname)) {
                 response.writeHead(404);
                 response.end();
                 return;
             }
+            if (liveClients && manifest.buildId !== pdfBuild) {
+                pdf = await loadPdfRuntime(root);
+                pdfHandler = pdf ? createPdfHttpHandler(pdf) : undefined;
+                pdfBuild = manifest.buildId;
+            }
+            if (pdf && pdfHandler && pathname === pdf.runtime.endpoint) {
+                try {
+                    await bridge(request, response, pdfHandler);
+                }
+                catch {
+                    if (!response.headersSent) {
+                        response.writeHead(503, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' });
+                        response.end('{"error":"PDF generation is unavailable."}');
+                    }
+                }
+                return;
+            }
             if (mcp && mcpHandler && pathname === mcp.runtime.path) {
                 await bridgeMcp(request, response, mcpHandler);
                 return;
@@ -201,8 +229,7 @@ export async function createSiteServer(directory, liveClients, extras = {}) {
                 mcpHandler = next ? createMcpHttpHandler(next) : undefined;
                 mcpBuild = manifest.buildId;
             }
-            const internalPath = pathname.toLowerCase().replace(/\/+$/, '');
-            if (internalPath === '/mcp-runtime.json' || internalPath === '/__shoalrun/mcp-data' || internalPath.startsWith('/__shoalrun/mcp-data/')) {
+            if (privateSitePath(pathname)) {
                 response.writeHead(404);
                 response.end();
                 return;

package/dist/vercel.js

@@ -5,6 +5,9 @@ import path from 'node:path';
 import { compile } from './compiler.js';
 import { homeUrl } from './negotiation.js';
 import { addAskFunction } from './vercel-function.js';
+import { loadConfig } from './config.js';
+import { resolvedCompilerConfig } from './compiler-config.js';
+import { resolvePdfButton } from './pdf-button.js';
 function exact(route) {
     return route.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -28,6 +31,9 @@ async function removeStaleFunctions(directory, keep = new Set()) {
     await visit(directory);
 }
 export async function buildVercel(configFile, outputDirectory, provenance = {}, options = {}) {
+    const settings = resolvedCompilerConfig((await loadConfig(configFile, { profile: options.profile })).value);
+    if (resolvePdfButton(settings.outputs)?.mode === 'endpoint')
+        throw new Error('On-demand PDF generation requires a Node server with an installed Chromium browser. Use outputs.html.pdf.mode: print for Vercel builds.');
     const output = path.resolve(outputDirectory);
     const staticDirectory = path.join(output, 'static');
     if (options.profile && options.chat)

package/examples/code-references/content/start.md

@@ -0,0 +1,53 @@
+---
+id: guide.start
+title: Python SDK
+summary: Explore a typed SDK with synchronous and async clients, models, pagination, and exceptions.
+type: guide
+slug: /
+channel: production
+version: current
+language: en
+access: { policy: public }
+---
+This example SDK manages records. Its reference pages are generated from Python source and docstrings, then rendered with Shoalrun's normal theme, navigation, search, and Markdown output.
+
+The sample client stores records in memory. It doesn't connect to a live service.
+
+## Fetch a typed record
+
+```python
+from orchard import Client
+
+client = Client("demo-key")
+record = client.fetch("rec_42")
+print(record.title)
+```
+
+Read [Client](doc:reference.client) for configuration and [fetch](doc:reference.fetch) for its typed and raw-response overloads.
+
+## Work with more than one page
+
+```python
+from orchard import RecordStatus
+
+for record in client.iter_records(page_size=50, status=RecordStatus.READY):
+    print(record.id, record.title)
+```
+
+Choose [list_records](doc:reference.Client.list_records) when your application needs explicit cursor control, or [Page.map](doc:reference.pagination.Page.map) to transform a response without losing its pagination metadata.
+
+## Use an async client
+
+```python
+from orchard import AsyncClient
+
+client = AsyncClient("demo-key")
+async for record in client.iter_records(page_size=50):
+    print(record.title)
+```
+
+Browse [AsyncClient](doc:reference.AsyncClient), [Record](doc:reference.models.Record), and the [typed exceptions](doc:reference.errors) to see how the generated reference fits together.
+
+## Choose how to browse
+
+Read the [Client class with member details inline](doc:reference.client), or open the [complete Python SDK reference](doc:reference.complete) to browse everything on one page. The example uses `layout: classes` and enables `singlePage` in its catalog configuration. Individual symbol links remain available.

package/examples/code-references/docs.config.yaml

@@ -0,0 +1,262 @@
+schemaVersion: 1
+site:
+  title: Python SDK documentation
+publications:
+  channels:
+    production: {}
+  versions:
+    current: {}
+  defaults:
+    channel: production
+    version: current
+    language: en
+  enabled:
+    - channel: production
+      version: current
+      language: en
+codeReferences:
+  sdk:
+    source:
+      kind: file
+      path: ./reference.json
+    symbols:
+      orchard:
+        documentId: reference.orchard
+        slug: /reference/orchard
+      orchard.client:
+        documentId: reference.clients
+        slug: /reference/clients
+      orchard.client.AsyncClient:
+        documentId: reference.AsyncClient
+        slug: /reference/async-client
+      orchard.client.AsyncClient.__init__:
+        documentId: reference.AsyncClient.__init__
+        slug: /reference/async-client/constructor
+      orchard.client.AsyncClient.fetch:
+        documentId: reference.AsyncClient.fetch
+        slug: /reference/async-client/fetch
+      orchard.client.AsyncClient.iter_records:
+        documentId: reference.AsyncClient.iter_records
+        slug: /reference/async-client/iter-records
+      orchard.client.Client:
+        documentId: reference.client
+        slug: /reference/client
+      orchard.client.Client.__init__:
+        documentId: reference.Client.__init__
+        slug: /reference/client/constructor
+      orchard.client.Client.base_url:
+        documentId: reference.Client.base_url
+        slug: /reference/client/base-url
+      orchard.client.Client.bulk_create:
+        documentId: reference.Client.bulk_create
+        slug: /reference/client/bulk-create
+      orchard.client.Client.create_record:
+        documentId: reference.Client.create_record
+        slug: /reference/client/create-record
+      orchard.client.Client.fetch:
+        documentId: reference.fetch
+        slug: /reference/client/fetch
+      orchard.client.Client.iter_records:
+        documentId: reference.Client.iter_records
+        slug: /reference/client/iter-records
+      orchard.client.Client.list_records:
+        documentId: reference.Client.list_records
+        slug: /reference/client/list-records
+      orchard.client.Client.max_retries:
+        documentId: reference.Client.max_retries
+        slug: /reference/client/max-retries
+      orchard.client.Client.timeout:
+        documentId: reference.Client.timeout
+        slug: /reference/client/timeout
+      orchard.errors:
+        documentId: reference.errors
+        slug: /reference/errors
+      orchard.errors.APIError:
+        documentId: reference.errors.APIError
+        slug: /reference/errors/apierror
+      orchard.errors.APIError.__init__:
+        documentId: reference.errors.APIError.__init__
+        slug: /reference/errors/apierror/constructor
+      orchard.errors.APIError.request_id:
+        documentId: reference.errors.APIError.request_id
+        slug: /reference/errors/apierror/request-id
+      orchard.errors.AuthenticationError:
+        documentId: reference.errors.AuthenticationError
+        slug: /reference/errors/authenticationerror
+      orchard.errors.NotFoundError:
+        documentId: reference.errors.NotFoundError
+        slug: /reference/errors/notfounderror
+      orchard.errors.RateLimitError:
+        documentId: reference.errors.RateLimitError
+        slug: /reference/errors/ratelimiterror
+      orchard.errors.RateLimitError.__init__:
+        documentId: reference.errors.RateLimitError.__init__
+        slug: /reference/errors/ratelimiterror/constructor
+      orchard.errors.RateLimitError.retry_after:
+        documentId: reference.errors.RateLimitError.retry_after
+        slug: /reference/errors/ratelimiterror/retry-after
+      orchard.models:
+        documentId: reference.models
+        slug: /reference/models
+      orchard.models.Record:
+        documentId: reference.models.Record
+        slug: /reference/models/record
+      orchard.models.Record.created_at:
+        documentId: reference.models.Record.created_at
+        slug: /reference/models/record/created-at
+      orchard.models.Record.id:
+        documentId: reference.models.Record.id
+        slug: /reference/models/record/id
+      orchard.models.Record.labels:
+        documentId: reference.models.Record.labels
+        slug: /reference/models/record/labels
+      orchard.models.Record.status:
+        documentId: reference.models.Record.status
+        slug: /reference/models/record/status
+      orchard.models.Record.title:
+        documentId: reference.models.Record.title
+        slug: /reference/models/record/title
+      orchard.models.Record.to_dict:
+        documentId: reference.models.Record.to_dict
+        slug: /reference/models/record/to-dict
+      orchard.models.RecordDict:
+        documentId: reference.models.RecordDict
+        slug: /reference/models/recorddict
+      orchard.models.RecordDict.id:
+        documentId: reference.models.RecordDict.id
+        slug: /reference/models/recorddict/id
+      orchard.models.RecordDict.status:
+        documentId: reference.models.RecordDict.status
+        slug: /reference/models/recorddict/status
+      orchard.models.RecordDict.title:
+        documentId: reference.models.RecordDict.title
+        slug: /reference/models/recorddict/title
+      orchard.models.RecordInput:
+        documentId: reference.models.RecordInput
+        slug: /reference/models/recordinput
+      orchard.models.RecordInput.labels:
+        documentId: reference.models.RecordInput.labels
+        slug: /reference/models/recordinput/labels
+      orchard.models.RecordInput.title:
+        documentId: reference.models.RecordInput.title
+        slug: /reference/models/recordinput/title
+      orchard.models.RecordStatus:
+        documentId: reference.models.RecordStatus
+        slug: /reference/models/recordstatus
+      orchard.models.RecordStatus.FAILED:
+        documentId: reference.models.RecordStatus.FAILED
+        slug: /reference/models/recordstatus/failed
+      orchard.models.RecordStatus.PENDING:
+        documentId: reference.models.RecordStatus.PENDING
+        slug: /reference/models/recordstatus/pending
+      orchard.models.RecordStatus.READY:
+        documentId: reference.models.RecordStatus.READY
+        slug: /reference/models/recordstatus/ready
+      orchard.pagination:
+        documentId: reference.pagination
+        slug: /reference/pagination
+      orchard.pagination.Page:
+        documentId: reference.pagination.Page
+        slug: /reference/pagination/page
+      orchard.pagination.Page.has_more:
+        documentId: reference.pagination.Page.has_more
+        slug: /reference/pagination/page/has-more
+      orchard.pagination.Page.items:
+        documentId: reference.pagination.Page.items
+        slug: /reference/pagination/page/items
+      orchard.pagination.Page.map:
+        documentId: reference.pagination.Page.map
+        slug: /reference/pagination/page/map
+      orchard.pagination.Page.next_cursor:
+        documentId: reference.pagination.Page.next_cursor
+        slug: /reference/pagination/page/next-cursor
+      orchard.pagination.Page.total:
+        documentId: reference.pagination.Page.total
+        slug: /reference/pagination/page/total
+      orchard.pagination.T:
+        documentId: reference.pagination.T
+        slug: /reference/pagination/t
+      orchard.pagination.U:
+        documentId: reference.pagination.U
+        slug: /reference/pagination/u
+    layout: classes
+    singlePage:
+      documentId: reference.complete
+      slug: /reference/all
+      title: Complete Python SDK reference
+      summary: Browse every public module, class, method, and field on one page.
+navigation:
+  - id: start
+    doc: guide.start
+  - id: complete
+    doc: reference.complete
+  - id: overview
+    label: Package
+    items:
+      - id: orchard
+        doc: reference.orchard
+      - id: orchard.client
+        doc: reference.clients
+  - id: client
+    label: Synchronous client
+    items:
+      - id: orchard.client.Client
+        doc: reference.client
+      - id: orchard.client.Client.__init__
+        doc: reference.Client.__init__
+      - id: orchard.client.Client.fetch
+        doc: reference.fetch
+      - id: orchard.client.Client.list_records
+        doc: reference.Client.list_records
+      - id: orchard.client.Client.iter_records
+        doc: reference.Client.iter_records
+      - id: orchard.client.Client.create_record
+        doc: reference.Client.create_record
+      - id: orchard.client.Client.bulk_create
+        doc: reference.Client.bulk_create
+  - id: async
+    label: Asynchronous client
+    items:
+      - id: orchard.client.AsyncClient
+        doc: reference.AsyncClient
+      - id: orchard.client.AsyncClient.fetch
+        doc: reference.AsyncClient.fetch
+      - id: orchard.client.AsyncClient.iter_records
+        doc: reference.AsyncClient.iter_records
+  - id: models
+    label: Models
+    items:
+      - id: orchard.models
+        doc: reference.models
+      - id: orchard.models.Record
+        doc: reference.models.Record
+      - id: orchard.models.RecordInput
+        doc: reference.models.RecordInput
+      - id: orchard.models.RecordDict
+        doc: reference.models.RecordDict
+      - id: orchard.models.RecordStatus
+        doc: reference.models.RecordStatus
+      - id: orchard.models.Record.to_dict
+        doc: reference.models.Record.to_dict
+  - id: pagination
+    label: Pagination
+    items:
+      - id: orchard.pagination.Page
+        doc: reference.pagination.Page
+      - id: orchard.pagination.Page.map
+        doc: reference.pagination.Page.map
+      - id: orchard.pagination.Page.has_more
+        doc: reference.pagination.Page.has_more
+  - id: errors
+    label: Exceptions
+    items:
+      - id: orchard.errors
+        doc: reference.errors
+      - id: orchard.errors.APIError
+        doc: reference.errors.APIError
+      - id: orchard.errors.AuthenticationError
+        doc: reference.errors.AuthenticationError
+      - id: orchard.errors.NotFoundError
+        doc: reference.errors.NotFoundError
+      - id: orchard.errors.RateLimitError
+        doc: reference.errors.RateLimitError

package/examples/code-references/python/orchard/__init__.py

@@ -0,0 +1,11 @@
+"""A sample SDK for working with records, collections, and paginated results.
+
+Use [Client](symbol:orchard.client.Client) in synchronous applications, or
+[AsyncClient](symbol:orchard.client.AsyncClient) in an async service. Models,
+pagination helpers, and typed exceptions have their own reference pages.
+
+This package is documentation example code. It doesn't contact a live service.
+"""
+from .client import AsyncClient, Client
+from .models import Record, RecordInput, RecordStatus
+from .pagination import Page

package/examples/code-references/python/orchard/client.py

@@ -0,0 +1,212 @@
+"""Synchronous and asynchronous clients for the sample records SDK."""
+from collections.abc import AsyncIterator, Iterator, Sequence
+from typing import Literal, overload
+from .errors import AuthenticationError, NotFoundError
+from .models import Record, RecordDict, RecordInput, RecordStatus
+from .pagination import Page
+
+class Client:
+    """Manage records from a synchronous Python application.
+
+    Create one client per API credential and reuse it across requests. Use
+    [AsyncClient](symbol:orchard.client.AsyncClient) in an async application.
+
+    The sample client keeps records in memory; it doesn't make network calls.
+    """
+    def __init__(self, api_key: str, *, base_url: str = "https://api.example.com/v1", timeout: float = 10.0, max_retries: int = 2):
+        """Configure a reusable client.
+
+        Args:
+            api_key: Credential used to identify the application.
+            base_url: Root URL of the API deployment.
+            timeout: Default request timeout, in seconds.
+            max_retries: Number of retries for transient failures.
+
+        Raises:
+            AuthenticationError: If the API key is empty.
+        """
+        if not api_key:
+            raise AuthenticationError("API key must not be empty")
+        self.base_url = base_url
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self._records: dict[str, Record] = {"rec_42": Record("rec_42", "Getting started")}
+
+    @overload
+    def fetch(self, record_id: str, *, raw: Literal[False] = False, timeout: float | None = None) -> Record: ...
+    @overload
+    def fetch(self, record_id: str, *, raw: Literal[True], timeout: float | None = None) -> RecordDict: ...
+    def fetch(self, record_id: str, *, raw: bool = False, timeout: float | None = None) -> Record | RecordDict:
+        """Retrieve a record by its stable identifier.
+
+        The default response is a typed [Record](symbol:orchard.models.Record).
+        Set `raw=True` to receive a dictionary for serialization or a legacy
+        integration. An explicit timeout overrides the client's default.
+
+        Args:
+            record_id: Stable identifier of the record to retrieve.
+            raw: Return a wire-format dictionary instead of a model.
+            timeout: Request timeout override, in seconds.
+
+        Returns:
+            The record model, or a dictionary when `raw=True`.
+
+        Raises:
+            ValueError: If the record identifier is empty.
+            NotFoundError: If no record matches the identifier.
+
+        Examples:
+            >>> client = Client("demo-key")
+            >>> record = client.fetch("rec_42")
+            >>> record.title
+            'Getting started'
+            >>> payload = client.fetch("rec_42", raw=True)
+            >>> payload["status"]
+            'ready'
+        """
+        if not record_id:
+            raise ValueError("record_id must not be empty")
+        if record_id not in self._records:
+            raise NotFoundError(f"Record {record_id} was not found")
+        record = self._records[record_id]
+        return record.to_dict() if raw else record
+
+    def list_records(self, *, limit: int = 20, cursor: str | None = None, status: RecordStatus | None = None) -> Page[Record]:
+        """List a single page of records with optional status filtering.
+
+        Use [iter_records](symbol:orchard.client.Client.iter_records) when you
+        want to read every page without managing continuation cursors.
+
+        Args:
+            limit: Maximum number of records in a page, from 1 to 100.
+            cursor: Opaque continuation token from an earlier response.
+            status: Include only records with this processing status.
+
+        Returns:
+            A page of matching records with an optional continuation cursor.
+
+        Raises:
+            ValueError: If the page size is outside the supported range.
+
+        Examples:
+            >>> page = client.list_records(limit=10, status=RecordStatus.READY)
+            >>> titles = page.map(lambda record: record.title)
+        """
+        if not 1 <= limit <= 100:
+            raise ValueError("limit must be between 1 and 100")
+        records = [r for r in self._records.values() if status is None or r.status == status]
+        start = int(cursor or "0")
+        end = start + limit
+        return Page(records[start:end], str(end) if end < len(records) else None, len(records))
+
+    def iter_records(self, *, page_size: int = 20, status: RecordStatus | None = None) -> Iterator[Record]:
+        """Iterate through records across every page.
+
+        Pagination is lazy: another page is read only when the iterator needs it.
+        Stop iteration early to avoid fetching pages your application won't use.
+
+        Args:
+            page_size: Number of records requested per page, from 1 to 100.
+            status: Optional processing status filter.
+
+        Yields:
+            Records in the service's response order.
+
+        Examples:
+            >>> for record in client.iter_records(page_size=50):
+            ...     print(record.id, record.title)
+        """
+        cursor = None
+        while True:
+            page = self.list_records(limit=page_size, cursor=cursor, status=status)
+            yield from page.items
+            if not page.has_more:
+                return
+            cursor = page.next_cursor
+
+    def create_record(self, data: RecordInput, *, idempotency_key: str | None = None) -> Record:
+        """Create a record from a typed input model.
+
+        Use an idempotency key when retrying a request after a timeout. Reuse the
+        same key only for retries of the same logical operation.
+
+        Args:
+            data: Title and labels for the new record.
+            idempotency_key: Application-generated retry token.
+
+        Returns:
+            An immutable snapshot of the created record.
+
+        Examples:
+            >>> data = RecordInput(title="Deployment notes", labels={"team": "platform"})
+            >>> record = client.create_record(data, idempotency_key="deploy-42")
+        """
+        record = Record(f"rec_{len(self._records) + 1}", data.title, labels=data.labels)
+        self._records[record.id] = record
+        return record
+
+    def bulk_create(self, records: Sequence[RecordInput], *, batch_size: int = 25) -> list[Record]:
+        """Create multiple records in bounded batches.
+
+        Args:
+            records: Input models to create, in submission order.
+            batch_size: Maximum number of records per batch, from 1 to 100.
+
+        Returns:
+            Created records in the same order as the submitted inputs.
+
+        Raises:
+            ValueError: If the batch size is outside the supported range.
+        """
+        if not 1 <= batch_size <= 100:
+            raise ValueError("batch_size must be between 1 and 100")
+        return [self.create_record(item) for item in records]
+
+class AsyncClient:
+    """Use the records SDK from an async Python application.
+
+    Await individual operations, or use `async for` to consume a record iterator.
+    This example delegates to an in-memory client; no network calls are made.
+    """
+    def __init__(self, api_key: str, *, timeout: float = 10.0):
+        """Configure an async client.
+
+        Args:
+            api_key: Application credential.
+            timeout: Default request timeout, in seconds.
+        """
+        self._client = Client(api_key, timeout=timeout)
+
+    async def fetch(self, record_id: str, *, timeout: float | None = None) -> Record:
+        """Await a typed record response.
+
+        Args:
+            record_id: Stable record identifier.
+            timeout: Optional request timeout override, in seconds.
+
+        Returns:
+            The matching record model.
+
+        Raises:
+            NotFoundError: If the record doesn't exist.
+
+        Examples:
+            >>> record = await client.fetch("rec_42")
+        """
+        return self._client.fetch(record_id, timeout=timeout)
+
+    async def iter_records(self, *, page_size: int = 20) -> AsyncIterator[Record]:
+        """Consume paginated records using asynchronous iteration.
+
+        Args:
+            page_size: Maximum number of records read in one page.
+
+        Yields:
+            Typed records from successive pages.
+
+        Examples:
+            >>> async for record in client.iter_records(page_size=50):
+            ...     print(record.title)
+        """
+        for record in self._client.iter_records(page_size=page_size):
+            yield record