@brass-build/client 0.1.0

package/dist/fetch-retry.js

@@ -0,0 +1,90 @@
+// 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.
+// Idempotent GET: replay the full transient set and network throws.
+export const RETRY_READ = {
+    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 = {
+    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 = {
+    replayStatuses: new Set([429, 502, 503, 504]),
+    replayNetworkErrors: true,
+};
+const defaultSleep = (ms) => 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, options = {}) {
+    const policy = options.policy ?? RETRY_READ;
+    const maxAttempts = options.maxAttempts ?? 3;
+    const baseDelayMs = options.baseDelayMs ?? 300;
+    const sleep = options.sleep ?? defaultSleep;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        let response;
+        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');
+}
+//# sourceMappingURL=fetch-retry.js.map

package/dist/fetch-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-retry.js","sourceRoot":"","sources":["../src/fetch-retry.ts"],"names":[],"mappings":"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"}

package/dist/guest-link.d.ts

@@ -0,0 +1,3 @@
+export declare const GUEST_LINK_PARAM = "brass_link";
+export declare function readGuestLinkToken(search: string): string | null;
+//# sourceMappingURL=guest-link.d.ts.map

package/dist/guest-link.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-link.d.ts","sourceRoot":"","sources":["../src/guest-link.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAE7C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE"}

package/dist/guest-link.js

@@ -0,0 +1,13 @@
+// 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) {
+    const value = new URLSearchParams(search).get(GUEST_LINK_PARAM);
+    return value && value.trim() !== '' ? value : null;
+}
+//# sourceMappingURL=guest-link.js.map

package/dist/guest-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-link.js","sourceRoot":"","sources":["../src/guest-link.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,yEAAyE;AACzE,mEAAmE;AACnE,2EAA2E;AAC3E,EAAE;AACF,0DAA0D;AAC1D,0BAA0B;AAE1B,MAAM,CAAC,MAAM,gBAAgB,GAAG,YAAY,CAAC;AAE7C,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAChE,OAAO,KAAK,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACrD,CAAC"}

package/dist/handles.d.ts

@@ -0,0 +1,57 @@
+import { LoroList, LoroMap } from 'loro-crdt';
+import { MutateBatcher } from './mutate-batching.js';
+export interface Change<T = unknown> {
+    readonly set: ReadonlyMap<string, T>;
+    readonly deleted: readonly string[];
+    readonly order?: readonly string[];
+}
+export type ChangeSource = 'local' | 'remote' | 'undo' | 'redo' | 'checkout';
+export interface ChangeOrigin {
+    readonly source: ChangeSource;
+}
+export type MapSubscriber<T = unknown> = (change: Change<T>, origin?: ChangeOrigin) => void;
+export type ListSubscriber = () => void;
+export type HandleUnsubscribe = () => void;
+export interface HandleOwner {
+    assertWritable(): void;
+    ensureLocalUpdatesSubscribed(): void;
+    commitMutate(): void;
+    originOf(event: unknown): ChangeSource;
+}
+export interface MapHandle<T = unknown> {
+    read(): Record<string, T>;
+    get(entryKey: string): T | undefined;
+    keys(): string[];
+    has(entryKey: string): boolean;
+    mutate(fn: (draft: Record<string, T>) => void): void;
+    subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
+    map<U>(entryKey: string): MapHandle<U>;
+    list<U>(entryKey: string): ListHandle<U>;
+}
+export interface ListHandle<T = unknown> {
+    read(): T[];
+    length(): number;
+    mutate(fn: (draft: T[]) => void): void;
+    subscribe(cb: ListSubscriber): HandleUnsubscribe;
+}
+export interface OrderedMapHandle<T = unknown> {
+    read(): Record<string, T>;
+    get(entryKey: string): T | undefined;
+    has(entryKey: string): boolean;
+    keys(): string[];
+    ordered(): {
+        key: string;
+        value: T;
+    }[];
+    mutate(fn: (draft: Record<string, T>) => void): void;
+    subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
+}
+export declare function wrapLoroMapProxy(loroMap: LoroMap, batcher?: MutateBatcher): Record<string, unknown>;
+export declare function createRootMapHandle<T>(root: LoroMap, owner: HandleOwner, pageCount?: () => number, pagingScheme?: () => number): MapHandle<T>;
+export declare function createRootListHandle<T>(root: LoroList, owner: HandleOwner): ListHandle<T>;
+export declare function rebindRootMapAnchor(handle: MapHandle<unknown>, next: LoroMap): void;
+export declare function rebindRootListAnchor(handle: ListHandle<unknown>, next: LoroList): void;
+export declare function resyncRootHandle(handle: MapHandle<unknown> | ListHandle<unknown>): void;
+export declare function teardownRootHandle(handle: MapHandle<unknown> | ListHandle<unknown>): void;
+export declare function createOrderedMapHandle<T>(map: MapHandle<T>, order: ListHandle<string>, owner: HandleOwner): OrderedMapHandle<T>;
+//# sourceMappingURL=handles.d.ts.map

package/dist/handles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handles.d.ts","sourceRoot":"","sources":["../src/handles.ts"],"names":[],"mappings":"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"}