cursedbelt 2.7.0 → 3.0.0

package/src/server/storage/storage.spec.ts

@@ -1,219 +0,0 @@
-import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-import { Hono } from 'hono';
-import { createDiskStore } from './diskStore';
-import { mountMediaRoutes } from './mountMediaRoutes';
-import { createMediaUrls } from './sources';
-import { decodeRange, serveRange } from './streamRange';
-import { createStreamTokenService } from './streamToken';
-import type { MediaStore } from './types';
-
-describe('decodeRange', () => {
-  test('no header ⇒ full', () => {
-    expect(decodeRange(undefined, 100)).toEqual({ kind: 'full' });
-  });
-  test('inclusive a-b', () => {
-    expect(decodeRange('bytes=4-9', 16)).toEqual({ kind: 'partial', start: 4, end: 9 });
-  });
-  test('open-ended a-', () => {
-    expect(decodeRange('bytes=8-', 16)).toEqual({ kind: 'partial', start: 8, end: 15 });
-  });
-  test('suffix -n', () => {
-    expect(decodeRange('bytes=-4', 16)).toEqual({ kind: 'partial', start: 12, end: 15 });
-  });
-  test('clamps end past EOF', () => {
-    expect(decodeRange('bytes=10-999', 16)).toEqual({ kind: 'partial', start: 10, end: 15 });
-  });
-  test('out of bounds ⇒ unsatisfiable', () => {
-    expect(decodeRange('bytes=999-1000', 16)).toEqual({ kind: 'unsatisfiable' });
-  });
-  test('malformed ⇒ full', () => {
-    expect(decodeRange('rows=1-2', 16)).toEqual({ kind: 'full' });
-  });
-});
-
-describe('streamTokenService', () => {
-  const svc = createStreamTokenService({ secret: 'test-secret-abc' });
-
-  test('round-trips a grant', async () => {
-    const token = await svc.sign({ owner: 'tenant1', sourceId: 'src', videoId: 'vid' });
-    expect(await svc.verify(token)).toEqual({ owner: 'tenant1', sourceId: 'src', videoId: 'vid' });
-  });
-  test('rejects a tampered token', async () => {
-    const token = await svc.sign({ owner: 't', sourceId: 's', videoId: 'v' });
-    expect(await svc.verify(`${token}x`)).toBeNull();
-  });
-  test('rejects an expired token', async () => {
-    const token = await svc.sign({ owner: 't', sourceId: 's', videoId: 'v' }, -10);
-    expect(await svc.verify(token)).toBeNull();
-  });
-  test('rejects a token signed with a different secret', async () => {
-    const other = createStreamTokenService({ secret: 'other-secret' });
-    const token = await other.sign({ owner: 't', sourceId: 's', videoId: 'v' });
-    expect(await svc.verify(token)).toBeNull();
-  });
-});
-
-describe('diskStore + serveRange', () => {
-  let root: string;
-  let store: MediaStore;
-  const key = 'fs/tenant1/clip.mp4';
-  const payload = new TextEncoder().encode('0123456789ABCDEF'); // 16 bytes
-
-  beforeAll(async () => {
-    root = await mkdtemp(path.join(tmpdir(), 'cb-storage-'));
-    store = createDiskStore(root);
-    await store.put(key, payload, 'video/mp4');
-  });
-  afterAll(async () => {
-    await rm(root, { recursive: true, force: true });
-  });
-
-  test('stat returns size', async () => {
-    expect(await store.stat(key)).toEqual({ size: 16 });
-  });
-  test('stat of a missing key is null', async () => {
-    expect(await store.stat('fs/tenant1/nope')).toBeNull();
-  });
-  test('getRange returns the inclusive slice', async () => {
-    const rr = await store.getRange(key, { start: 4, end: 9 });
-    const bytes = new Uint8Array(await new Response(rr?.stream).arrayBuffer());
-    expect(new TextDecoder().decode(bytes)).toBe('456789');
-  });
-  test('serveRange answers 206 with Content-Range', async () => {
-    const res = await serveRange(store, key, 'video/mp4', 'bytes=4-9');
-    expect(res.status).toBe(206);
-    expect(res.headers.get('content-range')).toBe('bytes 4-9/16');
-    expect(res.headers.get('content-length')).toBe('6');
-    expect(await res.text()).toBe('456789');
-  });
-  test('serveRange answers 200 for the whole object', async () => {
-    const res = await serveRange(store, key, 'video/mp4', undefined);
-    expect(res.status).toBe(200);
-    expect(res.headers.get('content-length')).toBe('16');
-  });
-  test('serveRange answers 416 for an unsatisfiable range', async () => {
-    const res = await serveRange(store, key, 'video/mp4', 'bytes=999-1000');
-    expect(res.status).toBe(416);
-    expect(res.headers.get('content-range')).toBe('bytes */16');
-  });
-  test('serveRange answers 404 for a missing key', async () => {
-    const res = await serveRange(store, 'fs/tenant1/nope', 'video/mp4', undefined);
-    expect(res.status).toBe(404);
-  });
-  test('removePrefix clears a subtree', async () => {
-    await store.put('hls/tenant1/vid/master.m3u8', payload, 'application/vnd.apple.mpegurl');
-    await store.removePrefix('hls/tenant1/vid');
-    expect(await store.stat('hls/tenant1/vid/master.m3u8')).toBeNull();
-  });
-
-  test('putStream writes a web ReadableStream without hanging or truncating', async () => {
-    const bytes = new Uint8Array(64 * 1024).map((_, i) => i % 256); // 64 KiB, multi-chunk
-    const stream = new Response(bytes).body as ReadableStream<Uint8Array>;
-    await store.putStream('fs/tenant1/streamed.bin', stream, 'application/octet-stream');
-    expect(await store.stat('fs/tenant1/streamed.bin')).toEqual({ size: 64 * 1024 });
-    const round = await store.get('fs/tenant1/streamed.bin');
-    expect(round?.length).toBe(64 * 1024);
-    expect(round?.[1000]).toBe(1000 % 256);
-  });
-
-  test('putStream survives a LIVE request-body stream (Bun 1.3.x detach bug)', async () => {
-    // Regression: in Bun 1.3.x a request-body stream's internals detach across an
-    // I/O await (the mkdir inside putStream); releaseLock() then throws "undefined
-    // is not a function" and every upload 500s. Only a REAL served request exhibits
-    // it — a Response-body stream (test above) never detaches.
-    const app = new Hono();
-    app.put('/u', async (c) => {
-      const body = c.req.raw.body;
-      if (!body) return c.json({ error: 'empty' }, 400);
-      await store.putStream('fs/tenant1/live.bin', body, 'application/octet-stream');
-      return c.json({ ok: true });
-    });
-    const server = Bun.serve({ fetch: app.fetch, port: 0 });
-    try {
-      const res = await fetch(`http://localhost:${server.port}/u`, {
-        method: 'PUT',
-        body: 'live request bytes',
-      });
-      expect(res.status).toBe(200);
-      expect(await store.stat('fs/tenant1/live.bin')).toEqual({ size: 18 });
-    } finally {
-      server.stop();
-    }
-  });
-});
-
-// The split-origin case: assets served from one origin (e.g. Cloudflare Pages), media+API from
-// another (e.g. an EC2 subdomain). Media URLs are built server-side with an ABSOLUTE base, and
-// the serve routes answer cross-origin CORS with the range headers a seeking <video> needs.
-describe('split-origin media (absolute URLs + CORS)', () => {
-  let root: string;
-  let store: MediaStore;
-  const token = createStreamTokenService({ secret: 'origin-secret' });
-  const ctx = { userId: 'u1', tenantId: 'tenantA' };
-  const payload = new TextEncoder().encode('SEGMENTBYTES-0123456789');
-  const PAGE_ORIGIN = 'https://app.example.com';
-  const API_BASE = 'https://api.example.com/_media';
-
-  beforeAll(async () => {
-    root = await mkdtemp(path.join(tmpdir(), 'cb-cors-'));
-    store = createDiskStore(root);
-    // Owner keyspace defaults to tenantId → store under fs/tenantA/…
-    await store.put('fs/tenantA/clip.mp4', payload, 'video/mp4');
-  });
-  afterAll(async () => {
-    await rm(root, { recursive: true, force: true });
-  });
-
-  test('createMediaUrls emits ABSOLUTE cross-origin URLs (not window-relative)', async () => {
-    const urls = createMediaUrls({ baseUrl: API_BASE, token });
-    const built = await urls.build(ctx, 'disk', 'clip');
-    expect(built.streamUrl.startsWith(`${API_BASE}/s/`)).toBe(true);
-    expect(built.hlsUrl.endsWith('/hls/disk/clip/master.m3u8')).toBe(true);
-    // The stream token is a single path segment, so hls.js relative segment fetches inherit it.
-    expect(built.streamUrl).toContain('/s/');
-  });
-
-  test('a trailing slash on baseUrl is normalized', async () => {
-    const urls = createMediaUrls({ baseUrl: `${API_BASE}/`, token });
-    const built = await urls.build(ctx, 'disk', 'clip');
-    expect(built.streamUrl.includes('//s/')).toBe(false);
-  });
-
-  test('cross-origin GET gets ACAO + exposes range headers', async () => {
-    const app = new Hono();
-    mountMediaRoutes(app, { store, token, cors: [PAGE_ORIGIN] });
-    const t = await token.sign({ owner: 'tenantA', sourceId: 'disk', videoId: 'clip' });
-    const res = await app.request(`/_media/s/${t}/media/disk/clip`, {
-      headers: { Origin: PAGE_ORIGIN, Range: 'bytes=0-3' },
-    });
-    expect(res.status).toBe(206);
-    expect(res.headers.get('access-control-allow-origin')).toBe(PAGE_ORIGIN);
-    expect(res.headers.get('access-control-expose-headers')).toContain('Content-Range');
-    expect(res.headers.get('content-range')).toBe('bytes 0-3/23');
-  });
-
-  test('preflight OPTIONS is answered for an allowed origin', async () => {
-    const app = new Hono();
-    mountMediaRoutes(app, { store, token, cors: [PAGE_ORIGIN] });
-    const res = await app.request('/_media/s/x/media/disk/clip', {
-      method: 'OPTIONS',
-      headers: { Origin: PAGE_ORIGIN },
-    });
-    expect(res.status).toBe(204);
-    expect(res.headers.get('access-control-allow-origin')).toBe(PAGE_ORIGIN);
-    expect(res.headers.get('access-control-allow-methods')).toContain('GET');
-  });
-
-  test('a disallowed origin gets no ACAO', async () => {
-    const app = new Hono();
-    mountMediaRoutes(app, { store, token, cors: [PAGE_ORIGIN] });
-    const t = await token.sign({ owner: 'tenantA', sourceId: 'disk', videoId: 'clip' });
-    const res = await app.request(`/_media/s/${t}/media/disk/clip`, {
-      headers: { Origin: 'https://evil.example.com' },
-    });
-    expect(res.headers.get('access-control-allow-origin')).toBeNull();
-  });
-});

