@brass-build/client 0.1.0

package/src/emitter.ts

@@ -0,0 +1,129 @@
+// Internal listener-fanout primitive. One home for the pattern the SDK's
+// subscribe surfaces share: a `Set` of callbacks, an add/delete unsubscribe,
+// an emit loop, and the small per-site knobs (deliver-on-attach, retain the
+// last value, drop duplicate emits, and how a listener's throw is handled).
+// Not exported from `index.ts`: every caller is SDK-internal (the document
+// lifecycle signals, the Document subscriber set, the client's error
+// listeners).
+
+export interface EmitterOptions<T> {
+  // Deliver the retained value to a newly-attached listener, in a microtask,
+  // so a listener wired after the value arrived still sees it once. The
+  // microtask keeps the callsite ordering identical whether the value is
+  // already present or arrives later (the unsubscribe is returned before the
+  // deferred fire runs). Needs a `retain` policy to have a value to deliver.
+  fireOnAttach?: boolean;
+  // Whether the last emitted value is cached:
+  //   'latest'  - cache it; a `fireOnAttach` attach delivers it, and it
+  //               survives `clear()`.
+  //   'oneShot' - cache it and stop after the first emit: later emits are
+  //               dropped, the listener set is cleared once it fires, and a
+  //               later attach delivers the cached value once without
+  //               retaining the listener.
+  retain?: 'latest' | 'oneShot';
+  // Drop an emit whose value equals the retained one (consulted only once a
+  // value is retained), so a source that re-emits on unrelated changes does
+  // not wake listeners when nothing they read moved.
+  equals?: (value: T, retained: T) => boolean;
+  // Called with a listener's thrown error instead of letting it propagate.
+  // Omit to let a throw propagate and abort the emit loop. The three policies
+  // the SDK uses: swallow (`onError: () => {}`), log and continue
+  // (`onError: (e) => console.error(...)`), and propagate (omit).
+  onError?: (err: unknown) => void;
+}
+
+export interface Emitter<T> {
+  // Register a listener; the returned function detaches it. Idempotent detach.
+  on(cb: (value: T) => void): () => void;
+  // Fanout `value` to every listener, applying the retain / dedup / one-shot
+  // policy and the error handling.
+  emit(value: T): void;
+  // Drop all listeners. The retained value (if any) is kept, so a later attach
+  // still delivers it: this matches the signals' `clearListeners`, where a
+  // suspend / close drops app callbacks but a resumed open still reads the
+  // last status.
+  clear(): void;
+  // The last emitted value, or `undefined` if none has been emitted (or the
+  // emitter does not retain). None of the SDK's retained types carry
+  // `undefined` as a meaningful value, so a caller coalesces with `?? null`.
+  readonly retained: T | undefined;
+  readonly size: number;
+}
+
+export function createEmitter<T>(opts: EmitterOptions<T> = {}): Emitter<T> {
+  const { fireOnAttach = false, retain, equals, onError } = opts;
+  const listeners = new Set<(value: T) => void>();
+  const oneShot = retain === 'oneShot';
+  const retains = retain !== undefined;
+  let hasValue = false;
+  let retained: T | undefined;
+
+  const dispatch = (cb: (value: T) => void, value: T): void => {
+    if (onError) {
+      try {
+        cb(value);
+      } catch (err) {
+        onError(err);
+      }
+    } else {
+      cb(value);
+    }
+  };
+
+  return {
+    on(cb) {
+      if (fireOnAttach && hasValue) {
+        if (oneShot) {
+          // A one-shot has already fired for everyone: a late attach gets the
+          // cached value once (in a microtask, so the unsubscribe returns
+          // first) and is not retained. Terminal, so the returned unsubscribe
+          // is a no-op (there is no ongoing subscription to cancel).
+          const value = retained as T;
+          queueMicrotask(() => {
+            dispatch(cb, value);
+          });
+          return () => {};
+        }
+        // Deliver the retained value on attach, in a microtask so the
+        // unsubscribe returns first. Two guards keep the deferred fire honest:
+        // skip it if the listener detached in the meantime (a synchronous
+        // unsubscribe, e.g. a framework effect's immediate cleanup, must not
+        // still receive a value), and deliver the CURRENT retained value
+        // rather than a snapshot taken at attach time, so a value emitted
+        // between attach and flush is not clobbered by a stale one.
+        listeners.add(cb);
+        queueMicrotask(() => {
+          if (!listeners.has(cb)) return;
+          dispatch(cb, retained as T);
+        });
+        return () => {
+          listeners.delete(cb);
+        };
+      }
+      listeners.add(cb);
+      return () => {
+        listeners.delete(cb);
+      };
+    },
+    emit(value) {
+      // A one-shot's first emit is terminal, so drop any later one.
+      if (oneShot && hasValue) return;
+      if (equals && hasValue && equals(value, retained as T)) return;
+      if (retains) {
+        retained = value;
+        hasValue = true;
+      }
+      for (const cb of listeners) dispatch(cb, value);
+      if (oneShot) listeners.clear();
+    },
+    clear() {
+      listeners.clear();
+    },
+    get retained() {
+      return retained;
+    },
+    get size() {
+      return listeners.size;
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,45 @@
+// The single error type every `@brass-build/client` call rejects with.
+//
+// One catch type, two mutually-exclusive discriminators: branch on
+// `.status` for the HTTP surface, `.code` for the hosted-UI launchers (an
+// HTTP rejection has no `code`, a launcher rejection no `status`).
+//   - `iframe_unavailable`: this browser / app context can't host the
+//     iframe (an app surfaces this as "open in a new tab").
+//   - `embed_error`: the embed page cannot proceed (e.g. not signed in).
+//   - `not_in_browser`: a non-DOM runtime.
+//   - `app_not_installed`: the server rejected the app's action because
+//     the target organization has no install of it; `organizationId`
+//     names the org so the install-consent flow can be offered.
+export type BrassErrorCode =
+  | 'not_in_browser'
+  | 'iframe_unavailable'
+  | 'embed_error'
+  | 'app_not_installed'
+  | 'schema_conflict';
+
+export class BrassError extends Error {
+  override name = 'BrassError';
+  readonly status?: number;
+  readonly code?: BrassErrorCode;
+  readonly organizationId?: string;
+  /** Server-authored heading for a prompt this error drives, when the
+   *  platform sends one. A client freezes into an app's bundle, so a string
+   *  it holds itself can only be corrected by every app republishing. */
+  readonly title?: string;
+
+  constructor(
+    message: string,
+    init?: {
+      status?: number;
+      code?: BrassErrorCode;
+      organizationId?: string;
+      title?: string;
+    },
+  ) {
+    super(message);
+    if (init?.status !== undefined) this.status = init.status;
+    if (init?.code !== undefined) this.code = init.code;
+    if (init?.organizationId !== undefined) this.organizationId = init.organizationId;
+    if (init?.title !== undefined) this.title = init.title;
+  }
+}

package/src/export-guest.ts

@@ -0,0 +1,282 @@
+// Export-guest: the app side of platform-initiated export when no app is
+// already framing the document. The standalone dashboard and the
+// drive-push path have no live app, so Brass loads the app's own bundle
+// in a hidden iframe with the export-mode URL flag, hands it the
+// document snapshot, and asks it to serialize. The roles invert from the
+// usual hosted-UI case (see `hosted-ui.ts`): Brass is the framer (host)
+// and the app's SDK is the guest.
+//
+// The guest never authenticates and never calls the API: it serializes
+// the handed-in snapshot, so a partitioned auth cookie in the framed
+// context is irrelevant. Reuses the `__brass_embed` envelope and the
+// `export-request` / `export-result` pair with the direction flipped
+// (framer -> guest carries the snapshot; guest -> framer the bytes).
+
+import { Document } from './documents.js';
+import type { DocumentStreamInfo } from './documents-namespace.js';
+import type { StreamRuntime } from './document-streams.js';
+import type { DocumentSerializer } from './serializer.js';
+
+const ENVELOPE = '__brass_embed';
+const PROTOCOL_VERSION = 1;
+
+// The URL flag Brass appends when it frames an app purely to serialize.
+// A normal app load never carries it, so a real user visit is untouched.
+export const EXPORT_MODE_PARAM = '__brass_export';
+
+// How long to wait for a late `registerSerializer` before answering
+// `no_serializer`, so the framer falls back to the server export without
+// waiting out its own longer timeout. Generous enough for an app doing
+// async setup before it registers.
+const SERIALIZER_WAIT_MS = 10_000;
+
+// How long a single proxied stream fetch (manifest or line snapshot) waits
+// on the framer before rejecting, so a serializer awaiting `doc.stream()`
+// during a headless export cannot hang past the framer's own export budget.
+const STREAM_REQUEST_TIMEOUT_MS = 20_000;
+
+// Search string passed in so this is pure and testable.
+export function isExportMode(search: string): boolean {
+  return new URLSearchParams(search).has(EXPORT_MODE_PARAM);
+}
+
+export interface ExportGuestController {
+  // `Brass.registerSerializer` forwards here so a serializer registered
+  // after the snapshot arrives still completes the export.
+  setSerializer(serializer: DocumentSerializer): void;
+  dispose(): void;
+}
+
+interface PendingRequest {
+  requestId: string;
+  // The document being serialized, so `doc.id` reads the same here as it
+  // does when the serializer runs against a live open. A serializer that
+  // writes the document id into its output is doing an ordinary thing, and
+  // it would otherwise get a real id on one export path and null on the
+  // other. Absent from an older framer's request, where it stays null.
+  docId: string | null;
+  // The sealed snapshot bytes, or null for a doc with no snapshot yet.
+  snapshot: Uint8Array | null;
+  // Tail op blobs since the snapshot, ordered by seq. Applying them over
+  // the snapshot matches what a live open sees, so the export reflects
+  // the user's latest edits, not the last sealed snapshot.
+  tailOps: Uint8Array[];
+  hostOrigin: string;
+}
+
+// Start listening as a framed export guest. Called from `Brass.init`
+// only when `isExportMode(location.search)` is true.
+export function startExportGuest(): ExportGuestController {
+  let serializer: DocumentSerializer | null = null;
+  let pending: PendingRequest | null = null;
+  let done = false;
+  let waitTimer: ReturnType<typeof setTimeout> | undefined;
+
+  // In-flight proxied stream fetches, keyed by requestId. A serializer that
+  // opens a partitioned document's streams (`doc.stream(name)`) resolves
+  // them over the bridge: the framer has the auth to fetch each stream's
+  // manifest + line snapshot, the detached guest does not.
+  const pendingStreamFetches = new Map<
+    string,
+    {
+      resolve: (value: unknown) => void;
+      reject: (error: Error) => void;
+      timer: ReturnType<typeof setTimeout>;
+    }
+  >();
+  let streamRequestSeq = 0;
+
+  // Ask the framer for stream data over the bridge and await its reply.
+  // Rejects on timeout so a serializer cannot hang past the framer's export
+  // budget (the framer then falls back / reports the failure).
+  function fetchFromFramer(
+    hostOrigin: string,
+    type: 'stream-list-request' | 'stream-snapshot-request',
+    extra: Record<string, unknown>,
+  ): Promise<unknown> {
+    const requestId = `str_${(streamRequestSeq += 1)}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingStreamFetches.delete(requestId);
+        reject(new Error('Timed out fetching stream data from the export host.'));
+      }, STREAM_REQUEST_TIMEOUT_MS);
+      pendingStreamFetches.set(requestId, { resolve, reject, timer });
+      window.parent.postMessage(
+        { [ENVELOPE]: PROTOCOL_VERSION, type, requestId, ...extra },
+        hostOrigin,
+      );
+    });
+  }
+
+  // A StreamRuntime whose list / openLine are served by the framer, so the
+  // detached export Document opens streams without any network of its own.
+  // create() is refused: an export is read-only.
+  function makeStreamRuntime(hostOrigin: string): StreamRuntime {
+    return {
+      list: async () => {
+        const res = (await fetchFromFramer(
+          hostOrigin,
+          'stream-list-request',
+          {},
+        )) as { streams: DocumentStreamInfo[] };
+        return res.streams;
+      },
+      openLine: async (lineId: string) => {
+        const res = (await fetchFromFramer(hostOrigin, 'stream-snapshot-request', {
+          lineId,
+        })) as { snapshot: Uint8Array | null; tailOps: Uint8Array[] };
+        const inner = res.snapshot
+          ? Document.openFromSnapshot(res.snapshot)
+          : Document.create();
+        for (const op of res.tailOps) inner.applyRemoteOp(op);
+        return inner;
+      },
+      create: () => {
+        throw new Error('Cannot create a stream during a headless export.');
+      },
+    };
+  }
+
+  function reply(
+    hostOrigin: string,
+    requestId: string,
+    outcome:
+      | { ok: true; bytes: Uint8Array }
+      | { ok: false; code: string; message: string },
+  ): void {
+    window.parent.postMessage(
+      { [ENVELOPE]: PROTOCOL_VERSION, type: 'export-result', requestId, ...outcome },
+      hostOrigin,
+    );
+  }
+
+  async function run(): Promise<void> {
+    if (done || !pending || !serializer) return;
+    done = true;
+    if (waitTimer !== undefined) clearTimeout(waitTimer);
+    const { hostOrigin, requestId, docId, snapshot, tailOps } = pending;
+    const identity = docId !== null ? { docId } : {};
+    try {
+      // A detached, in-memory Document over the snapshot + tail: the
+      // serializer reads records as it would from a live open, and its
+      // default-stream reads touch nothing. A serializer that opens a
+      // partitioned document's other streams (`doc.stream(name)`) resolves
+      // them over the bridge through the runtime below, so a partitioned
+      // document exports in full headless, not just its default stream.
+      const doc = snapshot
+        ? Document.openFromSnapshot(snapshot, identity)
+        : Document.create(identity);
+      for (const op of tailOps) doc.applyRemoteOp(op);
+      doc.setStreamRuntime(makeStreamRuntime(hostOrigin));
+      const bytes = await serializer(doc);
+      reply(hostOrigin, requestId, { ok: true, bytes });
+    } catch (err) {
+      reply(hostOrigin, requestId, {
+        ok: false,
+        code: 'serializer_failed',
+        message: err instanceof Error ? err.message : 'Serializer failed.',
+      });
+    }
+  }
+
+  function onMessage(event: MessageEvent): void {
+    const data = event.data as Record<string, unknown> | null;
+    if (!data || data[ENVELOPE] !== PROTOCOL_VERSION) return;
+
+    // A reply to a proxied stream fetch. Accept only from the pinned framer
+    // origin (set once the export request arrives), so a second frame cannot
+    // feed the serializer forged stream bytes.
+    if (
+      data['type'] === 'stream-list-result' ||
+      data['type'] === 'stream-snapshot-result'
+    ) {
+      if (!pending || event.origin !== pending.hostOrigin) return;
+      const requestId = data['requestId'];
+      if (typeof requestId !== 'string') return;
+      const fetch = pendingStreamFetches.get(requestId);
+      if (!fetch) return;
+      pendingStreamFetches.delete(requestId);
+      clearTimeout(fetch.timer);
+      if (data['ok'] === true) {
+        if (data['type'] === 'stream-list-result') {
+          fetch.resolve({
+            streams: Array.isArray(data['streams']) ? data['streams'] : [],
+          });
+        } else {
+          fetch.resolve({
+            snapshot: data['snapshot'] instanceof Uint8Array ? data['snapshot'] : null,
+            tailOps: Array.isArray(data['tailOps'])
+              ? data['tailOps'].filter((op) => op instanceof Uint8Array)
+              : [],
+          });
+        }
+      } else {
+        fetch.reject(
+          new Error(
+            typeof data['message'] === 'string'
+              ? data['message']
+              : 'The export host could not provide the stream.',
+          ),
+        );
+      }
+      return;
+    }
+
+    if (data['type'] !== 'export-request') return;
+    // First framer to send a request wins; pin its origin so a second
+    // frame cannot answer or observe.
+    if (pending !== null) return;
+    const requestId = data['requestId'];
+    const docId = data['docId'];
+    const snapshot = data['snapshot'];
+    const tailOps = data['tailOps'];
+    if (typeof requestId !== 'string') return;
+    if (snapshot !== null && !(snapshot instanceof Uint8Array)) return;
+    if (!Array.isArray(tailOps) || !tailOps.every((op) => op instanceof Uint8Array)) {
+      return;
+    }
+    pending = {
+      requestId,
+      docId: typeof docId === 'string' && docId !== '' ? docId : null,
+      snapshot,
+      tailOps,
+      hostOrigin: event.origin,
+    };
+    // If no serializer yet, wait briefly then answer `no_serializer` so
+    // the framer falls back to the server export.
+    if (serializer) {
+      void run();
+    } else {
+      waitTimer = setTimeout(() => {
+        if (done || !pending) return;
+        done = true;
+        reply(pending.hostOrigin, pending.requestId, {
+          ok: false,
+          code: 'no_serializer',
+          message: 'No serializer registered.',
+        });
+      }, SERIALIZER_WAIT_MS);
+    }
+  }
+
+  window.addEventListener('message', onMessage);
+  // Announce readiness. Posted with `'*'` because the host origin is not
+  // known until its first message arrives; the ping carries no data.
+  window.parent.postMessage({ [ENVELOPE]: PROTOCOL_VERSION, type: 'ready' }, '*');
+
+  return {
+    setSerializer(next: DocumentSerializer): void {
+      serializer = next;
+      if (pending) void run();
+    },
+    dispose(): void {
+      window.removeEventListener('message', onMessage);
+      if (waitTimer !== undefined) clearTimeout(waitTimer);
+      for (const fetch of pendingStreamFetches.values()) {
+        clearTimeout(fetch.timer);
+        fetch.reject(new Error('Export guest disposed.'));
+      }
+      pendingStreamFetches.clear();
+    },
+  };
+}

package/src/fetch-retry.ts

@@ -0,0 +1,119 @@
+// Bounded transient-retry for HTTP requests, with the replay policy as an
+// explicit argument so the read path and the one write path we replay share
+// a single implementation instead of hand-rolling a loop per call site.
+//
+// A cold Brass API container can reject a request at the gateway with a
+// transient 5xx (503 while the API scales into a concurrent burst, 502 /
+// 504 on a cold-start blip) or 429 (a short rate spike). These are not
+// the caller's error and clear within a second or two, so a single hard
+// failure on a document open reads as "the app is broken" when a brief
+// wait-and-retry would have succeeded.
+//
+// What is safe to replay depends on whether the request is idempotent,
+// which is why the policy is a parameter rather than a constant:
+//
+// - A GET is idempotent, so replaying it is always safe: retry the whole
+//   transient 5xx / 429 set AND a thrown network error (`RETRY_READ`).
+// - A write is NOT idempotent, so only a 503 is safe to replay: the API
+//   gateway returns a 503 BEFORE the request reaches the handler (a transient
+//   throttle / scale-up / deploy-window blip), so the write never ran and
+//   a replay cannot double-apply it. A 502 / 504 / 429 or a network throw
+//   might mean the handler ran, so those stay hard failures (`RETRY_WRITE_503`).
+// - A 500 is never retried under either policy: an unhandled server error
+//   is usually deterministic, so a replay just doubles the cost without
+//   changing the outcome.
+// A 4xx other than 429 (403 app_not_installed, 404) is a definitive answer
+// and is never in a policy's replay set.
+
+export interface RetryPolicy {
+  // HTTP statuses whose response is replayed rather than returned.
+  replayStatuses: ReadonlySet<number>;
+  // Whether a thrown network error (DNS, connection reset, TLS) is replayed.
+  // Safe only for an idempotent request: a throw on a write might mean the
+  // handler ran, so a write policy leaves this false.
+  replayNetworkErrors: boolean;
+}
+
+// Idempotent GET: replay the full transient set and network throws.
+export const RETRY_READ: RetryPolicy = {
+  replayStatuses: new Set([429, 502, 503, 504]),
+  replayNetworkErrors: true,
+};
+
+// Non-idempotent write: replay ONLY a pre-handler 503, never a network throw.
+export const RETRY_WRITE_503: RetryPolicy = {
+  replayStatuses: new Set([503]),
+  replayNetworkErrors: false,
+};
+
+// Idempotent write: replay the full transient set AND a network throw, exactly
+// like a read. Safe only when the request carries a STABLE idempotency key the
+// server dedupes on, so a replay the handler already applied returns the
+// original result instead of applying twice. This is what lets document create
+// stop assuming a 503 is always pre-handler (`RETRY_WRITE_503`'s constraint):
+// with a key, even a post-handler 503 or a network throw is replay-safe.
+export const RETRY_IDEMPOTENT_WRITE: RetryPolicy = {
+  replayStatuses: new Set([429, 502, 503, 504]),
+  replayNetworkErrors: true,
+};
+
+export interface RetryOptions {
+  // Which statuses / throws replay. Defaults to the idempotent read policy.
+  policy?: RetryPolicy;
+  // Total attempts including the first. Default 3 (so up to 2 replays).
+  maxAttempts?: number;
+  // Base backoff; attempt N waits ~base * 2^(N-1) with jitter. Default 300.
+  baseDelayMs?: number;
+  // Invoked before each replay with the 1-based attempt that just failed and
+  // the response (absent on a network throw). For diagnostics only.
+  onRetry?: (attempt: number, response: Response | undefined) => void;
+  // Injected for tests; defaults to the real timer.
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+// Run `doFetch` (which performs one request) up to `maxAttempts` times,
+// replaying per `policy` with exponential backoff plus jitter between tries.
+// Returns the last Response (replayable or not) so the caller keeps its own
+// status handling; rethrows the last network error only if the policy replays
+// throws and every attempt threw. A network throw the policy does not replay
+// propagates immediately.
+export async function fetchWithRetry(
+  doFetch: () => Promise<Response>,
+  options: RetryOptions = {},
+): Promise<Response> {
+  const policy = options.policy ?? RETRY_READ;
+  const maxAttempts = options.maxAttempts ?? 3;
+  const baseDelayMs = options.baseDelayMs ?? 300;
+  const sleep = options.sleep ?? defaultSleep;
+
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    let response: Response | undefined;
+    try {
+      response = await doFetch();
+    } catch (err) {
+      // A network-level throw is only replayable for an idempotent request;
+      // a write policy rethrows it rather than risk a double-apply.
+      if (!policy.replayNetworkErrors) throw err;
+      lastError = err;
+    }
+    if (response && !policy.replayStatuses.has(response.status)) {
+      return response;
+    }
+    if (attempt === maxAttempts) {
+      if (response) return response;
+      throw lastError;
+    }
+    options.onRetry?.(attempt, response);
+    // Exponential backoff with jitter so a burst of clients that all
+    // failed together do not re-collide on the same retry tick.
+    const backoff = baseDelayMs * 2 ** (attempt - 1);
+    const jitter = Math.random() * baseDelayMs;
+    await sleep(backoff + jitter);
+  }
+  // Unreachable: the loop returns or throws on the final attempt.
+  throw lastError ?? new Error('fetchWithRetry: no attempts made');
+}

package/src/guest-link.ts

@@ -0,0 +1,14 @@
+// The anonymous "anyone with the link" boot signal. When Brass routes a
+// no-sign-in share link into an app, it appends `?brass_link=<token>` to
+// the app's URL. `Brass.init` reads it here and opens the document
+// read-only through the token (`GET /links/:token/view`), with no sign-in.
+//
+// Pure + search-string-in so it stays testable, mirroring
+// `isExportMode(search)`.
+
+export const GUEST_LINK_PARAM = 'brass_link';
+
+export function readGuestLinkToken(search: string): string | null {
+  const value = new URLSearchParams(search).get(GUEST_LINK_PARAM);
+  return value && value.trim() !== '' ? value : null;
+}