@brass-build/client 0.1.0 → 0.3.0

package/docs/streams.md

@@ -2,19 +2,18 @@
 
 A document is a container of **streams**: named units of document
 state that load independently. Opening a document costs only the
-streams your app touches: snapshot download, CRDT import, and memory
-all scale with what you use, not with the document's total size. The
-motivating shape is a multi-discipline design: architectural,
-plumbing, HVAC, and structural as four streams of one document, where
-a plumbing tool opens one of them and pays a quarter of the cost.
-Every stream is collaborative CRDT state.
+streams your app touches, so download, load, and memory scale with what
+you use rather than with the document's total size. Split a
+multi-discipline design into architectural, plumbing, HVAC, and
+structural streams, and a plumbing tool opens one of them. Every stream
+is live, collaborative state that merges the same way the rest of the
+document does.
 
 Every document has a stream named **`default`**, and an open that names
 no stream opens that one, so the doc-level handles (`doc.map(...)`,
-`doc.orderedMap(...)`) read it. An unpartitioned document is just a
-document whose content lives entirely there: nothing about streams needs
-to be known or paid for until you partition. Name another stream on the
-open (below) and the doc-level handles read that one instead.
+`doc.orderedMap(...)`) read it. An unpartitioned document is one whose
+content lives entirely there. Name another stream on the open (below)
+and the doc-level handles read that one instead.
 
 ## Opening and editing a stream
 
@@ -40,37 +39,37 @@ surface scoped to that stream: `map` / `list` / `orderedMap` handles,
 ## Opening at a stream
 
 `Brass.openDocumentById(docId, { stream })` opens the document with that
-stream as its own state, so `doc.map(...)` reads it and the rest of the
-document is never downloaded. An app that works in one part of a large
+stream as its own state, so `doc.map(...)` hands you its records and the rest
+of the document is never downloaded. An app that works in one part of a large
 document pays for that part alone:
 
 ```ts
 const doc = await Brass.openDocumentById(docId, { stream: 'hvac' });
-doc.orderedMap('instances', 'instance_order').read(); // hvac's records
+doc.orderedMap('instances', 'instance_order').subscribe((change) => {
+  for (const [key, record] of change.set) hold(key, record); // hvac's records
+});
 ```
 
 `stream` defaults to `'default'`, the stream every document has, so an
 open always names a stream and the usual one needs no argument.
 `doc.stream(name)` resolves the name the document was opened at back to
 the document itself, with no second join, and any other name to its own
-line. So the loop below reads the same whichever stream you opened at:
+stream, so the loop below reads the same whichever stream you opened at:
 
 ```ts
 for (const info of await doc.listStreams()) {
   const stream = await doc.stream(info.name);
-  summarize(stream.map('instances').read());
+  stream.map('instances').subscribe((change) => summarize(change.set));
 }
 ```
 
-`listStreams()` includes it like any other name, so a loop over the
-manifest needs no separate step for the stream you opened at. Names are
-`a-z 0-9 . _ -`, 1 to 64 chars, starting with a letter or digit, the same
-rule a schema family follows. `default` is
-one of them: every document already holds it, so `getOrCreateStream`
-resolves it without a request, and a loop over the names your schema
-declares needs no case for it. `getOrCreateStream` writes, so a read-only
-open reads with `doc.stream` instead and shows a degraded view when the
-document does not hold the stream.
+Names are `a-z 0-9 . _ -`, 1 to 64 chars, starting with a letter or
+digit, the same rule a schema family follows. `default` is one of them:
+every document already holds it, so `getOrCreateStream` resolves it
+without a request, and a loop over the names your schema declares needs
+no case for it. `getOrCreateStream` writes, so a read-only open reads
+with `doc.stream` instead and shows a degraded view when the document
+does not hold the stream.
 
 ## Undo and editing model
 
@@ -81,9 +80,8 @@ only the default stream.
 
 A stream's local edits group into one undo step until the group is
 **sealed** with `stream.sealUndoStep()`, the same same-stroke