package/src/server/storage/streamRange.ts

@@ -1,92 +0,0 @@
-import type { MediaStore } from './types';
-
-// HTTP Range streaming for large media (video), Hono/Bun-native. Serves bytes straight from
-// the active store as 200 (whole) or 206 Partial Content (a byte range) so the browser's
-// <video> element can seek without downloading the entire file. Ported from ca's streamRange,
-// re-expressed as a web `Response` (no Express shim).
-
-export type RangeDecision =
-  | { kind: 'full' }
-  | { kind: 'partial'; start: number; end: number }
-  | { kind: 'unsatisfiable' };
-
-// Parse a single-range `Range: bytes=start-end` header against a known total size. Only the
-// common single-range forms are supported (`a-b`, `a-`, `-n`); anything malformed falls back
-// to a full response, and an out-of-bounds range is rejected so the caller can answer 416.
-// End is clamped to the last byte; ranges are inclusive.
-export function decodeRange(header: string | undefined | null, total: number): RangeDecision {
-  if (!header) return { kind: 'full' };
-  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
-  if (!match) return { kind: 'full' };
-  const [, rawStart, rawEnd] = match;
-  if (rawStart === '' && rawEnd === '') return { kind: 'full' };
-
-  let start: number;
-  let end: number;
-  if (rawStart === '') {
-    // Suffix range: the last N bytes.
-    const suffix = Number.parseInt(rawEnd, 10);
-    if (suffix <= 0) return { kind: 'unsatisfiable' };
-    start = Math.max(0, total - suffix);
-    end = total - 1;
-  } else {
-    start = Number.parseInt(rawStart, 10);
-    end = rawEnd === '' ? total - 1 : Number.parseInt(rawEnd, 10);
-  }
-
-  if (start > end || start >= total || start < 0) return { kind: 'unsatisfiable' };
-  if (end >= total) end = total - 1;
-  return { kind: 'partial', start, end };
-}
-
-export type ServeRangeOpts = {
-  /** Content-Disposition value, e.g. 'inline' or `attachment; filename="clip.mp4"`. */
-  contentDisposition?: string;
-  /** Overrides the default 'private, max-age=86400' (e.g. 'no-store' for private bytes). */
-  cacheControl?: string;
-  extraHeaders?: Record<string, string>;
-};
-
-// Build a Range-aware Response for a stored object. `rangeHeader` is the request's Range header
-// (Hono: `c.req.header('range')`). 404 if the key is gone, 416 for an unsatisfiable range, 206
-// for a partial hit, else 200.
-export async function serveRange(
-  store: MediaStore,
-  key: string,
-  mime: string,
-  rangeHeader: string | undefined | null,
-  opts: ServeRangeOpts = {},
-): Promise<Response> {
-  const meta = await store.stat(key);
-  if (!meta) return new Response(null, { status: 404 });
-  const total = meta.size;
-
-  const headers = new Headers({
-    'Accept-Ranges': 'bytes',
-    'Content-Type': mime,
-    'Cache-Control': opts.cacheControl ?? 'private, max-age=86400',
-  });
-  if (opts.contentDisposition) headers.set('Content-Disposition', opts.contentDisposition);
-  if (opts.extraHeaders) {
-    for (const [k, v] of Object.entries(opts.extraHeaders)) headers.set(k, v);
-  }
-
-  const decision = decodeRange(rangeHeader, total);
-
-  if (decision.kind === 'unsatisfiable') {
-    headers.set('Content-Range', `bytes */${total}`);
-    return new Response(null, { status: 416, headers });
-  }
-
-  const range = decision.kind === 'partial' ? decision : undefined;
-  const result = await store.getRange(key, range);
-  if (!result) return new Response(null, { status: 404 });
-
-  if (range) {
-    headers.set('Content-Range', `bytes ${range.start}-${range.end}/${total}`);
-    headers.set('Content-Length', String(range.end - range.start + 1));
-    return new Response(result.stream, { status: 206, headers });
-  }
-  headers.set('Content-Length', String(total));
-  return new Response(result.stream, { status: 200, headers });
-}

