@brass-build/client 0.1.0

package/src/importer.ts

@@ -0,0 +1,89 @@
+import type { Document } from './documents.js';
+import type { DocumentSourceBlob } from './documents-namespace.js';
+import { BrassError } from './errors.js';
+
+// The app's import half for a file Brass does not parse: given the stored
+// source file and the open document, parse the bytes and write the records
+// through the ordinary handles. Register one at boot with
+// `Brass.registerImporter`, beside `Brass.registerSerializer`.
+//
+// The SDK drives the protocol: on each open it asks the platform for the
+// import claim, and only the winning client fetches the source and runs
+// the importer. Every other open client receives the records through its
+// normal subscription, and completing the import stamps the document with
+// the app's declared schema.
+export type DocumentImporter = (
+  source: DocumentSourceBlob,
+  doc: Document,
+) => void | Promise<void>;
+
+// Wire shape of `POST /documents/:docId/import-claim`'s 200 responses.
+// `claimed` marks the CAS win; `already_imported` carries the stamped
+// provenance of a finished import. A pending claim by another client
+// arrives as a 409 `BrassError` instead.
+export interface ImportClaimResponse {
+  claimed?: boolean;
+  already_imported?: boolean;
+  schema_ref?: { app_id: string; schema_hash: string };
+}
+
+export interface ImportRunnerDeps {
+  claimImport(docId: string): Promise<ImportClaimResponse>;
+  completeImport(docId: string): Promise<unknown>;
+  reportError(error: Error): void;
+}
+
+export interface ImportRunner {
+  setImporter(importer: DocumentImporter): void;
+  attempt(doc: Document): Promise<void>;
+}
+
+// Runs the import protocol for one opened document: claim, and on the
+// win fetch + parse + complete. Separated from the client so the
+// protocol is testable against mocked HTTP deps.
+export function createImportRunner(deps: ImportRunnerDeps): ImportRunner {
+  let importer: DocumentImporter | null = null;
+  // One attempt per Document instance; a reopen mints a new instance,
+  // whose claim resolves `already_imported` as a no-op.
+  const attempted = new WeakSet<Document>();
+  return {
+    setImporter(fn: DocumentImporter): void {
+      importer = fn;
+    },
+    async attempt(doc: Document): Promise<void> {
+      if (importer === null || doc.id === null || attempted.has(doc)) return;
+      attempted.add(doc);
+      const run = importer;
+      const docId = doc.id;
+      let claim: ImportClaimResponse;
+      try {
+        claim = await deps.claimImport(docId);
+      } catch (err) {
+        // The common no-op outcomes arrive as 4xx: not a stored source
+        // file, read-only access, another client's claim in flight. Only
+        // a server fault surfaces.
+        if (err instanceof BrassError && err.status !== undefined && err.status < 500) {
+          return;
+        }
+        deps.reportError(asError(err));
+        return;
+      }
+      if (claim.claimed !== true) return;
+      // This client won the claim: run the importer, then report
+      // completion so the platform stamps the document with the app's
+      // schema. A throw leaves the claim to expire, so another client
+      // can retry rather than the document staying half-claimed.
+      try {
+        const source = await doc.sourceBlob();
+        await run(source, doc);
+        await deps.completeImport(docId);
+      } catch (err) {
+        deps.reportError(asError(err));
+      }
+    },
+  };
+}
+
+function asError(err: unknown): Error {
+  return err instanceof Error ? err : new Error(String(err));
+}

package/src/index.ts

