@oddington/sdk 0.1.1 → 0.1.3

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 API work in browsers. Installing the package grants no authority.
 
 ```sh
 npm install @oddington/sdk
@@ -13,6 +14,92 @@ 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`.
+
+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, history or changes operation
+is included. Collection schemas omit Markdown storage hints.
+`DataOperationError.code` distinguishes `context_unavailable`, `unauthenticated`,
+`access_denied`, `invalid_query`, `request_too_large`, `capacity` and `unavailable`.
+Only `capacity` and `unavailable` are retryable; an error never includes private
+server details. Server boundaries own query bounds and authorization.
+
+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`
+and `delete`. Reads allow table names or stable IDs and return all ordered pages;
+writes require a stable table ID and one nonempty batch of at most ten records.
+Operations cannot select another workspace, base, token or provider URL.
+
+```ts
+import { connections } from '@oddington/sdk';
+
+const airtable = connections.airtable('project-management');
+const changed = await airtable.records.update({ table: 'tblContacts', records: [{
+  id: 'recRetained', expected: { Email: 'james@example.com', Company: null },
+  set: { Company: ['recCompany'] },
+}] });
+```
+
+Preserve original reviewed `expected` values. Non-null values must match exactly;
+`null` requires an omitted field key and cannot be used as an update value. Reads
+preserve Airtable's omitted-field shape. Create requires nonempty `fields`, update
+requires nonempty `set`, and untouched fields remain unchanged. Guarded methods
+read before a single batch write; this leaves a concurrency race and provides no
+atomic compare-and-swap, rollback or implicit retry.
+
+Success returns a safe Airtable `receipt` with the connection, configured base,
+table, operation and acknowledged IDs. Create/update also return acknowledged
+records separately. `AirtableOperationError` reports `unapplied`, `partial` or
+`uncertain` effects and known safe `receipts`. Stop after partial or uncertain
+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