@oddington/sdk 0.1.23 → 0.1.25

package/README.md

@@ -1,6 +1,6 @@
-# Oddington SDK
+# OS SDK
 
-The importable client for Oddington apps, routines and response handlers.
+The importable client for OS apps, routines and response handlers.
 Node operations require Node.js 22.12.0 or later. The root import and hosted
 Data and Files APIs work in browsers. Installing the package grants no authority.
 
@@ -396,8 +396,8 @@ await files.upload(report.id); // Move a local File and every retained enrichmen
 
 Hosted Files retains remote originals and caller-produced named enrichments;
 `storage: 'local'` requires a managed CLI parent. Configure that parent with
-`ODDINGTON_FILES_ROOT` pointing to an empty or already OS-managed dedicated
-directory outside tracked Git content. `ODDINGTON_FILES_DEFAULT=local|remote`
+`OS_FILES_ROOT` pointing to an empty or already OS-managed dedicated
+directory outside tracked Git content. `OS_FILES_DEFAULT=local|remote`
 selects its default; without it, remote remains the default. Per-File `storage`
 overrides it. The root stays private to the parent. Local creation without a
 configured root fails with `unsupported_context`. Files have one durable home;
@@ -501,6 +501,55 @@ replacement; repeat its options and links while omitting unrelated collections.
 There is no automatic retry or separate version fetch.
 Collection schemas omit Markdown storage hints.
 
+Iterate matching Records on demand or collect them with an explicit total ceiling:
+
+```ts
+import type { RecordsQuery } from '@oddington/sdk';
+
+const query = {
+  invoices: { $: { limit: 50, count: true }, supplier: { $: { fields: ['name'] } } },
+  suppliers: { $: { fields: ['name'], limit: 50 } },
+} satisfies RecordsQuery;
+
+for await (const page of general.records.pages(query)) {
+  consume(page.invoices, page.suppliers);
+}
+const matches = await general.records.all(query, { maxRecords: 10_000 });
+```
+
+Both helpers preserve literal collection arrays and selected-link inference.
+`pages` captures the query at invocation, fetches only when requested, and never
+prefetches after a consumer stops. Independent collection cursors pin the first
+snapshot. Completed collections yield empty arrays on later pages and retain
+requested counts. Empty matches yield one versioned page. Helpers own continuation;
+use `select` for a manual `after` cursor or explicit historical selection.
+
+`all` consumes the same iterator and returns only after successful exhaustion.
+Its required positive safe-integer `maxRecords` caps top-level Record occurrences
+across all collections; expanded links do not count toward that ceiling. Overflow
+rejects with nonretryable `capacity`, without a partial or truncated result.
+Invalid helper arguments use `invalid_query`; malformed pages, cursor cycles,
+snapshot changes or inconsistent requested counts use nonretryable `unavailable`.
+Selection and authority failures propagate unchanged, with no retry or restart.
+
+Read known stable refs directly, including refs from different collections:
+
+```ts
+const invoice = await general.records.read('invoices/one'); // complete Record or null
+const batch = await general.records.read(['invoices/one', 'suppliers/acme']);
+// batch.$meta.version identifies one repository snapshot.
+// batch.records has one Record-or-null slot per input, in the same order.
+```
+
+An array accepts 1–100 distinct valid refs; a one-element array keeps the batch
+shape, and all-missing batches still carry their version. Both forms send one
+bounded operation through the same app/routine authority and snapshot as `select`.
+Records include `$ref`, `$version` and all canonical structured fields; links
+remain refs, omitted and null fields stay distinct, and Markdown bodies and
+`$filing` are excluded. Invalid refs, exceeded bounds, denied access and service
+failures reject the entire call; only a missing Record returns null. No options,
+projection, expansion or historical version argument is accepted.
+
 Read published History through the same inert repository handle:
 
 ```ts
@@ -663,8 +712,8 @@ work; never repeat the whole change blindly. Credentials must never be retained
 in files, publication, logs, handler input, errors or receipts.
 
 Managed routine launches supply workspace, scoped capability and working root.
-The defaults read `ODDINGTON_ROUTINE_WORKSPACE`, `ODDINGTON_ROUTINE_RUN` and
-`ODDINGTON_INBOX_WORKING_ROOT` (or the current directory). Callers may supply the
+The defaults read `OS_ROUTINE_WORKSPACE`, `OS_ROUTINE_RUN` and
+`OS_INBOX_WORKING_ROOT` (or the current directory). Callers may supply the
 existing `workspace`, `capability` and `workingRoot` options. Runtime context
 provides authority; callers cannot select repository remotes or expand grants.
 `os routine run <name> [--input <file|->]` executes the conventional inert