@@ -0,0 +1,267 @@
+import { BrassClient } from './client.js';
+import type {
+  CreateDocumentOptions,
+  OpenDocumentByIdOptions,
+  OpenedDocument,
+} from './open-document.js';
+import type { SelectDocumentResult } from './hosted-ui.js';
+import type { DocumentsNamespace } from './documents-namespace.js';
+import type { DocumentImporter } from './importer.js';
+import type { DocumentSerializer } from './serializer.js';
+import type { DocumentSession } from './session.js';
+import type {
+  AuthStatus,
+  ErrorListener,
+  BrassInitOptions,
+  BrassUser,
+  UserChangeListener,
+} from './types.js';
+
+export type {
+  AuthStatus,
+  ErrorListener,
+  BrassInitOptions,
+  BrassUser,
+  UserChangeListener,
+};
+export { BrassError, type BrassErrorCode } from './errors.js';
+export {
+  type AcquireOrganizationResult,
+  type HostedUiLauncher,
+  type HostedUiLauncherOptions,
+  type HostedUiTheme,
+  type SelectDocumentResult,
+} from './hosted-ui.js';
+export {
+  type DocumentMember,
+  type DocumentRecord,
+  type DocumentRole,
+  type DocumentCheckpoint,
+  type DocumentSourceBlob,
+  type DocumentSourceStream,
+  type DocumentStreamInfo,
+  type DocumentSummary,
+  type DocumentThumbnail,
+  type DocumentsNamespace,
+  type GetThumbnailOptions,
+  type SetThumbnailInput,
+} from './documents-namespace.js';
+export {
+  type CanvasSource,
+  type Command,
+  type CommandGroup,
+  type CommandSurface,
+  type DocumentSession,
+  type DocumentSessionDeps,
+  type SessionOpenOptions,
+  type SessionStatus,
+} from './session.js';
+export type {
+  SessionToolbarHandle,
+  SessionHeaderHandle,
+  SessionToolbarOptions,
+  MountedPiece,
+} from './session-toolbar.js';
+import type {
+  SessionToolbarHandle,
+  SessionHeaderHandle,
+  SessionToolbarOptions,
+  MountedPiece,
+} from './session-toolbar.js';
+export {
+  Document,
+  type DocumentMutator,
+  type DocumentOptions,
+  type DocumentSubscriber,
+  type SyntheticSubscribeEvent,
+  type DocumentUnsubscribe,
+  type DocumentGoneListener,
+  type DocumentGoneReason,
+  type DocumentGoneUnsubscribe,
+  type DocumentWorkStatus,
+  type DocumentStatusListener,
+  type DocumentStatusUnsubscribe,
+  type DocumentDriveStatus,
+  type DocumentDriveStatusListener,
+  type DocumentDriveStatusUnsubscribe,
+  type DocumentDriveTrackingState,
+  type DriveMirrorDirection,
+  type EntityProxy,
+  type UndoState,
+  type UndoStateSubscriber,
+} from './documents.js';
+export type {
+  Change,
+  ChangeOrigin,
+  ChangeSource,
+  HandleUnsubscribe,
+  ListHandle,
+  ListSubscriber,
+  MapHandle,
+  MapSubscriber,
+  OrderedMapHandle,
+} from './handles.js';
+export type { UndoControllerOptions } from './undo.js';
+export type { DocumentSerializer } from './serializer.js';
+export type { DocumentImporter } from './importer.js';
+export { DocumentStream, type StreamRuntime } from './document-streams.js';
+export {
+  type CreateDocumentFn,
+  type CreateDocumentOptions,
+  type DocumentAtVersionResponse,
+  type DocumentDriveSummaryWire,
+  type DocumentFactory,
+  type DocumentSnapshotResponse,
+  type OpenDocumentFactoryOptions,
+  type OpenDocumentByIdFn,
+  type OpenDocumentByIdOptions,
+  type OpenDocumentWsClient,
+  type OpenedDocument,
+} from './open-document.js';
+export type {
+  PresenceChangeListener,
+  PresenceClient,
+  PresenceParticipant,
+  PresenceSetInput,
+  PresenceState,
+} from './presence.js';
+
+const client = new BrassClient();
+
+// A Brass-hosted bundle (`*.onbrass.app`) resolves its app id and
+// environment from the serving slot, so it uses the zero-argument form;
+// everywhere else the app id is required.
+function init(options?: BrassInitOptions): Promise<void>;
+function init(appId: string, options?: BrassInitOptions): Promise<void>;
+function init(
+  appIdOrOptions?: string | BrassInitOptions,
+  options?: BrassInitOptions,
+): Promise<void> {
+  if (typeof appIdOrOptions === 'string') return client.init(appIdOrOptions, options);
+  return client.init(undefined, appIdOrOptions);
+}
+
+export const Brass = {
+  init,
+  signIn(): void {
+    client.signIn();
+  },
+  signOut(): void {
+    client.signOut();
+  },
+  get user(): BrassUser | null {
+    return client.currentUser;
+  },
+  // Tri-state auth lifecycle: `'unknown'` until `Brass.init` settles,
+  // then `'signed-in'` / `'signed-out'`. Gate the sign-in CTA on this,
+  // not on `!Brass.user`: a falsy `user` during `'unknown'` is "not
+  // checked yet", so gating on `!user` flashes the CTA at signed-in
+  // users on reload. Render the CTA only on `'signed-out'`.
+  get authStatus(): AuthStatus {
+    return client.authStatus;
+  },
+  onUserChange(listener: UserChangeListener): () => void {
+    return client.onUserChange(listener);
+  },
+  onError(listener: ErrorListener): () => void {
+    return client.onError(listener);
+  },
+  getAccessToken(): Promise<string | null> {
+    return client.getAccessToken();
+  },
+  // Metadata read for a known id (`get`) plus thumbnails / branches /
+  // pushToDrive. Create / move / list / grant access are hosted-only.
+  get documents(): DocumentsNamespace {
+    return client.documents;
+  },
+  // The document session: owns the active-document lifecycle and exposes
+  // a flat command list to render. Accessible before `Brass.init` so a
+  // boot flow can subscribe first.
+  get session(): DocumentSession {
+    return client.session;
+  },
+  // SDK-rendered document toolbar: file menu, title, location, account
+  // menu, presence roster into `container`. The app fills the returned
+  // `tools` slot with its own buttons.
+  mountToolbar(
+    container: HTMLElement,
+    options?: SessionToolbarOptions,
+  ): SessionToolbarHandle {
+    return client.mountToolbar(container, options);
+  },
+  // The bare header shell, for an app that wants the SDK's responsive
+  // layout but fills the clusters itself. Mount pieces into the returned
+  // `start` / `tools` / `end` slots; the account avatar in `end` stays
+  // pinned top-right on mobile, never wrapping when the tools wrap.
+  mountHeader(container: HTMLElement): SessionHeaderHandle {
+    return client.mountHeader(container);
+  },
+  // Composable header pieces, for an app that builds its own shell and
+  // wants the standard clusters (account menu / presence / title / file
+  // menu / undo-redo) without the whole `mountToolbar` bar. Each renders
+  // one cluster and returns `{ destroy(): void }`.
+  mountFileMenu(container: HTMLElement): MountedPiece {
+    return client.mountFileMenu(container);
+  },
+  mountDocumentTitle(container: HTMLElement): MountedPiece {
+    return client.mountDocumentTitle(container);
+  },
+  mountUndoRedo(container: HTMLElement): MountedPiece {
+    return client.mountUndoRedo(container);
+  },
+  mountPresenceRoster(container: HTMLElement): MountedPiece {
+    return client.mountPresenceRoster(container);
+  },
+  mountDriveSync(container: HTMLElement): MountedPiece {
+    return client.mountDriveSync(container);
+  },
+  mountAccountMenu(container: HTMLElement): MountedPiece {
+    return client.mountAccountMenu(container);
+  },
+  // The historical-version preview banner (return-to-live during a hosted
+  // `history` preview). `mountToolbar` / `mountHeader` already include it, so
+  // this is only for an app that builds fully custom chrome.
+  mountVersionPreview(container: HTMLElement): MountedPiece {
+    return client.mountVersionPreview(container);
+  },
+  selectDocument(): Promise<SelectDocumentResult | null> {
+    return client.selectDocument();
+  },
+  // Opens the hosted multi-tier share dialog (document / project /
+  // organization in one UI) focused on the given document.
+  shareDocument(docId: string): Promise<void> {
+    return client.shareDocument(docId);
+  },
+  openDocumentById(
+    docId: string,
+    options?: OpenDocumentByIdOptions,
+  ): Promise<OpenedDocument> {
+    return client.openDocumentById(docId, options);
+  },
+  // `true` when the page was opened as an anonymous link guest
+  // (`?brass_link=`): no signed-in user, a read-only document. Apps render
+  // their working surface for a guest as they do for a signed-in user (the
+  // document is read-only) and show their sign-in CTA only when neither.
+  get isGuest(): boolean {
+    return client.isGuest;
+  },
+  createDocument(options?: CreateDocumentOptions): Promise<OpenedDocument> {
+    return client.createDocument(options);
+  },
+  // Register the app's export backend: serialises a blob document back
+  // to its source file's bytes. The platform calls it when a user
+  // downloads from a hosted surface (the app never initiates export).
+  // Call once at boot; an app with no serializer cannot export blobs.
+  registerSerializer(serializer: DocumentSerializer): void {
+    client.registerSerializer(serializer);
+  },
+  // Register the app's import backend: parses a stored source file into
+  // the document's records. Brass runs it when a document's file needs
+  // importing; the records reach every open client live. Call once at
+  // boot beside `registerSerializer`.
+  registerImporter(importer: DocumentImporter): void {
+    client.registerImporter(importer);
+  },
+};
+
+export default Brass;

