cursedbelt 5.1.0 → 5.2.0

package/src/react/engagement/beaconClient.ts

@@ -0,0 +1,228 @@
+/**
+ * `cursedbelt/react/engagement-beacon` — the engagement beacon's plain-JS half (no React). Lifted
+ * 2026-09-23 (cursedbelt 5.2.0, task 098-280's browser half) from `src/kit/engagement/beacon.client.ts`,
+ * identical in collections, family, music and roms (auth's differed only in a comment). The
+ * server half is `cursedbelt-server/engagement`.
+ *
+ * The browser half — report which PLACE the user is on, once per arrival.
+ *
+ * ── Why an explicit beacon and not the request log ──────────────────────────
+ * Most satellites are SPA-routed: moving from Notes' Files page to its Ask page
+ * fires zero navigations and, on a warm cache, zero HTTP requests. So the
+ * request metrics already in `metrics/` can tell you an app is used and cannot
+ * tell you which of its pages are — which is exactly the question the owner
+ * asked ("notes is used but its slideshow is not"). One small event, sent by
+ * the router, is the only thing that can answer it.
+ *
+ * ── It is ONE implementation, adopted; never per-app ────────────────────────
+ * Eleven hand-rolled beacons would be eleven different place vocabularies, and
+ * the console would be comparing strings that mean different things. Apps call
+ * `reportPlace` (or mount `useEngagementBeacon`) and send an id from their own
+ * route manifest; the server resolves it against that same manifest.
+ *
+ * ── What it does NOT send ───────────────────────────────────────────────────
+ * No path, no query, no title, no referrer, no identifiers of any kind — just
+ * `{ place }`. The account comes from the session cookie the request already
+ * carries, server-side. There is nothing in the payload that could carry a note
+ * id, a ROM title or a search string, which is the property that makes this
+ * safe to run inside private apps at all. See `policy.ts`.
+ *
+ * ── Failure is silence ──────────────────────────────────────────────────────
+ * Every call is fire-and-forget and swallows its error. Telemetry that can
+ * surface an error toast, block a route change, or reject an unhandled promise
+ * is telemetry that makes the app worse than having none.
+ *
+ * 🔴 …and "silence" includes the BROWSER's console, which is why the beacon
+ * asks whether there is a session before it reports (`SESSION_PATH` below).
+ * Swallowing the rejection in JS is not enough: a `fetch` that comes back 401
+ * leaves the browser's own *"Failed to load resource: the server responded with
+ * a status of 401"* in the console no matter what the caller does with the
+ * promise. Measured 2026-08-14 against live prod — `music` and `learn` both
+ * failed their signed-out route-health check on exactly this, with a correctly
+ * rendered sign-in card on screen and nothing else wrong. `apps/roms`' App.tsx
+ * already wrote the rule down for the feedback provider: *"an app that logs an
+ * error on its front door is an app nobody can tell apart from a broken one."*
+ * The recorder's 401 is deliberate and stays — `api.ts` mounts it AFTER the
+ * session gate on purpose, because the gate is what puts the user where
+ * `resolveUser` can read them — so the fix belongs on this side.
+ *
+ * It is also the semantically right answer, not merely a quieter one: the
+ * recorder attributes a view to an account, so a signed-out arrival could never
+ * have been recorded. Nothing that used to be counted stops being counted.
+ */
+
+/** Where the recorder is mounted. Apps that remount it pass `basePath`. */
+export const ENGAGEMENT_BASE_PATH = "/api/engagement";
+
+/**
+ * The public session probe every satellite serves
+ * (`ssoConsumer.server.ts` → `{ authenticated, user?, accountsUrl }`).
+ *
+ * Deliberately NOT session-gated on the server, which is what makes it usable
+ * here: asking it costs one small same-origin GET and can never itself produce
+ * the console line this exists to avoid.
+ */
+export const SESSION_PATH = "/api/auth/session";
+
+export interface ReportPlaceOptions {
+	basePath?: string;
+	/** Injected in tests; defaults to the global. */
+	fetchImpl?: typeof fetch;
+	/** Override the session probe. Apps that remount the consumer elsewhere. */
+	sessionPath?: string;
+	/**
+	 * Skip the session probe and report unconditionally.
+	 *
+	 * For a caller that ALREADY knows there is a session — a React tree below the
+	 * authenticated branch, say — where the probe would be a second answer to a
+	 * question already asked. Never set it from `main.tsx`, which runs before
+	 * anything knows.
+	 */
+	assumeSignedIn?: boolean;
+}
+
+/**
+ * The last place reported, so a router that re-renders does not re-report.
+ *
+ * A React router re-runs its effects on every state change that touches the
+ * route object, and a beacon per keystroke in a search box would turn one visit
+ * into forty views — inflating exactly the number the console reads as
+ * "interest". De-duplicating on the place id is what keeps a view meaning "an
+ * arrival".
+ */
+let lastReported: string | null = null;
+
+/**
+ * Where the browser is, as a string the server can resolve.
+ *
+ * The hash when there is one (every satellite but roms routes on it), else the
+ * pathname. Never the search string: `normalizePlaceId` strips one anyway, and
+ * not sending it in the first place means user text does not travel at all.
+ */
+export function currentLocationPlace(): string {
+	const { hash, pathname } = window.location;
+	const raw = hash && hash !== "#" ? hash : pathname;
+	return raw.split("?")[0] ?? "/";
+}
+
+/**
+ * The answer to "is anyone signed in?", remembered for this page load.
+ *
+ * One probe per load, not one per navigation: the answer cannot change without
+ * a navigation that replaces the document (the SSO callback is a full page
+ * load), and re-asking on every hash change would trade one wasted request for
+ * dozens.
+ */
+let sessionAnswer: Promise<boolean> | null = null;
+
+/** Reset the de-duplication memory. Tests, and a sign-out. */
+export function resetEngagementBeacon(): void {
+	lastReported = null;
+	sessionAnswer = null;
+}
+
+/**
+ * Is there a session? Silent, cached, and false on any doubt.
+ *
+ * Fails CLOSED — a probe that throws, answers non-2xx or returns a body this
+ * cannot read means "do not report". The cost of a false negative is one
+ * uncounted view; the cost of a false positive is the console line on the front
+ * door that this whole path exists to prevent.
+ */
+async function hasSession(options: ReportPlaceOptions): Promise<boolean> {
+	const doFetch = options.fetchImpl ?? globalThis.fetch;
+	if (typeof doFetch !== "function") return false;
+	try {
+		const res = await doFetch(options.sessionPath ?? SESSION_PATH, {
+			credentials: "same-origin",
+		});
+		if (!res.ok) return false;
+		const body = (await res.json()) as { authenticated?: unknown } | null;
+		return body?.authenticated === true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Report an arrival at `place`. Returns whether anything was sent.
+ *
+ * Not awaited by callers in practice — the promise is returned so a test can
+ * settle it without a timer.
+ */
+export async function reportPlace(
+	place: string,
+	options: ReportPlaceOptions = {},
+): Promise<boolean> {
+	if (!place || place === lastReported) return false;
+	const doFetch = options.fetchImpl ?? globalThis.fetch;
+	if (typeof doFetch !== "function") return false;
+
+	// 🔴 BEFORE the de-duplication is committed, not after. A signed-out arrival
+	// must leave no trace at all — recording it as `lastReported` would mean the
+	// view that happens once the visitor signs in and lands back on this same
+	// place is silently dropped as a duplicate.
+	if (options.assumeSignedIn !== true) {
+		sessionAnswer ??= hasSession(options);
+		if (!(await sessionAnswer)) return false;
+	}
+
+	if (place === lastReported) return false;
+	lastReported = place;
+	try {
+		await doFetch(`${options.basePath ?? ENGAGEMENT_BASE_PATH}/view`, {
+			method: "POST",
+			headers: { "content-type": "application/json" },
+			// Same-origin credentials: the session cookie is the only identity
+			// this request carries, and it is the only one it may carry.
+			credentials: "same-origin",
+			body: JSON.stringify({ place }),
+			keepalive: true,
+		});
+		return true;
+	} catch {
+		// See the header: telemetry never becomes the user's problem.
+		return false;
+	}
+}
+
+/** Detaches the listeners `startLocationBeacon` installed. */
+export type StopBeacon = () => void;
+
+let running: StopBeacon | null = null;
+
+/**
+ * Start reporting wherever the browser is, and keep reporting as it moves.
+ *
+ * The form every app adopts, called once from `main.tsx` beside
+ * `initColorScheme()` — one line, no React, and no per-app mapping from a
+ * router's internal view name to a place id. The server resolves the LOCATION
+ * against that app's own `routes.manifest.json` (`policy.ts:resolvePlace`),
+ * which is the list the app already maintains and already gates on.
+ *
+ * `hashchange` and `popstate` between them cover both kinds of router, which is
+ * why BOTH are listened for when `collections` — hash-routed — only needs the
+ * first. The census that settled it was the previous generation's twelve apps:
+ * eleven hash routers and one pushState app. Keeping the second listener costs
+ * a no-op call, and losing it would be silent.
+ *
+ * Idempotent — a second call replaces the first rather than doubling every
+ * view, which matters because React 18 StrictMode mounts twice in development
+ * and a doubled count is a wrong number rather than a visible fault.
+ */
+export function startLocationBeacon(options: ReportPlaceOptions = {}): StopBeacon {
+	running?.();
+	const send = (): void => {
+		void reportPlace(currentLocationPlace(), options);
+	};
+	send();
+	window.addEventListener("hashchange", send);
+	window.addEventListener("popstate", send);
+	const stop: StopBeacon = () => {
+		window.removeEventListener("hashchange", send);
+		window.removeEventListener("popstate", send);
+		if (running === stop) running = null;
+	};
+	running = stop;
+	return stop;
+}

package/src/react/engagement/index.ts

@@ -0,0 +1,13 @@
+// `cursedbelt/react/engagement-beacon` — the engagement beacon: `reportPlace` and
+// `startLocationBeacon` (plain JS, no React) and the React hooks over them.
+export {
+	ENGAGEMENT_BASE_PATH,
+	type ReportPlaceOptions,
+	reportPlace,
+	resetEngagementBeacon,
+	SESSION_PATH,
+	type StopBeacon,
+	startLocationBeacon,
+	currentLocationPlace,
+} from './beaconClient.js';
+export { EngagementBeacon, useEngagementBeacon, useLocationBeacon } from './beacon.js';

package/src/react/lib/directUpload.spec.ts

@@ -0,0 +1,128 @@
+/**
+ * `cursedbelt/react/upload-direct` — the browser half of a resumable upload to binary-server.
+ *
+ * Neither app that carried this module (collections, family) had a test of it, so these pin the
+ * behaviours a 10 GB upload depends on, against a scripted `fetch`: resume skips delivered parts,
+ * parts are PUT with their bytes, a 403 re-mints the token, a 507 is terminal and never retried, a
+ * dropped part is retried, low disk only WARNS, and a lost final response is recovered by asking.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { chunkCount, fetchSessionState, InsufficientStorageError, type UploadSession, uploadDirect } from './directUpload.js';
+
+const SESSION: UploadSession = {
+  baseUrl: 'https://bs.test',
+  path: 'family/media/abc def',
+  token: 't1',
+  sid: 's',
+  totalChunks: 3,
+  chunkBytes: 4,
+};
+const FILE = new Blob(['aaaabbbbcc'], { type: 'image/jpeg' });
+
+interface Call {
+  method: string;
+  url: URL;
+  body: string | null;
+}
+
+const realFetch = globalThis.fetch;
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+/** Install a `fetch` that records every call and answers from `answer`. */
+function script(answer: (call: Call) => Response | Promise<Response>): Call[] {
+  const calls: Call[] = [];
+  globalThis.fetch = (async (input: string, init?: RequestInit) => {
+    const body = init?.body instanceof Blob ? await init.body.text() : null;
+    const call = { method: init?.method ?? 'GET', url: new URL(String(input)), body };
+    calls.push(call);
+    return answer(call);
+  }) as unknown as typeof fetch;
+  return calls;
+}
+
+const json = (status: number, body: unknown) => new Response(JSON.stringify(body), { status });
+const status = (received: number[], extra: Record<string, unknown> = {}) => json(200, { received, complete: false, ...extra });
+
+describe('chunkCount and fetchSessionState', () => {
+  test('parts round UP, and an empty file is still one part', () => {
+    expect(chunkCount(10, 4)).toBe(3);
+    expect(chunkCount(8, 4)).toBe(2);
+    expect(chunkCount(0, 4)).toBe(1);
+  });
+
+  test('a status the server cannot answer is a FRESH session, not a failure', async () => {
+    script(() => new Response('nope', { status: 500 }));
+    const state = await fetchSessionState(SESSION);
+    expect([...state.received]).toEqual([]);
+    expect(state.complete).toBe(false);
+  });
+});
+
+describe('uploadDirect', () => {
+  test('resumes: sends only the parts binary-server does not hold, with their bytes, to an encoded path', async () => {
+    const calls = script((c) =>
+      c.method === 'GET' ? status([1]) : json(200, c.url.searchParams.get('ci') === '2' ? { assembled: true, size: 10, checksum: 'h', key: SESSION.path } : {}),
+    );
+    const result = await uploadDirect(FILE, SESSION, { concurrency: 1 });
+    const puts = calls.filter((c) => c.method === 'PUT');
+    expect(puts.map((c) => [c.url.searchParams.get('ci'), c.body])).toEqual([
+      ['0', 'aaaa'],
+      ['2', 'cc'],
+    ]);
+    expect(puts[0]?.url.pathname).toBe('/upload-chunk/family/media/abc%20def');
+    expect(result).toEqual({ key: SESSION.path, size: 10, checksum: 'h' });
+  });
+
+  test('an object already complete sends NOTHING', async () => {
+    const calls = script(() => json(200, { received: [0, 1, 2], complete: true, size: 10, checksum: 'h' }));
+    expect(await uploadDirect(FILE, SESSION)).toEqual({ key: SESSION.path, size: 10, checksum: 'h' });
+    expect(calls.filter((c) => c.method === 'PUT')).toEqual([]);
+  });
+
+  test('a 403 re-mints the token and the retry carries the new one', async () => {
+    let first = true;
+    const calls = script((c) => {
+      if (c.method === 'GET') return status([0, 1]);
+      if (first) {
+        first = false;
+        return new Response('expired', { status: 403 });
+      }
+      return json(200, { assembled: true, size: 10, checksum: null });
+    });
+    await uploadDirect(FILE, SESSION, { refreshToken: async () => 't2', retries: 3 });
+    const puts = calls.filter((c) => c.method === 'PUT').map((c) => c.url.searchParams.get('token'));
+    expect(puts).toEqual(['t1', 't2']);
+  }, 10_000);
+
+  test('🔴 a 507 is TERMINAL — one attempt, a named error, no retry storm against a full disk', async () => {
+    const calls = script((c) => (c.method === 'GET' ? status([0, 1]) : json(507, { freeBytes: 0 })));
+    await expect(uploadDirect(FILE, SESSION, { retries: 5 })).rejects.toBeInstanceOf(InsufficientStorageError);
+    expect(calls.filter((c) => c.method === 'PUT')).toHaveLength(1);
+  });
+
+  test('🔴 low disk only WARNS — the upload still runs (the owner, 2026-08-13)', async () => {
+    const warned: unknown[] = [];
+    script((c) => (c.method === 'GET' ? status([], { freeBytes: 1 }) : json(200, { assembled: c.url.searchParams.get('ci') === '2' })));
+    await uploadDirect(FILE, SESSION, { onLowDisk: (info) => warned.push(info) });
+    expect(warned).toEqual([{ freeBytes: 1, needBytes: 10 }]);
+  });
+
+  test('a lost final response is recovered by ASKING, not by re-sending', async () => {
+    let gets = 0;
+    const calls = script((c) => {
+      if (c.method === 'GET') return ++gets === 1 ? status([0, 1]) : json(200, { received: [0, 1, 2], complete: true, size: 10, checksum: 'z' });
+      return json(200, {}); // the part landed; the assemble result never reached us
+    });
+    expect(await uploadDirect(FILE, SESSION)).toEqual({ key: SESSION.path, size: 10, checksum: 'z' });
+    expect(calls.filter((c) => c.method === 'PUT')).toHaveLength(1);
+  });
+
+  test('progress reaches 1', async () => {
+    const seen: number[] = [];
+    script((c) => (c.method === 'GET' ? status([]) : json(200, { assembled: c.url.searchParams.get('ci') === '2' })));
+    await uploadDirect(FILE, SESSION, { onProgress: (f) => seen.push(f) });
+    expect(seen.at(-1)).toBe(1);
+  });
+});