v3: api/ gets one layout rule and keeps to it, and whatever crosses the wire is defined once, in shared/ — api/model/interfaces.ts and src/model.ts declared the same 40 types by hand and had drifted: the error envelope, email required on one side and optional on the other, Invitee/InviteTreeEntry and LinkPreview/UrlPreviewResponse for one shape each. The validation limits, the role permissions, the chat length cap, the @mention pattern and the Bandcamp and YouTube player responses were copied too, behind "keep in sync" comments. shared/ now holds them once, one file per domain (api, category, chat, comment, dump, follow, mention, notification, permissions, player, playlist, search, user, validation, ws), and imports nothing from either half. The server sends Dates; the client reads Wire<T>, the same type with every Date an ISO string, and turns it back with src/utils/shared/deserialize.ts. APIErrorCode becomes a const object, since the frontend's erasableSyntaxOnly rejects an enum. The shared types showed two real gaps: the avatar upload and GET /api/users/me return the full self user and the frontend read them as public users, and a stored session may predate media tokens, so the client keeps it as its own Session type. The backend rule: each folder holds one kind of module, each file is named after its domain. routes/ parse and answer; services/ hold the logic and every SQL query (lib/auth.ts's token check moves to user-service); remote/ is the only place that fetches from other sites — the guarded fetch and the HTML scraping out of rich-content-service, public-address, the Bandcamp and YouTube resolvers, the link providers, the image proxy (fetch, checks and cache, out of routes/preview.ts) and the Twemoji glyphs (out of lib/site-icons.ts). model/ holds per table a row type, its guard and its mappers; validators/ the request guards; db/connection.ts the handle and transaction(), db/startup.ts the purges and default admin that db.ts ran on import, called at the same moment. Tests mirror the source one file per module, test/<layer>/<module>.test.ts, with shared/'s under shared/test/ (deno task test runs both); the test that covered the bandcamp and soundcloud providers together is two now, and the backend can() has its own, so 202 tests. deno lint src/ is clean too: window.* becomes globalThis.*, and test bodies and act() callbacks that never awaited lose their async. The README states the rule. No behaviour changes; the catalogues only move their source references.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

api/remote/bandcamp-tralbum.ts

@@ -0,0 +1,124 @@
+/**
+ * Parser for Bandcamp's `data-tralbum` attribute.
+ *
+ * Every Bandcamp track and album page carries the whole release — titles,
+ * durations and signed mp3 stream URLs — as one HTML-escaped JSON blob on a
+ * `data-tralbum` attribute. One fetch of an album page therefore yields every
+ * track's stream URL; there is no per-track request.
+ *
+ * The stream URLs are signed and expire 24h after the page was fetched, which
+ * is why nothing here is ever persisted to `rich_content` — see
+ * `api/routes/bandcamp.ts` for the resolve-at-play-time endpoint.
+ *
+ * The shape is undocumented, so every field is treated as optional and the
+ * whole parse is best-effort: a `null` return means "not a Bandcamp page",
+ * which callers turn into a fallback to the iframe embed.
+ */
+
+import type { Tralbum, TralbumTrack } from "../../shared/player.ts";
+
+/** Hostnames Bandcamp serves its own sites from. Anchored at the end so that
+ * `bandcamp.com.example.org` cannot pass. Artists on custom domains do not
+ * match this and keep using the embed. */
+export const BANDCAMP_HOST_RE = /(?:^|\.)bandcamp\.com$/;
+
+/**
+ * Decode HTML entities in a single pass.
+ *
+ * The single pass is the point: `decodeHtmlEntities` in remote/html.ts
+ * replaces `&` before `"`, so an escaped-ampersand-then-quot sequence
+ * (`"`, i.e. the literal text `"` inside a title) decodes twice
+ * and yields a bare `"` — which lands inside the JSON string and breaks the
+ * parse. Matching every entity form in one regex means each is replaced once.
+ */
+function decodeEntitiesOnce(input: string): string {
+  const named: Record<string, string> = {
+    quot: '"',
+    apos: "'",
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    nbsp: " ",
+  };
+  return input.replace(
+    /&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z]+));/g,
+    (match, dec: string, hex: string, name: string) => {
+      if (dec) return String.fromCodePoint(Number(dec));
+      if (hex) return String.fromCodePoint(parseInt(hex, 16));
+      return named[name.toLowerCase()] ?? match;
+    },
+  );
+}
+
+/** Resolve Bandcamp's protocol-relative and root-relative art URLs. */
+function artworkUrl(artId: unknown): string | undefined {
+  if (typeof artId !== "number" && typeof artId !== "string") return undefined;
+  const id = String(artId).trim();
+  if (!/^\d+$/.test(id)) return undefined;
+  // _16 is the large square art Bandcamp's own player uses.
+  return `https://f4.bcbits.com/img/a${id}_16.jpg`;
+}
+
+/**
+ * Pull the `data-tralbum` blob out of a Bandcamp page and normalise it.
+ * Returns null when the page has no blob, no audio, or nothing parseable.
+ */
+export function parseTralbum(html: string, sourceUrl: string): Tralbum | null {
+  const match = html.match(/\bdata-tralbum=(["'])([\s\S]*?)\1/);
+  if (!match) return null;
+
+  let raw: Record<string, unknown>;
+  try {
+    raw = JSON.parse(decodeEntitiesOnce(match[2]));
+  } catch {
+    return null;
+  }
+  if (!raw || typeof raw !== "object") return null;
+  if (raw.hasAudio === false) return null;
+
+  const rawTracks = Array.isArray(raw.trackinfo) ? raw.trackinfo : [];
+  const tracks: TralbumTrack[] = rawTracks.map((entry, index) => {
+    const t = (entry ?? {}) as Record<string, unknown>;
+    const file = (t.file ?? {}) as Record<string, unknown>;
+    const mp3 = typeof file["mp3-128"] === "string" ? file["mp3-128"] : null;
+    // Only ever hand out bcbits URLs. Without this the endpoint would relay
+    // whatever host a hostile page put in the blob straight to the browser.
+    const streamUrl = mp3 && isBcbitsUrl(mp3) ? mp3 : null;
+    return {
+      index,
+      trackNum: typeof t.track_num === "number" ? t.track_num : undefined,
+      title: typeof t.title === "string" && t.title.trim()
+        ? t.title
+        : `Track ${index + 1}`,
+      duration: typeof t.duration === "number" && t.duration > 0
+        ? t.duration
+        : undefined,
+      streamUrl,
+      streamable: streamUrl !== null && t.streaming === 1 &&
+        t.unreleased_track !== true && !t.encoding_pending,
+      capped: t.is_capped === true,
+    };
+  });
+
+  if (!tracks.some((t) => t.streamable)) return null;
+
+  const current = (raw.current ?? {}) as Record<string, unknown>;
+  return {
+    sourceUrl,
+    itemType: raw.item_type === "album" ? "album" : "track",
+    title: typeof current.title === "string" ? current.title : undefined,
+    artist: typeof raw.artist === "string" ? raw.artist : undefined,
+    artworkUrl: artworkUrl(raw.art_id),
+    tracks,
+    resolvedAt: Date.now(),
+  };
+}
+
+function isBcbitsUrl(url: string): boolean {
+  try {
+    const { protocol, hostname } = new URL(url);
+    return protocol === "https:" && /(?:^|\.)bcbits\.com$/.test(hostname);
+  } catch {
+    return false;
+  }
+}