package/src/init-keys.ts

@@ -0,0 +1,15 @@
+// Single source of truth for the set of keys an integration needs to
+// plug into `Brass.init`. When you add a new field to `Brass.init`,
+// add the key here first.
+
+// Keys used in the prompt block the dashboard renders. The `app_id`
+// line carries the app-specific id; the URL lines carry the env's
+// auth / data / WS origins.
+export const BRASS_INIT_ARG_KEYS = [
+  'app_id',
+  'auth_base_url',
+  'api_base_url',
+  'ws_base_url',
+] as const;
+
+export type BrassInitArgKey = (typeof BRASS_INIT_ARG_KEYS)[number];

package/src/internal.ts

@@ -0,0 +1,23 @@
+// The entry point Brass's own surfaces import
+// (`@brass-build/client/internal`).
+//
+// The dashboard, the operator console, and this package's tests consume
+// the SDK as their client library and reach for primitives that sit
+// below the `Brass` namespace: the client class that namespace wraps,
+// the WS transport, the auth-flow helpers, and the init-key vocabulary
+// the dashboard quickstart renders. They live on their own subpath so
+// the default import (`@brass-build/client`) offers apps the `Brass`
+// surface the README documents, and an assistant scaffolding from that
+// README stays on it.
+
+export { BrassClient } from './client.js';
+export { BrassWsClient } from './ws-client.js';
+export {
+  buildSignInUrl,
+  refreshTokens,
+  type RefreshCredential,
+  type RefreshResult,
+  type TokenSet,
+} from './auth-flow.js';
+export { decodeIdToken } from './jwt.js';
+export { BRASS_INIT_ARG_KEYS, type BrassInitArgKey } from './init-keys.js';