-collapsing doc-level undo gets from checkpoints, exposed directly
-because streams carry no checkpoint machinery. Seal when a user
-operation completes; an app that never seals gets one giant step per
+collapsing doc-level undo gets from checkpoints. Seal when a user
+operation completes. An app that never seals gets one giant step per
 session.
 
 ### Undoing an operation that spans streams
@@ -103,6 +101,8 @@ Two rules make the stacks line up:
    breaks that.
 
 ```ts
+import type { DocumentStream } from '@brass-build/client';
+
 type Op = { label: string; streams: string[] };
 const undoJournal: Op[] = [];
 const redoJournal: Op[] = [];
@@ -159,14 +159,14 @@ Collaborators' edits do not disturb the alignment: undo stacks are
 local-peer-scoped, and each stream's undo rebases your reverted step
 over remote changes the same way single-document undo does.
 
-Two properties to design around rather than against. The cross-stream
-undo is **not atomic**: each stream's revert is its own commit, so a
-collaborator can briefly observe one stream reverted before the other
-(the same window any multi-stream operation has). And the journal is
-**in-memory**: a reload starts it empty, exactly like single-document
-undo. If an operation genuinely cannot tolerate the window, that is
-the signal its data belongs in one stream: partition by load unit, and
-keep records that must change together in the same stream.
+Design around two properties of it. The cross-stream undo is **not
+atomic**: each stream's revert is its own commit, so a collaborator can
+briefly observe one stream reverted before the other (the same window
+any multi-stream operation has). And the journal is **in-memory**: a
+reload starts it empty, exactly like single-document undo. When an
+operation cannot tolerate that window, its data belongs in one stream:
+partition by load unit, and keep records that must change together in
+the same stream.
 
 ## When to partition
 
@@ -174,19 +174,9 @@ Opening a stream costs a request for its snapshot, and the first one on a
 document also reads the stream manifest, so add a stream when it carries
 real content that some opens can skip. Partition by **load unit** (a
 discipline, a heavy layer, a dataset a specific tool reads), not by
-concept. A handful of streams with megabytes each works best; dozens of
-tiny streams make opening everything slower
-than a monolith, and content every open needs belongs in the default
-stream.
-
-Branches and streams compose: creating a branch forks every stream, so a
-branch is fully isolated from its source across all of them, exactly like an
-unpartitioned document, and each forked stream keeps the shape its records
-conform to. Branching from a historical version addresses the default
-stream's timeline; the other streams fork at their current state. Deleting a
-branch deletes its streams with it. Two branches that then diverge in shape
-report different contracts, because a contract belongs to a stream on a
-branch rather than to the document.
+concept. Aim for a handful of streams carrying megabytes each. Dozens
+of tiny streams make opening everything slower than a monolith, and
+content every open needs belongs in the default stream.
 
 ## Reading a document spread across streams
 
@@ -203,21 +193,29 @@ DOCUMENT holds, because a referenced record may live in one the default
 stream does not. `doc.listStreams()` is that list, so merge by id:
 
 ```ts