package/src/server/storage/streamToken.ts

@@ -1,76 +0,0 @@
-// 🔴 `../auth/jwt`, NOT `../auth`. The jose half is a REAL dependency — stream tokens are
-// signed and verified here, and jose is a plain `dependencies` entry every consumer already
-// installs. The BARREL was the accident: `../auth/index.ts` also reaches `totp.ts` → `otplib`,
-// an OPTIONAL peer, so every app that touched anything in `cursedbelt/server/storage` was made
-// to install a one-time-password library for code it never calls. Import the leaf module that
-// has what you need; never the index that has everything. `src/leafSubpathsImportNothing.spec.ts`
-// fails if this file (or anything else the storage barrel reaches) undoes it.
-import { signToken, verifyPurposeToken } from '../auth/jwt';
-
-// ── Stream tokens ───────────────────────────────────────────────────────────────
-// Media bytes are loaded by <video>/hls.js/<img>, which cannot send the platform Bearer
-// header an app's auth uses. So byte-serving routes live OUTSIDE the guarded API and
-// authorize each request with a short-lived, PATH-embedded token instead.
-//
-// Why path-embedded, not ?t=: hls.js resolves segment/playlist URIs RELATIVE to the master
-// playlist and does NOT inherit query strings — a `?t=` token would be dropped on segment
-// fetches. A token carried as a leading path segment (…/s/<token>/hls/…) is inherited by every
-// relative child URL, so one token authorizes the whole HLS tree.
-//
-// Reuses cursedbelt's ONE jose integration (`signToken`/`verifyPurposeToken`, HS256) — the
-// same primitive the vault/files/pm unlock tokens use — under a dedicated 'media-stream'
-// purpose so it can never be replayed as an access token (or vice-versa).
-
-const MEDIA_STREAM_PURPOSE = 'media-stream';
-
-/** The scope a stream token authorizes: one video's whole derivative tree, under one owner. */
-export type StreamGrant = {
-  /** owner keyspace segment (the media lives under fs/<owner>/… , hls/<owner>/… , …). */
-  owner: string;
-  sourceId: string;
-  videoId: string;
-};
-
-export interface StreamTokenService {
-  sign(grant: StreamGrant, ttlSeconds?: number): Promise<string>;
-  verify(token: string): Promise<StreamGrant | null>;
-}
-
-export function createStreamTokenService(opts: {
-  secret: string;
-  /** Default 6h — long enough to survive a paused-and-resumed playback without a 401. */
-  defaultTtlSeconds?: number;
-}): StreamTokenService {
-  const ttl = opts.defaultTtlSeconds ?? 6 * 60 * 60;
-  return {
-    async sign(grant, ttlSeconds = ttl) {
-      // userId carries the owner; src/vid are extra claims (JWTPayload allows them). sessionId
-      // is unused for stream tokens (they're not tied to a revocable session row) — a stable
-      // marker keeps the required-field contract without implying a session.
-      return signToken(
-        {
-          userId: grant.owner,
-          sessionId: 'media-stream',
-          roles: [],
-          purpose: MEDIA_STREAM_PURPOSE,
-          src: grant.sourceId,
-          vid: grant.videoId,
-        },
-        opts.secret,
-        ttlSeconds,
-      );
-    },
-    async verify(token) {
-      try {
-        const p = await verifyPurposeToken(token, opts.secret, MEDIA_STREAM_PURPOSE);
-        const src = (p as { src?: unknown }).src;
-        const vid = (p as { vid?: unknown }).vid;
-        if (typeof src !== 'string' || typeof vid !== 'string') return null;
-        return { owner: p.userId, sourceId: src, videoId: vid };
-      } catch {
-        // Bad signature / expiry / purpose mismatch — deny.
-        return null;
-      }
-    },
-  };
-}