package/src/jwt.ts

@@ -0,0 +1,18 @@
+import type { BrassUser } from './types.js';
+
+export function decodeIdToken(idToken: string): BrassUser | null {
+  const parts = idToken.split('.');
+  if (parts.length !== 3) return null;
+  const payloadPart = parts[1];
+  if (!payloadPart) return null;
+  try {
+    const json = atob(payloadPart.replace(/-/g, '+').replace(/_/g, '/'));
+    const claims = JSON.parse(json) as { sub?: unknown; email?: unknown };
+    if (typeof claims.sub !== 'string') return null;
+    const user: BrassUser = { sub: claims.sub };
+    if (typeof claims.email === 'string') user.email = claims.email;
+    return user;
+  } catch {
+    return null;
+  }
+}

package/src/launch-context.ts

@@ -0,0 +1,43 @@
+// The organization a launch came from. Brass appends
+// `?brass_org=<organization_id>` to the app URL it opens from an
+// organization's dashboard, so the first document an app creates lands in
+// the organization the person was standing in when they clicked Open. A
+// member of several organizations has already answered "which one" with
+// that click; without the parameter the create reaches the server with no
+// destination and comes back asking again.
+//
+// `brass_` prefixed like the platform's other boot parameters so it cannot
+// collide with an app's own query string, and stripped from the address bar
+// on read so it does not linger in history or a referrer.
+//
+// The dashboard writes this parameter in `src/lib/open-app-url.ts`; the
+// published SDK cannot import the workspace, so the name is spelled in both
+// places.
+
+export const LAUNCH_ORGANIZATION_PARAM = 'brass_org';
+
+// Pure + search-string-in so it stays testable, mirroring
+// `readGuestLinkToken(search)`.
+export function readLaunchOrganizationId(search: string): string | null {
+  const value = new URLSearchParams(search).get(LAUNCH_ORGANIZATION_PARAM);
+  const trimmed = value?.trim() ?? '';
+  return trimmed === '' ? null : trimmed;
+}
+
+// Reads the parameter and strips it from the visible URL in the same tick.
+// Best-effort on the strip: an exotic URL or an unavailable history API
+// leaves the parameter in the address bar, which costs nothing, the value
+// is already in hand.
+export function consumeLaunchOrganizationId(): string | null {
+  if (typeof window === 'undefined') return null;
+  const organizationId = readLaunchOrganizationId(window.location.search);
+  if (!organizationId) return null;
+  try {
+    const url = new URL(window.location.href);
+    url.searchParams.delete(LAUNCH_ORGANIZATION_PARAM);
+    window.history.replaceState(window.history.state, '', url.toString());
+  } catch {
+    /* address-bar tidiness only */
+  }
+  return organizationId;
+}

