@oddington/sdk 0.1.2 → 0.1.4

package/README.md

@@ -1,7 +1,8 @@
 # Oddington SDK
 
-The importable client for Oddington routines and response handlers. Requires
-Node.js 22.12.0 or later. Installing the package grants no authority.
+The importable client for Oddington 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.
 
 ```sh
 npm install @oddington/sdk
@@ -13,6 +14,138 @@ import { defineHandler, resolveAsk, routinePublicationClient } from '@oddington/
 const inbox = routinePublicationClient();
 ```
 
+The OS-owned browser entry point initializes the existing shared refreshing
+session source before app code runs:
+
+```ts
+import { os } from '@oddington/sdk';
+
+os.init({ auth });
+```
+
+This returns `void` and derives context from the current HTTPS workspace origin
+under `oddington.ai`, excluding `auth`. Reinitialization replaces the previous
+session subscription. Workspace existence and member access are checked by the
+OS service. App modules use capability namespaces; routines and handlers receive
+runtime context without calling `os.init`.
+
+Create and recover a private immutable original through the same host context:
+
+```ts
+import { files } from '@oddington/sdk';
+
+const report = await files.create({
+  file: selectedFile, // Web File, path-backed Blob, Uint8Array or byte stream
+  name: 'September statement.csv',
+  path: 'HSC/2026/09',
+}, { requestKey: 'statement/2026/09' });
+const descriptor = await files.get(report.id);
+const response = await files.read(descriptor.id);
+await response.text(); // Also supports blob(), arrayBuffer() and body streaming.
+```
+
+Hosted Files retains remote originals only, with empty `enrichments`. It rejects
+`local`, `both` and explicit routine local preparation with `unsupported_context`.
+Unnamed inputs require a safe `name`; streams also require declared `size`.
+Blob and byte-array declarations must match their intrinsic size. Originals are
+bounded to 16 MiB, metadata to 4 KiB, and descriptor/error bodies to 16 KiB.
+Creates allow four concurrent buffered operations and a 30-second deadline;
+transport retries at most once with the same prepared bytes and request key.
+Omitting a key generates one for that invocation. Supply a stable key to recover
+across processes or fresh routine runs. Caller inputs remain owned by the caller.
+Each request resolves current authority; routine Files calls go directly to the
+selected workspace's HTTPS OS host. `FileOperationError` exposes a bounded code,
+status and retryability without server details. Reads return the successful Web
+Response without consuming its body. Creation grants private creator access;
+workspace membership alone never grants another creator's File.
+
+Read a named repository through the authenticated host context:
+
+```ts
+import { data, DataOperationError } from '@oddington/sdk';
+
+const general = data.repository('general');
+const collections = await general.collections.list();
+const schema = await general.collections.schema('invoices');
+const first = await general.records.select({
+  invoices: { $: { limit: 50 }, supplier: { $: { fields: ['name'] } } },
+  suppliers: {},
+});
+const next = first.$meta.collections.invoices.next;
+if (next) await general.records.select({
+  invoices: { $: { limit: 50, after: next }, supplier: { $: { fields: ['name'] } } },
+});
+```
+
+Binding is inert. Each operation resolves current workspace, endpoint and
+short-lived authority from the trusted app host or managed routine context.
+Customer calls cannot configure those values. Missing or expired context
+rejects; a named handle does not expand repository access. During explicit
+`os routine run --local`, the same calls use the matched checkout's committed
+version through a private parent transport. Dirty files are ignored. An OS
+cache outside the checkout reuses derived data; reads require no remote access
+or preparation storage. Later accepted record effects advance the run's view
+to their exact proposed version. Login, installed grants and provider authority
+retain their normal checks. A dead local parent fails without hosted fallback.
+
+Each graph selection sends one request and returns only selected canonical
+values, expanded forward links and exact opaque public versions. Cursors
+continue the exact retained artifact and collection selection, even after
+replacement; repeat its options and links while omitting unrelated collections.
+No automatic retry, separate version fetch, search or history operation is
+included. Collection schemas omit Markdown storage hints.
+
+`where` combines field conditions with AND. Alongside exact scalar/null equality
+and `$in`, declared one-valued `integer`, `number` and `date` fields accept
+`$gt`, `$gte`, `$lt` and `$lte`:
+
+```ts
+await general.records.select({ invoices: { $: { where: {
+  amount: { $gte: 10, $lte: 20 },
+  date: { $gte: '2026-10-01', $lt: '2026-11-01' },
+  month: { $gte: '2026-10', $lte: '2026-10' },
+}, count: true } } });
+```
+
+Supply one lower bound, one upper bound, or one of each. Bounds cannot combine
+`$gt` with `$gte`, `$lt` with `$lte`, or any bound with `$in`. Operands must be
+valid for the declared field, including numeric precision and real day/month
+dates; values are never coerced. Missing and null values never match bounds.
+A valid interval without matches returns an empty array and requested zero
+count. V0 types check expression structure; runtime schema validation owns field
+eligibility. Repeat the same bounds when continuing a cursor.
+
+`DataOperationError.code` distinguishes `context_unavailable`, `unauthenticated`,
+`access_denied`, `invalid_query`, `request_too_large`, `capacity` and `unavailable`.
+For reads, only `capacity` and `unavailable` are retryable; an error never includes private
+server details. Server boundaries own query bounds and authorization.
+
+Guarded updates use the same handle in hosted and explicitly local routines:
+
+```ts
+const changes = general.changes();
+changes.update(first.invoices[0], { amount: 30 });
+await changes.validate();
+const publication = await changes.publish();
+```
+
+Preparation captures only the Record's `$ref`, `$version` and explicit set,
+without I/O. Validation checks the complete committed result without effects;
+publication repeats guarded validation and applies the whole update batch.
+Success returns `{ version, created: [], updated: [{ $ref, $version }], deleted: [] }`
+only after its exact index is ready. Later current reads discover that version.
+During `os routine run --local`, publication retains the exact proposal and
+advances only run-local reads. `os routine publish` later applies and indexes
+that immutable proposal; unrelated staged and unstaged work is preserved.
+
+`invalid_change` and known-unapplied `conflict` reject the batch.
+`publication_pending` is retryable and may report `uncertain` or `applied`;
+retry the same change set to reconcile its retained identity. A transport failure
+also keeps that identity. Concurrent publication calls coalesce, confirmed calls
+replay the result, and changed intent requires a new change set. Updates are
+bounded to 10,000 Records and the 256 KiB Data request limit. Create, delete,
+`$filing`, search and history are outside this supported Changes slice.
+
 Bind a declared Airtable connection with `connections.airtable('project-management')`
 from the package root. Import and binding perform no network or credential work.
 The client exposes `tables.list()` and `records.list`, `get`, `create`, `update`