-const store: Record<string, { type: string; params: unknown }> = {
-  ...doc.orderedMap('instances', 'instance_order').read(),
-};
+import type { OrderedMapHandle } from '@brass-build/client';
+
+type StoredRecord = { type: string; params: unknown };
+const store: Record<string, StoredRecord> = {};
+const fold = (records: OrderedMapHandle<StoredRecord>) =>
+  records.subscribe((change) => {
+    for (const [key, record] of change.set) store[key] = record;
+    for (const key of change.deleted) delete store[key];
+  });
+
+fold(doc.orderedMap<StoredRecord>('instances', 'instance_order'));
 for (const info of await doc.listStreams()) {
   const stream = await doc.stream(info.name);
-  Object.assign(store, stream.orderedMap('instances', 'instance_order').read());
+  fold(stream.orderedMap<StoredRecord>('instances', 'instance_order'));
 }
 // store['#137'] resolves wherever #137 lives.
 ```
 
-The loop opens the stream the document was opened at without a second
-join, so it reads the same for an unpartitioned document as for a split
-one. Open only what you read: an app that needs just the default view's
-records reads the default stream alone; one that resolves references
-reads them all and pays for the streams it opens.
+The loop reads an unpartitioned document the same way it reads a split
+one, so it needs no special case. Open only what you read: an app that
+needs just the default view's records reads the default stream alone,
+and one that resolves references reads them all and pays for the
+streams it opens.
 
 A document can hold streams your schema does not name (computed results,
 review notes, a cache), so the merge above skips them and an exporter that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brass-build/client",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Client SDK for Brass",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,7 +18,8 @@
     "./internal": {
       "types": "./dist/internal.d.ts",
       "import": "./dist/internal.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
@@ -40,7 +41,7 @@
   },
   "dependencies": {
     "fflate": "^0.8.3",
-    "loro-crdt": "^1.12.1"
+    "loro-crdt": "^1.13.0"
   },
   "devDependencies": {
     "typescript": "~6.0.0"

package/src/auth-flow.ts

@@ -1,14 +1,23 @@
 import { SDK_CLIENT_ID } from './version.js';
 import { fetchWithRetry, RETRY_READ, RETRY_WRITE_503 } from './fetch-retry.js';
 
-// Fallback token lifetime if a /refresh response omits `expires_in`. The
-// server always sends it (so this is forward-compat robustness), but without a
-// fallback `Date.now() + undefined * 1000` is NaN, and the client's freshness
-// check `expiresAt - leeway > Date.now()` is then always false, so every
-// getAccessToken() would fire a fresh /refresh round-trip. Mirrors the CLI's
-// same guard.
+// Fallback token lifetime when a /refresh response carries no usable
+// `expires_in`. The server always sends a positive number (so this is
+// forward-compat robustness), and every other value stamps an `expiresAt` the
+// client's freshness check `expiresAt - leeway > Date.now()` can never
+// satisfy: `undefined` and a non-numeric make it NaN, and 0 or a negative
+// makes it already past. Either way every getAccessToken() would fire a fresh
+// /refresh round-trip. Mirrors the CLI's same guard.
 const DEFAULT_TOKEN_TTL_SECONDS = 3600;
 
+// The lifetime to stamp a token set with, given whatever `expires_in` the
+// response carried.
+function tokenTtlSeconds(expiresIn: unknown): number {
+  return typeof expiresIn === 'number' && Number.isFinite(expiresIn) && expiresIn > 0
+    ? expiresIn
+    : DEFAULT_TOKEN_TTL_SECONDS;
+}
+
 export interface TokenSet {
   accessToken: string;
   idToken: string;
@@ -24,9 +33,9 @@ interface RefreshResponse {
   id_token: string;
   expires_in: number;
   app_assertion?: string;
-  // Present only for a fallback-mode request (a `brass_code` exchange or
-  // a `sid` echo): the opaque platform-session pointer the SDK holds in
-  // memory to keep refreshing without the cross-site cookie.
+  // Present only for a fallback-mode request (a `brass_code` exchange or a
+  // `sid` echo): an opaque pointer, bound server-side to this app id, that the
+  // SDK holds in memory to keep refreshing without the cross-site cookie.
   session_token?: string;
 }
 
@@ -52,6 +61,33 @@ export interface RefreshResult {
   sessionToken?: string;
 }
 
+// The result of one /refresh attempt, carrying whether a failure was the
+// server's answer or the absence of one.
+//
+// `no_session`: this credential resolves no live session (revoked, expired,
+// or never approved for this app). The caller signs the user out.
+//
+// `unavailable`: the request threw, or a transient status outlived the
+// retries. Nothing was learned about the session, so the caller keeps the
+// credentials it holds and lets a later attempt settle it. Treating this as
+// `no_session` ends a live session over a momentary network failure.
+export type RefreshOutcome =
+  | { status: 'ok'; result: RefreshResult }
+  | { status: 'no_session' }
+  | { status: 'unavailable' };
+
+// Attempts for a /refresh, raised from `fetchWithRetry`'s default of 3
+// (~0.9s of backoff) so the call outlasts the few-second network gap a
+// machine waking from sleep produces.
+const REFRESH_ATTEMPTS = 5;
+
+// Statuses that mean the request found no answer. A 5xx is in the set
+// because the auth proxy reports an upstream failure as one, so it says
+// nothing about whether the session is live.
+function isTransientStatus(status: number): boolean {
+  return status >= 500 || status === 429 || status === 408;
+}
+
 export function buildSignInUrl(authBaseUrl: string, appId: string, returnTo: string): string {
   const url = new URL(`${authBaseUrl}/sign-in`);
   url.searchParams.set('app_id', appId);
@@ -70,11 +106,38 @@ export function buildSignedOutOfAppUrl(
   return url.toString();
 }
 
+// Drops this app's approval off the platform session, presenting the same
+// credential a refresh does. Never rejects: the sign-out navigation follows
+// either way, and the page it lands on offers the button that finishes a
+// revocation this call could not deliver.
+export async function revokeAppApproval(
+  authBaseUrl: string,
+  appId: string,
+  credential: RefreshCredential = { kind: 'cookie' },
+): Promise<void> {
+  const url = `${authBaseUrl}/sign-out-of-app?${new URLSearchParams({
+    app_id: appId,
+  }).toString()}`;
+  const init: RequestInit = { method: 'POST', credentials: 'include' };
+  if (credential.kind === 'sessionToken') {
+    // A URLSearchParams body keeps this a CORS simple request, as on
+    // /refresh: the auth API serves no preflight OPTIONS.
+    const body = new URLSearchParams();
+    body.set('sid', credential.sessionToken);
+    init.body = body;
+  }
+  try {
+    await fetch(url, init);
+  } catch {
+    // Swallowed on purpose: see above.
+  }
+}
+
 export async function refreshTokens(
   authBaseUrl: string,
   appId: string,
   credential: RefreshCredential = { kind: 'cookie' },
-): Promise<RefreshResult | null> {
+): Promise<RefreshOutcome> {
   // `client` rides a query param, not a header: /refresh is deliberately
   // a CORS simple request (no preflight), and any custom header would
   // trip one. The server folds it into the token_refresh audit so the
@@ -95,31 +158,35 @@ export async function refreshTokens(
     init.body = body;
   }
   // Retry a transient failure (a cold-start 5xx / 429, or a network blip)
-  // rather than collapsing it into the same `null` a definitive 401 returns:
-  // `null` signs the user out and clears the login hint, so without a retry one
-  // hourly-refresh blip tears down a live session that was fine server-side. A
-  // definitive 401/403 is not in either replay set, so it still returns fast.
-  // The one-time `brass_code` exchange is single-use server-side, so its
-  // channel replays ONLY a pre-handler 503 (never a network throw, which might
-  // mean the code was already consumed); the cookie / sid channels are
-  // idempotent and replay the full transient set.
+  // before reporting it. A definitive 401/403 is not in either replay set, so
+  // it still returns fast. The one-time `brass_code` exchange is single-use
+  // server-side, so its channel replays ONLY a pre-handler 503 (never a
+  // network throw, which might mean the code was already consumed); the
+  // cookie / sid channels are idempotent and replay the full transient set.
   const policy = credential.kind === 'code' ? RETRY_WRITE_503 : RETRY_READ;
   let response: Response;
   try {
-    response = await fetchWithRetry(() => fetch(url, init), { policy });
+    response = await fetchWithRetry(() => fetch(url, init), {
+      policy,
+      maxAttempts: REFRESH_ATTEMPTS,
+    });
   } catch {
-    return null;
+    return { status: 'unavailable' };
+  }
+  if (!response.ok) {
+    return isTransientStatus(response.status)
+      ? { status: 'unavailable' }
+      : { status: 'no_session' };
   }
-  if (!response.ok) return null;
   const json = (await response.json()) as RefreshResponse;
   const result: RefreshResult = {
     tokens: {
       accessToken: json.access_token,
       idToken: json.id_token,
-      expiresAt: Date.now() + (json.expires_in ?? DEFAULT_TOKEN_TTL_SECONDS) * 1000,
+      expiresAt: Date.now() + tokenTtlSeconds(json.expires_in) * 1000,
       ...(json.app_assertion ? { appAssertion: json.app_assertion } : {}),
     },
   };
   if (json.session_token) result.sessionToken = json.session_token;
-  return result;
+  return { status: 'ok', result };
 }