@oddington/sdk 0.1.45 → 0.1.47

package/README.md

@@ -246,13 +246,45 @@ try {
 }
 
 os.init({ auth: browserAuth }); // Trusted workspace host startup only.
-// Later: await browserAuth.signOut(); // Ends only this browser's session.
+// Later: await browserAuth.signOut(); // Ends the active session.
 // On document teardown (refresh, navigation or close):
 unsubscribe();
 browserAuth.dispose();
 ```
 
-`auth.create()` accepts no options. Trusted same-origin OS setup selects the
+In a local app started by `os app dev` or `os app launch`, the same handle
+uses the CLI-backed app connection and presents the signed-in viewer:
+
+```ts
+const { status, account } = browserAuth.getState();
+if (status === "signed_in") {
+  // account.email and account.displayName identify this app's current viewer.
+}
+```
+
+Use this account for viewer-aware presentation such as a Mine filter. Subscribe
+to keep that presentation current; it is not an authorization decision. There
+is no Inbox identity call, extra hosted lookup, browser provider session or CLI
+token. The handle and `os.init` share one exact-origin connection. Expiry clears
+account presentation, and same-session renewal restores it. Local sign-out ends
+the host session for its browsers; a failed confirmation reports unavailable.
+Disposal preserves the connection's stored proofs for document refresh. Local
+passcode and consent actions are unavailable: sign in with `os login` first.
+
+In React, consume the handle as an external store so an early auth update cannot
+be missed between rendering and subscribing:
+
+```ts
+import { useSyncExternalStore } from "react";
+
+const authState = useSyncExternalStore(browserAuth.subscribe, browserAuth.getState);
+```
+
+Derive viewer-aware UI from the current `authState.account`; account changes do
+not require refetching the app's records.
+
+At a hosted workspace origin, `auth.create()` accepts no options. Trusted
+same-origin OS setup selects the
 provider internally through exact-origin `GET /api/auth`, owned by OS. The SDK
 uses same-origin credentials, refuses redirects and bypasses caching. Missing or
 invalid setup makes authentication unavailable without a legacy endpoint or
@@ -652,9 +684,10 @@ external edits. Current local Data acquires no hosted binding or index. 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.
+values, expanded forward links and exact opaque public versions. For selected current repositories, cursors
+continue a live keyset position with the same selection; each page reads current.
+Concurrent movement can repeat or skip a Record. Unselected repositories temporarily
+retain their existing exact-version cursors. Repeat options and links while omitting completed collections.
 There is no automatic retry or separate version fetch.
 Collection schemas omit Markdown storage hints.
 
@@ -698,19 +731,22 @@ 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
+prefetches after a consumer stops. Independent collection cursors continue live positions; versions and requested
+counts may change between pages. Completed collections yield empty arrays on later pages and retain
 requested counts. Empty matches yield one versioned page. Helpers own continuation;
 use `query` for a manual `after` cursor or explicit historical query.
 
-`all` consumes the same iterator and returns only after successful exhaustion.
+`all` sends one bounded collection operation. Selected hosted execution uses one
+ordinary database transaction, and local execution reads one captured in-memory
+view. Records, requested counts and version describe that single observation;
+the operation retains no snapshot afterward.
 Its required positive safe-integer `maxRecords` caps top-level Record occurrences
 across all collections; expanded links do not count toward that ceiling. Overflow
 names the queried collections and ceiling, tells the author to narrow the query
 or increase `maxRecords`, and 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`.
+or missing/invalid requested counts use nonretryable `unavailable`.
 Query and authority failures propagate unchanged, with no retry or restart.
 
 Read known stable refs directly, including refs from different collections:
@@ -789,7 +825,7 @@ sees completed Changes writes and external edits. Search Records supply captured
 versions for subsequent Changes. Explicit History keeps its hosted contract.
 
 `where` combines field conditions with AND. Alongside exact scalar/null equality
-and `$in`, declared one-valued `integer`, `number` and `date` fields accept
+and `$in`, declared one-valued `integer`, `number`, `date` and `datetime` fields accept
 `$gt`, `$gte`, `$lt` and `$lte`:
 
 ```ts
@@ -808,6 +844,28 @@ 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.
 
+A `kind: datetime` field is an instant represented as a canonical UTC string
+with milliseconds, for example `2026-09-15T14:30:00.000Z`. OS validates the real
+date/time and exact `YYYY-MM-DDTHH:mm:ss.sssZ` spelling. Invalid dates, offsets,
+missing or excess fractional digits and Date objects reject; values are never
+silently converted or rounded. To convert an instant explicitly, use
+`Date.toISOString()`. Returned values remain strings and equality/ranges/order
+all use the same canonical representation. Existing string fields need an
+explicit schema change to acquire datetime semantics.
+
+The app owns business timezone boundaries. For September 2026 in Europe/London,
+pass the UTC start (inclusive) and next-month start (exclusive):
+
+```ts
+await general.records.query({ emails: { $: { where: {
+  received_at: { $gte: '2026-08-31T23:00:00.000Z', $lt: '2026-09-30T23:00:00.000Z' },
+}, order: { received_at: 'desc' } } } });
+```
+
+This filters metadata in the query engine before returning selected Records;
+the app can then batch-read bodies only for those matches. A calendar `date`
+continues to mean a day/month without a timezone.
+
 `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
@@ -835,7 +893,6 @@ schema fields, in the same guarded change:
 changes.create({ $ref: 'emails/email-123', type: 'email', subject: 'Invoice',
   $body: 'Hello,\n\nPlease find our invoice attached.\n' });
 changes.update(existingEmail, { $body: revisedMarkdown }); // body-only change
-const emails = await general.records.read(emailRefs, { body: true });
 ```
 
 Omitted `$body` on create means empty; omitted on update preserves the existing
@@ -843,16 +900,19 @@ body exactly. A string deliberately replaces it, `''` clears it, and `null` is
 invalid. Body-only edits preserve front matter, field-only edits preserve the
 body, and both share the Record's exact-byte version guard. Bodies round-trip
 without Markdown interpretation, formatting, trimming, or fence semantics.
-Ordinary reads, selections and search stay body-free; explicitly requested
-bodies use the same ordered batch/null-slot shape. Local change batches support
-32 MiB of serialized JSON; hosted requests retain their separate 256 KiB limit.
-Body-enabled read responses are bounded to 8 MiB, with an explicit error
-instead of truncation. Hosted body reads use a protected immutable v3 index;
-older indexes without body coverage are unavailable rather than falsely empty.
+Selections and search return structured fields only. Exact reads remain
+body-free unless they explicitly request the body:
+
+```ts
+const email = await general.records.read('emails/email-123', { body: true });
+console.log(email?.$body);
+```
+
+Local change batches support 32 MiB of serialized JSON; hosted requests retain
+their separate 256 KiB limit.
 
 The customer routine owns content and authoring policy. For imported emails,
-create with the prepared body, omit `$body` on ordinary reruns, and backfill
-only bodies explicitly read as exactly empty. Existing notes and fenced blocks
+create with the prepared body, omit `$body` on ordinary reruns, and preserve existing source bodies on ordinary reruns. Existing notes and fenced blocks
 remain ordinary authored content. A fresh version alone does not authorize
 overwriting an existing nonempty body.