package/src/server/storage/transcode.integration.spec.ts

@@ -1,134 +0,0 @@
-import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
-import { existsSync, mkdirSync } from 'node:fs';
-import { mkdtemp, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-import { pickFreePort, startTestServer, type TestServer } from 'cwip/testing';
-
-// Integration test for the binary-server's transcode API (POST /api/transcode,
-// GET /api/transcode/:jobId). Skips cleanly when the binary-server checkout is
-// absent. Mirrors the pattern from chunked.integration.spec.ts.
-//
-// Transcode API implemented in #tsk_01KWQNXRP25W6BE086K49M9S3W.
-// Contract: POST /api/transcode → { jobId }, GET /api/transcode/:jobId → { status, progress?, result? }.
-// Auth: x-internal-secret header must match process.env.INTERNAL_SECRET.
-
-const BS_DIR = process.env.BINARY_SERVER_DIR ?? '';
-const BS_PRESENT = BS_DIR !== '' && existsSync(path.join(BS_DIR, 'src', 'index.ts'));
-
-// SKIPPED until a real binary-server checkout is present: point BINARY_SERVER_DIR at one.
-// There is deliberately no default — a published package must not go looking in one machine's
-// directory layout — and `binary-server` has not been re-homed here, so this skips on every host today.
-describe.skipIf(!BS_PRESENT)('transcode API → real binary-server (integration)', () => {
-  let port: number;
-  let storeDir: string;
-  let server: TestServer | null = null;
-  let tmpData: string;
-  const INTERNAL_SECRET = 'test-transcode-secret';
-
-  beforeAll(async () => {
-    tmpData = await mkdtemp(path.join(tmpdir(), 'bs-transcode-test-'));
-    storeDir = path.join(tmpData, 'binaries');
-    mkdirSync(storeDir, { recursive: true });
-
-    port = await pickFreePort();
-    server = await startTestServer({
-      cwd: BS_DIR,
-      cmd: ['bun', path.join(BS_DIR, 'src', 'index.ts')],
-      port,
-      env: {
-        PORT: String(port),
-        HOST: '127.0.0.1',
-        STORAGE_ROOT: storeDir,
-        DB_PATH: path.join(tmpData, 'test.sqlite'),
-        INTERNAL_SECRET,
-        NODE_ENV: 'test',
-      },
-      healthPath: '/healthz',
-      timeoutMs: 90_000,
-    });
-  }, 90_000);
-
-  afterAll(async () => {
-    await server?.stop();
-    await rm(tmpData, { recursive: true, force: true }).catch(() => void 0);
-  });
-
-  test('POST /api/transcode rejects missing secret with 401', async () => {
-    const res = await fetch(`http://localhost:${port}/api/transcode`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        strategy: 'faststart',
-        sourceKey: 'demo/fs/u1/node1',
-        binaryKey: 'demo/fs/u1/node1.mp4',
-        settings: {},
-      }),
-    });
-    expect(res.status).toBe(401);
-  });
-
-  test('POST /api/transcode rejects wrong secret with 401', async () => {
-    const res = await fetch(`http://localhost:${port}/api/transcode`, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        'x-internal-secret': 'wrong-secret',
-      },
-      body: JSON.stringify({
-        strategy: 'faststart',
-        sourceKey: 'demo/fs/u1/node1',
-        binaryKey: 'demo/fs/u1/node1.mp4',
-        settings: {},
-      }),
-    });
-    expect(res.status).toBe(401);
-  });
-
-  test('POST /api/transcode with missing source returns jobId then fails', async () => {
-    const res = await fetch(`http://localhost:${port}/api/transcode`, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        'x-internal-secret': INTERNAL_SECRET,
-      },
-      body: JSON.stringify({
-        strategy: 'faststart',
-        sourceKey: 'demo/fs/u1/nonexistent',
-        binaryKey: 'demo/fs/u1/nonexistent.mp4',
-        settings: {},
-      }),
-    });
-    expect(res.status).toBe(202);
-    const { jobId } = (await res.json()) as { jobId?: string };
-    expect(typeof jobId).toBe('string');
-
-    // Poll until failed or timeout.
-    const deadline = Date.now() + 5_000;
-    let status: string | undefined;
-    while (Date.now() < deadline) {
-      const poll = await fetch(
-        `http://localhost:${port}/api/transcode/${encodeURIComponent(jobId!)}`,
-        { headers: { 'x-internal-secret': INTERNAL_SECRET } },
-      );
-      expect(poll.status).toBe(200);
-      const body = (await poll.json()) as { status?: string };
-      status = body.status;
-      if (status === 'failed' || status === 'ready') break;
-      await Bun.sleep(100);
-    }
-    expect(status).toBe('failed');
-  });
-
-  test('GET /api/transcode/:jobId returns 404 for unknown job', async () => {
-    const res = await fetch(`http://localhost:${port}/api/transcode/nonexistent-job-id`, {
-      headers: { 'x-internal-secret': INTERNAL_SECRET },
-    });
-    expect(res.status).toBe(404);
-  });
-
-  test('GET /api/transcode/:jobId rejects missing secret with 401', async () => {
-    const res = await fetch(`http://localhost:${port}/api/transcode/any-id`);
-    expect(res.status).toBe(401);
-  });
-});