package/src/login-hint.ts

@@ -0,0 +1,60 @@
+// Per-app "a Brass session probably exists for this app" hint.
+//
+// The platform session lives in an httpOnly cross-site cookie the app's
+// origin can't read, so on a cold load the SDK would POST `/refresh`
+// blindly; for a signed-out visitor that 401s, which the browser logs to
+// the console even though the SDK handles it cleanly. The hint lets the SDK
+// skip the probe when it has no reason to believe a session exists.
+//
+// Set after any successful refresh, cleared on sign-out or an empty
+// refresh. localStorage (not sessionStorage) so a returning, already-
+// approved user gets a silent restore in a brand-new tab. The value is a
+// non-secret boolean flag (the real session is the server-side row gated by
+// `approved_apps`, useless without the cookie), so readable storage leaks
+// nothing. Keyed per app id.
+
+const KEY_PREFIX = '__brass_login_hint_';
+
+function getStorage(): Storage | null {
+  if (typeof localStorage === 'undefined') return null;
+  try {
+    return localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function key(appId: string): string {
+  return `${KEY_PREFIX}${appId}`;
+}
+
+export function storeLoginHint(appId: string): void {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(key(appId), '1');
+  } catch {
+    // Quota / disabled storage. The hint is a best-effort optimisation;
+    // without it the SDK probes /refresh unconditionally.
+  }
+}
+
+export function readLoginHint(appId: string): boolean {
+  const storage = getStorage();
+  if (!storage) return false;
+  try {
+    return storage.getItem(key(appId)) === '1';
+  } catch {
+    return false;
+  }
+}
+
+export function clearLoginHint(appId: string): void {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(key(appId));
+  } catch {
+    // See storeLoginHint.
+  }
+}

package/src/mutate-batching.ts

@@ -0,0 +1,63 @@
+// Committing a very large mutation as it goes, so an app can write a
+// file's worth of records through the same `mutate` it uses for one.
+//
+// Encoding a commit costs more per record the more containers that commit
+// creates: 20,000 records in one commit take ~60s and produce an op too
+// large to store, where the same records committed every ~500 take under
+// 3s (`scripts/bench/`). Above the budget below, a mutation therefore
+// commits and continues.
+//
+// The consequence a caller can observe is that peers receive such a write
+// as several updates instead of one, so they can see it part-applied. It
+// converges normally and stays one undo step.
+
+// A batch closes once the values assigned since the last commit reach
+// roughly this much JSON, which keeps each op in the tens of KB: an
+// encoded op runs close to the JSON length of its values, and base64 adds
+// a third. Budgeting on size rather than on a record count is what keeps
+// that true for narrow and wide records alike, so where it splits depends
+// on width (measured: ~800 spreadsheet cells, ~200 wider rows).
+export const MUTATE_BATCH_JSON_BUDGET_CHARS = 48 * 1024;
+
+/** Rough size of one assigned value. Runs on every assignment, so it only
+ *  has to be proportional; an unserializable value counts as nominal
+ *  rather than throwing, since the assignment itself is where that error
+ *  belongs. */
+function approximateChars(value: unknown): number {
+  if (value === null || value === undefined) return 8;
+  const t = typeof value;
+  if (t === 'number' || t === 'boolean') return 8;
+  if (t === 'string') return (value as string).length + 2;
+  try {
+    return JSON.stringify(value)?.length ?? 64;
+  } catch {
+    return 64;
+  }
+}
+
+/**
+ * Decides when a mutation should commit. The caller supplies what a commit
+ * means, since an ordered map reconciles its order list first.
+ */
+export class MutateBatcher {
+  private _chars = 0;
+
+  constructor(private readonly _flush: () => void) {}
+
+  /** Account for one assignment, from the proxy's set trap. */
+  record(value: unknown): void {
+    const chars = approximateChars(value);
+    // Commit BEFORE adding, so one assignment larger than the whole budget
+    // lands in a batch of its own instead of dragging its neighbours over
+    // the line with it.
+    if (this._chars > 0 && this._chars + chars > MUTATE_BATCH_JSON_BUDGET_CHARS) {
+      this._flush();
+      this._chars = 0;
+    }
+    this._chars += chars;
+  }
+
+  recordDelete(): void {
+    this.record(null);
+  }
+}