package/src/server/storage/transcodeJobs.spec.ts

@@ -1,152 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { createTranscodeJobClient } from './transcodeJobs';
-
-/**
- * The transport, driven against a scripted binary-server. The two derivative helpers are what
- * apps call, so what matters is the REQUEST they send (a wrong strategy or a missing
- * `posterOnly` is a full transcode nobody asked for) and that a failure is a plain negative
- * answer rather than a throw — every caller's fallback is "render what you rendered before".
- */
-
-type Call = { url: string; body?: Record<string, unknown>; headers: Record<string, string> };
-
-function scriptedServer(script: {
-  submitStatus?: number;
-  statuses: { status: string; progress?: number; result?: Record<string, unknown> }[];
-}) {
-  const calls: Call[] = [];
-  let polls = 0;
-  const fetchImpl = (async (url: string | URL | Request, init?: RequestInit) => {
-    const href = String(url);
-    const headers = Object.fromEntries(
-      Object.entries((init?.headers ?? {}) as Record<string, string>),
-    );
-    if (init?.method === 'POST') {
-      calls.push({ url: href, body: JSON.parse(String(init.body)), headers });
-      const status = script.submitStatus ?? 202;
-      return new Response(JSON.stringify({ jobId: 'job-1' }), { status });
-    }
-    calls.push({ url: href, headers });
-    const next = script.statuses[Math.min(polls++, script.statuses.length - 1)];
-    return new Response(JSON.stringify(next), { status: 200 });
-  }) as unknown as typeof fetch;
-  return { calls, fetchImpl, polls: () => polls };
-}
-
-const config = (fetchImpl: typeof fetch) => ({
-  baseUrl: 'https://bs.test',
-  appId: 'notes',
-  internalSecret: 's3cret',
-  fetchImpl,
-  pollMs: 0,
-  sleep: async () => {},
-});
-
-describe('createTranscodeJobClient', () => {
-  test('an image job asks for the image strategy with app-scoped keys and the secret', async () => {
-    const server = scriptedServer({ statuses: [{ status: 'ready', result: { hasThumbnail: true } }] });
-    const client = createTranscodeJobClient(config(server.fetchImpl));
-
-    const out = await client.imageThumbnail({
-      sourceKey: 'attachments/abc',
-      thumbKey: 'derived/abc-thumb.jpg',
-    });
-
-    expect(out).toEqual({ hasThumbnail: true, hasDisplay: false });
-    const submit = server.calls[0] as Call;
-    expect(submit.url).toBe('https://bs.test/api/transcode');
-    expect(submit.headers['x-internal-secret']).toBe('s3cret');
-    expect(submit.body).toMatchObject({
-      strategy: 'image',
-      sourceKey: 'notes/attachments/abc',
-      binaryKey: 'notes/attachments/abc',
-      posterKey: 'notes/derived/abc-thumb.jpg',
-    });
-    // No displayKey unless one was asked for — a HEIC display JPEG is a second derivative,
-    // not a default.
-    expect(submit.body).not.toHaveProperty('displayKey');
-  });
-
-  test('a display JPEG is requested only when a displayKey is given', async () => {
-    const server = scriptedServer({
-      statuses: [{ status: 'ready', result: { hasThumbnail: true, hasDisplay: true } }],
-    });
-    const client = createTranscodeJobClient(config(server.fetchImpl));
-    const out = await client.imageThumbnail({
-      sourceKey: 'attachments/heic',
-      thumbKey: 'derived/heic-thumb.jpg',
-      displayKey: 'derived/heic-display.jpg',
-    });
-    expect(out).toEqual({ hasThumbnail: true, hasDisplay: true });
-    expect((server.calls[0] as Call).body).toMatchObject({
-      displayKey: 'notes/derived/heic-display.jpg',
-    });
-  });
-
-  test('a video poster job is posterOnly — a grid tile must not trigger a full transcode', async () => {
-    const server = scriptedServer({
-      statuses: [{ status: 'ready', result: { hasPoster: true, durationSeconds: 12.5 } }],
-    });
-    const client = createTranscodeJobClient(config(server.fetchImpl));
-
-    const out = await client.videoPoster({
-      sourceKey: 'attachments/vid',
-      posterKey: 'derived/vid-poster.jpg',
-    });
-
-    expect(out).toEqual({ hasPoster: true, durationSeconds: 12.5 });
-    expect((server.calls[0] as Call).body).toMatchObject({
-      strategy: 'library',
-      posterOnly: true,
-      posterKey: 'notes/derived/vid-poster.jpg',
-    });
-    // No ladder, no hlsPrefix, no sprite — the expensive half must not be implied.
-    const body = (server.calls[0] as Call).body as Record<string, unknown>;
-    expect(body).not.toHaveProperty('hlsPrefix');
-    expect(body).not.toHaveProperty('spriteKey');
-  });
-
-  test('it polls until the job settles, not once', async () => {
-    const server = scriptedServer({
-      statuses: [
-        { status: 'processing', progress: 10 },
-        { status: 'processing', progress: 80 },
-        { status: 'ready', result: { hasThumbnail: true } },
-      ],
-    });
-    const client = createTranscodeJobClient(config(server.fetchImpl));
-    await client.imageThumbnail({ sourceKey: 'a', thumbKey: 'b' });
-    expect(server.polls()).toBe(3);
-  });
-
-  test('a FAILED job is a negative answer, not a throw — callers fall back to no thumbnail', async () => {
-    const server = scriptedServer({ statuses: [{ status: 'failed' }] });
-    const client = createTranscodeJobClient(config(server.fetchImpl));
-    expect(await client.imageThumbnail({ sourceKey: 'a', thumbKey: 'b' })).toEqual({
-      hasThumbnail: false,
-      hasDisplay: false,
-    });
-    expect(await client.videoPoster({ sourceKey: 'a', posterKey: 'b' })).toEqual({
-      hasPoster: false,
-      durationSeconds: 0,
-    });
-  });
-
-  test('a ready job that produced nothing still reports nothing', async () => {
-    // binary-server answers `ready` for a source it could probe but not derive from. Reading
-    // the STATUS alone would claim a thumbnail that does not exist, and the consumer would
-    // then render a broken image instead of the text it had.
-    const server = scriptedServer({ statuses: [{ status: 'ready', result: {} }] });
-    const client = createTranscodeJobClient(config(server.fetchImpl));
-    expect(await client.imageThumbnail({ sourceKey: 'a', thumbKey: 'b' })).toEqual({
-      hasThumbnail: false,
-      hasDisplay: false,
-    });
-  });
-
-  test('a refused submit throws, so a misconfigured secret is loud', async () => {
-    const server = scriptedServer({ submitStatus: 401, statuses: [] });
-    const client = createTranscodeJobClient(config(server.fetchImpl));
-    await expect(client.imageThumbnail({ sourceKey: 'a', thumbKey: 'b' })).rejects.toThrow(/401/);
-  });
-});