@gigamusic/checkout 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gigamusic/checkout",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Next.js route-handler factories for Stripe Checkout, Stripe webhooks, and presigned-URL downloads. Stripe is hard-wired; all secrets enter as factory args.",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md"
   ],
   "publishConfig": {
@@ -29,10 +30,10 @@
   "dependencies": {
     "archiver": "^7.0.1",
     "stripe": "^22.0.0",
-    "@gigamusic/core": "0.1.0",
-    "@gigamusic/db": "0.1.0",
-    "@gigamusic/email": "0.1.0",
-    "@gigamusic/storage": "0.1.0"
+    "@gigamusic/core": "0.1.1",
+    "@gigamusic/storage": "0.1.1",
+    "@gigamusic/db": "0.1.1",
+    "@gigamusic/email": "0.1.1"
   },
   "peerDependencies": {
     "next": ">=15"

package/src/checkout.ts

@@ -0,0 +1,204 @@
+import type { NextRequest } from "next/server";
+import Stripe from "stripe";
+import { applyCatalogDiscount, sumLineItems } from "@gigamusic/core";
+import type { ReleaseWithTracks, TrackWithFiles } from "@gigamusic/db";
+import type { CheckoutCartItem, CheckoutDeps } from "./types.js";
+
+/**
+ * Build a POST handler that translates `{ items }` from the cart into a Stripe
+ * Checkout Session and replies with `{ url }`. Release/track metadata is
+ * stashed on the session so the webhook handler can later record the order
+ * without re-deriving cart contents.
+ *
+ * Stripe is hard-wired (per project policy). The Stripe SDK instance is
+ * created once per factory call and captured in the closure — no module
+ * globals, no `process.env`.
+ */
+export function createCheckoutHandler(
+  deps: CheckoutDeps,
+): (req: NextRequest) => Promise<Response> {
+  const {
+    stripeSecret,
+    queries,
+    baseUrl,
+    successPath = "/checkout/success",
+    cancelPath = "/cart",
+    currency = "usd",
+    catalogDiscount,
+  } = deps;
+
+  const stripe = new Stripe(stripeSecret, { typescript: true });
+
+  return async (req: NextRequest): Promise<Response> => {
+    let payload: { items?: CheckoutCartItem[] };
+    try {
+      payload = (await req.json()) as { items?: CheckoutCartItem[] };
+    } catch {
+      return jsonError("Invalid JSON body", 400);
+    }
+
+    const items = payload.items;
+    if (!items || items.length === 0) {
+      return jsonError("No items provided", 400);
+    }
+
+    const successUrl = `${baseUrl}${successPath}?session_id={CHECKOUT_SESSION_ID}`;
+    const cancelUrl = `${baseUrl}${cancelPath}`;
+
+    const isCatalogPurchase = items.some((i) => i.kind === "catalog");
+
+    try {
+      if (isCatalogPurchase) {
+        const resolvedDiscount =
+          typeof catalogDiscount === "function"
+            ? await catalogDiscount()
+            : catalogDiscount;
+        if (!resolvedDiscount) {
+          return jsonError("Catalog purchase not configured", 400);
+        }
+        const releases = await queries.listPublishedReleases();
+        const subtotal = sumLineItems(
+          releases.map((r) => ({ id: r.id, priceCents: r.price })),
+        );
+        const { totalCents } = applyCatalogDiscount(subtotal, resolvedDiscount.percent);
+
+        const session = await stripe.checkout.sessions.create({
+          mode: "payment",
+          line_items: [
+            {
+              price_data: {
+                currency,
+                product_data: { name: resolvedDiscount.productName },
+                unit_amount: totalCents,
+              },
+              quantity: 1,
+            },
+          ],
+          metadata: {
+            catalog_purchase: "true",
+            release_ids: JSON.stringify(releases.map((r) => r.id)),
+            track_ids: "[]",
+          },
+          success_url: successUrl,
+          cancel_url: cancelUrl,
+        });
+
+        return Response.json({ url: session.url });
+      }
+
+      const releaseIds = items
+        .filter((i) => i.kind === "release" && i.id != null)
+        .map((i) => i.id as number);
+      const trackIds = items
+        .filter((i) => i.kind === "track" && i.id != null)
+        .map((i) => i.id as number);
+
+      if (releaseIds.length === 0 && trackIds.length === 0) {
+        return jsonError("No valid items found", 400);
+      }
+
+      // Single `listPublishedReleases` call sources both release and track
+      // line items. Tracks live inside their release, so one fetch keeps the
+      // ID/price/cover lookups consistent without a second round-trip.
+      const allReleases = await queries.listPublishedReleases();
+      const releaseById = new Map(allReleases.map((r) => [r.id, r]));
+      const trackContext = new Map<
+        number,
+        { track: TrackWithFiles; release: ReleaseWithTracks }
+      >();
+      for (const release of allReleases) {
+        for (const track of release.tracks) {
+          trackContext.set(track.id, { track, release });
+        }
+      }
+
+      const releaseLineItems = releaseIds
+        .map((id) => releaseById.get(id))
+        .filter((r): r is ReleaseWithTracks => r !== undefined)
+        .map((r) => ({
+          price_data: {
+            currency,
+            product_data: {
+              name: r.name,
+              ...(r.coverImageUrl
+                ? { images: [toAbsoluteUrl(r.coverImageUrl, baseUrl)] }
+                : {}),
+            },
+            unit_amount: r.price,
+          },
+          quantity: 1 as const,
+        }));
+
+      const trackLineItems = trackIds
+        .map((id) => trackContext.get(id))
+        .filter(
+          (c): c is { track: TrackWithFiles; release: ReleaseWithTracks } =>
+            c !== undefined,
+        )
+        .map(({ track, release }) => ({
+          price_data: {
+            currency,
+            product_data: {
+              name: `${release.name} — ${track.name}`,
+              ...(release.coverImageUrl
+                ? { images: [toAbsoluteUrl(release.coverImageUrl, baseUrl)] }
+                : {}),
+            },
+            unit_amount: track.price,
+          },
+          quantity: 1 as const,
+        }));
+
+      const lineItems = [...releaseLineItems, ...trackLineItems];
+      if (lineItems.length === 0) {
+        return jsonError("No valid items found", 400);
+      }
+
+      const resolvedReleaseIds = releaseLineItems.length
+        ? releaseIds.filter((id) => releaseById.has(id))
+        : [];
+      const resolvedTrackIds = trackLineItems.length
+        ? trackIds.filter((id) => trackContext.has(id))
+        : [];
+
+      const session = await stripe.checkout.sessions.create({
+        mode: "payment",
+        line_items: lineItems,
+        metadata: {
+          release_ids: JSON.stringify(resolvedReleaseIds),
+          track_ids: JSON.stringify(resolvedTrackIds),
+        },
+        success_url: successUrl,
+        cancel_url: cancelUrl,
+      });
+
+      return Response.json({ url: session.url });
+    } catch (err) {
+      return jsonError("Failed to create checkout session", 500, err);
+    }
+  };
+}
+
+/** Resolve a stored relative URL against `baseUrl` and percent-encode the path. Bare http(s) URLs pass through. */
+function toAbsoluteUrl(url: string, baseUrl: string): string {
+  const raw = url.startsWith("http")
+    ? url
+    : `${baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
+  try {
+    const parsed = new URL(raw);
+    parsed.pathname = encodeURI(decodeURI(parsed.pathname));
+    return parsed.toString();
+  } catch {
+    return raw;
+  }
+}
+
+function jsonError(message: string, status: number, cause?: unknown): Response {
+  if (cause) {
+    // Logged via console.error. Consumers can swap this for a structured
+    // logger in a future iteration; the package contract doesn't expose a
+    // logger slot yet.
+    console.error(`[checkout] ${message}:`, cause);
+  }
+  return Response.json({ error: message }, { status });
+}

package/src/download.ts

@@ -0,0 +1,85 @@
+import type { NextRequest } from "next/server";
+import type { Queries, TrackFile } from "@gigamusic/db";
+import type { DownloadDeps } from "./types.js";
+
+interface RouteContext {
+  params: Promise<{ token: string }>;
+}
+
+/**
+ * Build the GET handler for `/download/[token]?trackId=…&format=…`. The token
+ * is looked up via `queries.getDownloadToken`; the track grant is checked via
+ * `queries.tokenGrantsTrack`. On success the handler 302s to a presigned R2
+ * URL — the storage provider has `Content-Disposition: attachment` baked in,
+ * so the browser triggers a same-tab download.
+ *
+ * Order of checks: locate the file in the catalog first (so a missing-file
+ * is 404), *then* enforce the token-track grant (a wrong trackId for the
+ * given token is 403, not 404).
+ */
+export function createDownloadHandler(
+  deps: DownloadDeps,
+): (req: NextRequest, ctx: RouteContext) => Promise<Response> {
+  const { queries, storage } = deps;
+
+  return async (req: NextRequest, ctx: RouteContext): Promise<Response> => {
+    const { token } = await ctx.params;
+    const requestUrl = new URL(req.url);
+    const trackIdRaw = requestUrl.searchParams.get("trackId");
+    const format = requestUrl.searchParams.get("format") ?? "mp3";
+
+    if (!trackIdRaw) {
+      return Response.json({ error: "Missing trackId" }, { status: 400 });
+    }
+    const trackId = Number(trackIdRaw);
+    if (!Number.isFinite(trackId)) {
+      return Response.json({ error: "Invalid trackId" }, { status: 400 });
+    }
+
+    const downloadToken = await queries.getDownloadToken(token);
+    if (!downloadToken) {
+      return Response.json({ error: "Invalid download link" }, { status: 404 });
+    }
+
+    const file = await findTrackFileInCatalog(queries, trackId, format);
+    if (!file) {
+      return Response.json({ error: "File not found" }, { status: 404 });
+    }
+
+    const ok = await queries.tokenGrantsTrack(token, trackId);
+    if (!ok) {
+      return Response.json({ error: "Track not in order" }, { status: 403 });
+    }
+
+    const url = await storage.getPresignedDownloadUrl(file.storageKey, {
+      filename: cleanDownloadFilename(file.fileName),
+      contentType: format === "wav" ? "audio/wav" : "audio/mpeg",
+    });
+    return Response.redirect(url, 302);
+  };
+}
+
+/** Walk the published catalog (released to all customers) to find the file matching `trackId` + `format`. */
+async function findTrackFileInCatalog(
+  queries: Queries,
+  trackId: number,
+  format: string,
+): Promise<TrackFile | null> {
+  const releases = await queries.listPublishedReleases();
+  for (const release of releases) {
+    const track = release.tracks.find((t) => t.id === trackId);
+    if (!track) continue;
+    const file = track.files.find((f) => f.format === format);
+    return file ?? null;
+  }
+  return null;
+}
+
+/** Trim stray leading/trailing whitespace from a download filename while keeping its extension intact. */
+export function cleanDownloadFilename(name: string): string {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return name.trim();
+  return `${name.slice(0, dot).trim()}${name.slice(dot).trim()}`;
+}
+
+export type { Queries };

package/src/index.ts

@@ -0,0 +1,13 @@
+export { createCheckoutHandler } from "./checkout.js";
+export { createStripeWebhookHandler } from "./webhook.js";
+export { createDownloadHandler } from "./download.js";
+export { createDownloadZipHandler } from "./zip.js";
+export { createDownloadZipStreamHandler } from "./zip-stream.js";
+export { createSwZipFallbackHandler } from "./sw-zip-fallback.js";
+
+export type {
+  CheckoutCartItem,
+  CheckoutDeps,
+  DownloadDeps,
+  WebhookDeps,
+} from "./types.js";

package/src/sw-zip-fallback.ts

@@ -0,0 +1,56 @@
+const ERROR_HTML = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="color-scheme" content="light dark">
+  <title>Bulk download couldn't start</title>
+  <style>
+    body { font-family: system-ui, -apple-system, sans-serif; max-width: 560px; margin: 3rem auto; padding: 0 1.25rem; line-height: 1.55; }
+    h1 { font-size: 1.35rem; margin-bottom: 0.75rem; }
+    ul { padding-left: 1.25rem; }
+    li { margin: 0.35rem 0; }
+    a { color: #6366f1; }
+  </style>
+</head>
+<body>
+  <h1>Bulk download couldn't start</h1>
+  <p>Your browser couldn't generate the zip in the background. This usually happens in private/incognito mode, or after the order page has been open for a long time.</p>
+  <p>To get your music:</p>
+  <ul>
+    <li>Go back to your order page and use the individual track download buttons.</li>
+    <li>Or reopen the order link in a fresh tab and try the bulk download again.</li>
+  </ul>
+  <p><a href="javascript:history.back()">&larr; Back to your order</a></p>
+</body>
+</html>`;
+
+/**
+ * Fallback for `/sw-zip/[...path]` reached only when the service worker
+ * shipped at `@gigamusic/ui`'s `public/sw-zip.js` fails to intercept the
+ * navigation. Without this route the browser would save Next.js's 404
+ * HTML under the URL's `.zip` filename — and macOS Archive Utility
+ * surfaces that as the confusing "Error 79 - Inappropriate file type or
+ * format." Returning `text/html` (and no `Content-Disposition`) makes
+ * the browser render the message instead of saving it.
+ *
+ * Wire up at `app/sw-zip/[...path]/route.ts`:
+ *
+ * ```ts
+ * export const GET = createSwZipFallbackHandler();
+ * ```
+ */
+export function createSwZipFallbackHandler(): () => Response {
+  return () => {
+    // Hitting this route is always a failure mode — the SW should have
+    // intercepted. Log so the frequency shows up in serverless logs.
+    console.warn("[sw-zip] fallback route hit — service worker did not intercept");
+    return new Response(ERROR_HTML, {
+      status: 503,
+      headers: {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+      },
+    });
+  };
+}

package/src/types.ts

@@ -0,0 +1,67 @@
+import type Stripe from "stripe";
+import type { Queries } from "@gigamusic/db";
+import type { StorageProvider } from "@gigamusic/storage";
+import type { EmailProvider, EmailBranding } from "@gigamusic/email";
+
+/** Cart item shape accepted by `createCheckoutHandler`. `id` is required for "release" / "track"; ignored for "catalog". */
+export interface CheckoutCartItem {
+  kind: "release" | "track" | "catalog";
+  id?: number;
+}
+
+export interface CheckoutDeps {
+  stripeSecret: string;
+  queries: Queries;
+  /** e.g. https://artist.com — used for success/cancel redirects. */
+  baseUrl: string;
+  /** Defaults to "/checkout/success". `?session_id={CHECKOUT_SESSION_ID}` is appended automatically. */
+  successPath?: string;
+  /** Defaults to "/cart". */
+  cancelPath?: string;
+  /** Defaults to "usd". */
+  currency?: string;
+  /**
+   * Catalog discount applied to "buy the whole catalog" line items. Can be a
+   * literal value or an async callback resolved at request time — use the
+   * callback when the discount lives in a settings table that admins edit.
+   * Resolving to `null`/`undefined` disables the discount for that request.
+   */
+  catalogDiscount?:
+    | { percent: number; productName: string }
+    | (() => Promise<{ percent: number; productName: string } | null | undefined>);
+}
+
+export interface WebhookDeps {
+  /**
+   * Either a pre-built Stripe client (handy in tests, where the SDK is mocked
+   * at the consumer-app boundary) or a `stripeSecret` string the handler uses
+   * to construct one. Pass exactly one — `stripe` wins if both are provided.
+   */
+  stripe?: Stripe;
+  stripeSecret?: string;
+  webhookSecret: string;
+  queries: Queries;
+  email: EmailProvider;
+  branding: EmailBranding;
+  emailFrom: string;
+  baseUrl: string;
+  /** JWT secret for the magic-link order-verification token mailed to the customer. */
+  orderTokenSecret: string;
+  /** Defaults to "/orders/verify". */
+  verifyPath?: string;
+}
+
+export interface DownloadDeps {
+  queries: Queries;
+  storage: StorageProvider;
+  /** Optional second factor; the DB-stored token UUID remains the primary check. */
+  downloadTokenSecret?: string;
+  /**
+   * Optional artist-name prefix prepended to zip filenames — both the SW
+   * manifest and the server-side stream output use it. Example: passing
+   * `"My Artist"` yields `"My Artist - Order 12 (MP3).zip"`. Whitespace is
+   * trimmed and the joiner (`" - "`) is added automatically; empty / undefined
+   * leaves the brand-agnostic default (`"Order 12 (MP3).zip"`).
+   */
+  zipNamePrefix?: string;
+}

package/src/webhook.ts

@@ -0,0 +1,212 @@
+import { after, type NextRequest } from "next/server";
+import Stripe from "stripe";
+import { signOrderToken } from "@gigamusic/core";
+import type { ReleaseWithTracks, TrackWithFiles } from "@gigamusic/db";
+import { renderPurchaseConfirmation } from "@gigamusic/email";
+import type { WebhookDeps } from "./types.js";
+
+function isUniqueConstraintError(err: unknown): boolean {
+  return (
+    typeof err === "object" &&
+    err !== null &&
+    (err as { code?: string }).code === "P2002"
+  );
+}
+
+/**
+ * Build the POST handler for Stripe's webhook endpoint. Verifies the
+ * signature, records the order on `checkout.session.completed`, then defers
+ * the magic-link email via `after()` so Stripe sees a fast 200.
+ *
+ * Idempotency is enforced two ways: a pre-flight `getOrderByStripeSessionId`
+ * lookup, plus a P2002-unique-constraint catch around `recordCompletedOrder`
+ * for the case where two webhook deliveries race past the lookup. Both paths
+ * short-circuit with `{ received: true }` so Stripe doesn't retry.
+ *
+ * ### Published-only resolution (gotcha)
+ *
+ * The handler resolves the release/track IDs from `session.metadata` against
+ * `queries.listPublishedReleases()`. Anything not in the published catalog at
+ * the moment the webhook fires is silently dropped from the persisted order's
+ * line items — the customer is still charged, but the order row doesn't
+ * include the unpublished item.
+ *
+ * In the canonical flow this can't happen: `createCheckoutHandler` filters on
+ * the same `listPublishedReleases()` before it ever creates the Stripe
+ * Session. The only ways an unpublished ID can reach this handler are:
+ *  - an admin unpublishes between session-create and webhook-delivery
+ *    (a several-second race window),
+ *  - a consumer bypasses `createCheckoutHandler` and creates Stripe sessions
+ *    directly with their own metadata.
+ *
+ * If either of those is a realistic concern, swap the resolution call here
+ * to `listAllReleases()` (or wrap with a "warn + fallback" branch) — but be
+ * aware that doing so will surface unpublished items in admin order views.
+ */
+export function createStripeWebhookHandler(
+  deps: WebhookDeps,
+): (req: NextRequest) => Promise<Response> {
+  const {
+    stripe: stripeOverride,
+    stripeSecret,
+    webhookSecret,
+    queries,
+    email,
+    branding,
+    emailFrom,
+    baseUrl,
+    orderTokenSecret,
+    verifyPath = "/orders/verify",
+  } = deps;
+
+  if (!stripeOverride && !stripeSecret) {
+    throw new Error(
+      "createStripeWebhookHandler: must supply either `stripe` or `stripeSecret`",
+    );
+  }
+  const stripe =
+    stripeOverride ?? new Stripe(stripeSecret as string, { typescript: true });
+
+  return async (req: NextRequest): Promise<Response> => {
+    const body = await req.text();
+    const sig = req.headers.get("stripe-signature");
+
+    if (!sig) {
+      return Response.json({ error: "Missing signature" }, { status: 400 });
+    }
+
+    let event: Stripe.Event;
+    try {
+      event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
+    } catch {
+      return Response.json({ error: "Invalid signature" }, { status: 400 });
+    }
+
+    if (event.type !== "checkout.session.completed") {
+      return Response.json({ received: true });
+    }
+
+    const session = event.data.object as Stripe.Checkout.Session;
+
+    const existing = await queries.getOrderByStripeSessionId(session.id);
+    if (existing) {
+      return Response.json({ received: true });
+    }
+
+    const releaseIds = safeJsonIdList(session.metadata?.release_ids);
+    const trackIds = safeJsonIdList(session.metadata?.track_ids);
+
+    if (releaseIds.length === 0 && trackIds.length === 0) {
+      return Response.json({ received: true });
+    }
+
+    // Snapshot the published catalog once so we can resolve both release and
+    // track prices + names off a single in-memory lookup.
+    const allReleases = await queries.listPublishedReleases();
+    const releaseById = new Map(allReleases.map((r) => [r.id, r]));
+    const trackContext = new Map<
+      number,
+      { track: TrackWithFiles; release: ReleaseWithTracks }
+    >();
+    for (const release of allReleases) {
+      for (const track of release.tracks) {
+        trackContext.set(track.id, { track, release });
+      }
+    }
+
+    const matchedReleases = releaseIds
+      .map((id) => releaseById.get(id))
+      .filter((r): r is ReleaseWithTracks => r !== undefined);
+    const matchedTracks = trackIds
+      .map((id) => trackContext.get(id))
+      .filter(
+        (c): c is { track: TrackWithFiles; release: ReleaseWithTracks } =>
+          c !== undefined,
+      );
+
+    const orderItems = [
+      ...matchedReleases.map((r) => ({ releaseId: r.id, price: r.price })),
+      ...matchedTracks.map(({ track }) => ({ trackId: track.id, price: track.price })),
+    ];
+
+    const customerEmail = session.customer_details?.email ?? "";
+
+    let recordedOrder;
+    try {
+      recordedOrder = await queries.recordCompletedOrder({
+        stripeSessionId: session.id,
+        stripePaymentId:
+          typeof session.payment_intent === "string" ? session.payment_intent : null,
+        email: customerEmail,
+        amountTotal: session.amount_total ?? 0,
+        items: orderItems,
+      });
+    } catch (err) {
+      // Two deliveries can both pass the pre-flight lookup and race here. The
+      // unique constraint on `stripeSessionId` guarantees only one row lands;
+      // the loser surfaces as P2002. Treat that as the same idempotent
+      // short-circuit — no email, no 500, no Stripe retry.
+      if (isUniqueConstraintError(err)) {
+        return Response.json({ received: true });
+      }
+      throw err;
+    }
+
+    if (!customerEmail) {
+      // Stripe almost always supplies an email but doesn't guarantee it. The
+      // order is safely recorded; manual intervention required to deliver the
+      // magic link.
+      console.warn(
+        `[stripe-webhook] checkout.session.completed (session=${session.id}) has no customer_details.email — order recorded but customer cannot retrieve downloads.`,
+      );
+      return Response.json({ received: true });
+    }
+
+    const itemNames = [
+      ...matchedReleases.map((r) => r.name),
+      ...matchedTracks.map(({ track, release }) => `${release.name} — ${track.name}`),
+    ];
+
+    after(async () => {
+      try {
+        const verifyToken = await signOrderToken({
+          orderId: String(recordedOrder.id),
+          email: customerEmail,
+          secret: orderTokenSecret,
+        });
+        const verifyUrl = `${baseUrl}${verifyPath}?token=${verifyToken}`;
+        const { subject, html } = renderPurchaseConfirmation({
+          branding,
+          verifyUrl,
+          itemNames,
+          totalCents: session.amount_total ?? 0,
+        });
+        await email.send({
+          from: emailFrom,
+          to: customerEmail,
+          subject,
+          html,
+        });
+      } catch (err) {
+        console.error(
+          `[stripe-webhook] failed to send purchase confirmation to ${customerEmail} for session ${session.id}:`,
+          err,
+        );
+      }
+    });
+
+    return Response.json({ received: true });
+  };
+}
+
+/** Parse a JSON-stringified id array from Stripe metadata, returning `[]` on any failure. NaN entries are dropped. */
+function safeJsonIdList(value: string | undefined | null): number[] {
+  if (!value) return [];
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.map((v) => Number(v)).filter((n) => Number.isFinite(n));
+  } catch {
+    return [];
+  }
+}

package/src/zip-stream.ts

@@ -0,0 +1,156 @@
+import type { NextRequest } from "next/server";
+import { Readable, Transform } from "node:stream";
+import { finished } from "node:stream/promises";
+import type { ReadableStream as NodeReadableStream } from "node:stream/web";
+import archiver from "archiver";
+import type { DownloadDeps } from "./types.js";
+import { resolveZipBundle } from "./zip.js";
+
+interface RouteContext {
+  params: Promise<{ token: string }>;
+}
+
+/**
+ * Server-side bulk-download fallback. Mirrors `createDownloadZipHandler`'s
+ * auth + file-list logic via the shared `resolveZipBundle()`, but streams
+ * a real zip back to the browser through `archiver` instead of returning
+ * a manifest for a service worker to assemble.
+ *
+ * When to wire this up: in addition to `createDownloadZipHandler`. Browsers
+ * that can't run the service worker reliably (WebKit — Safari desktop and
+ * every iOS browser, plus private/incognito on most engines) get truncated
+ * archives from the SW path. Detect those browsers at click time on the
+ * client and hard-navigate here instead.
+ *
+ * Cost trade-off: audio bytes proxy through the serverless function and
+ * cost egress, which is why the SW path stays the default for browsers
+ * that handle it correctly.
+ *
+ * Per-file failure policy matches the SW: any failed storage fetch becomes
+ * a `_FAILED_<name>.txt` placeholder so one bad object doesn't taint the
+ * whole archive.
+ */
+export function createDownloadZipStreamHandler(
+  deps: DownloadDeps,
+): (req: NextRequest, ctx: RouteContext) => Promise<Response> {
+  const { queries, storage } = deps;
+
+  return async (req: NextRequest, ctx: RouteContext): Promise<Response> => {
+    const { token } = await ctx.params;
+    const url = new URL(req.url);
+
+    const resolution = await resolveZipBundle({
+      queries,
+      token,
+      releaseId: url.searchParams.get("releaseId"),
+      trackIdsParam: url.searchParams.get("trackIds"),
+      format: url.searchParams.get("format") ?? "mp3",
+      zipNamePrefix: deps.zipNamePrefix,
+    });
+    if (!resolution.ok) {
+      return Response.json({ error: resolution.error }, { status: resolution.status });
+    }
+
+    // `store: true` = no DEFLATE compression. MP3/WAV barely compress, and
+    // the SW path serves uncompressed entries — staying consistent means
+    // identical byte counts across the two routes.
+    const archive = archiver("zip", { store: true });
+
+    archive.on("error", (err) => {
+      console.error("[zip-stream] archiver error:", err);
+    });
+
+    // Tear the pipeline down if the client disconnects mid-download.
+    req.signal.addEventListener("abort", () => archive.abort());
+
+    // Serialise storage fetches: only open file N's socket after archiver
+    // has fully consumed file N-1. The naive parallel approach (open every
+    // socket up front, let archiver drain them in order) leaves the later
+    // sockets idle behind backpressure long enough for upstream R2/S3 to
+    // time them out, surfacing as `TypeError: terminated` mid-stream. A
+    // serial pipeline costs one TTFB per file transition — small compared
+    // to the per-file streaming time — and archiver is the serial
+    // bottleneck anyway, so end-to-end throughput is unchanged.
+    (async () => {
+      for (const file of resolution.files) {
+        if (req.signal.aborted) return;
+        const baseName = file.fileName.split("/").pop() || file.fileName;
+        try {
+          const url = await storage.getPresignedDownloadUrl(file.storageKey, {
+            filename: baseName,
+            contentType: file.contentType,
+          });
+          const res = await fetch(url, { signal: req.signal });
+          if (!res.ok || !res.body) throw new Error(`HTTP ${res.status}`);
+          // DOM `ReadableStream` and Node's web `ReadableStream` are
+          // runtime-compatible but typed separately — cast at the boundary.
+          const body = Readable.fromWeb(
+            res.body as unknown as NodeReadableStream<Uint8Array>,
+          );
+          // Pass-through counter for two reasons: we get a meaningful
+          // "bytesReceived" in failure logs, and `archiver.append(counter)`
+          // gives us a handle the `finished()` await below can resolve on
+          // (archiver's internal entry isn't exposed).
+          let bytesReceived = 0;
+          const counter = new Transform({
+            transform(chunk: Buffer, _enc, cb) {
+              bytesReceived += chunk.length;
+              cb(null, chunk);
+            },
+          });
+          // Forward upstream errors onto the counter so the `finished`
+          // await rejects and the loop can append a _FAILED_ placeholder.
+          body.on("error", (err) => counter.destroy(err));
+          body.pipe(counter);
+          archive.append(counter, { name: file.fileName });
+          try {
+            // Resolves once both sides of `counter` are done: body has
+            // ended (upstream finished) AND archiver has drained the
+            // readable side (entry fully written to the zip queue).
+            await finished(counter);
+          } catch (err) {
+            if (req.signal.aborted) return;
+            const detail = err instanceof Error ? err.message : String(err);
+            console.error(
+              `[zip-stream] body stream error for ${file.fileName} ` +
+                `(storageKey=${file.storageKey}, bytesReceived=${bytesReceived}): ${detail}`,
+            );
+            try {
+              archive.append(
+                `Streaming "${file.fileName}" from storage failed after ${bytesReceived} bytes: ${detail}.\n` +
+                  `Try downloading the track individually from your order page.\n`,
+                { name: `_FAILED_${baseName}.txt` },
+              );
+            } catch (appendErr) {
+              console.warn(
+                `[zip-stream] could not append failure placeholder for ${file.fileName}:`,
+                appendErr,
+              );
+            }
+          }
+        } catch (err) {
+          if (req.signal.aborted) return;
+          const detail = err instanceof Error ? err.message : String(err);
+          console.warn(`[zip-stream] fetch failed for ${file.fileName}:`, detail);
+          archive.append(
+            `Failed to download "${file.fileName}" from storage: ${detail}.\n` +
+              `Try downloading the track individually from your order page.\n`,
+            { name: `_FAILED_${baseName}.txt` },
+          );
+        }
+      }
+      await archive.finalize();
+    })().catch((err) => {
+      console.error("[zip-stream] pipeline error:", err);
+      archive.abort();
+    });
+
+    return new Response(Readable.toWeb(archive) as ReadableStream<Uint8Array>, {
+      headers: {
+        "Content-Type": "application/zip",
+        "Content-Disposition": `attachment; filename="${resolution.zipName.replace(/"/g, "")}"`,
+        "Cache-Control": "no-store",
+      },
+    });
+  };
+}

package/src/zip.ts

@@ -0,0 +1,418 @@
+import type { NextRequest } from "next/server";
+import type {
+  OrderWithItems,
+  Queries,
+  ReleaseWithTracks,
+  TrackWithFiles,
+} from "@gigamusic/db";
+import type { StorageProvider } from "@gigamusic/storage";
+import type { DownloadDeps } from "./types.js";
+import { cleanDownloadFilename } from "./download.js";
+
+interface RouteContext {
+  params: Promise<{ token: string }>;
+}
+
+/** A file destined for the zip, paired with the storage object it streams from. */
+export interface ZipFile {
+  fileName: string;
+  storageKey: string;
+  contentType: string;
+}
+
+interface ZipManifest {
+  zipName: string;
+  files: { fileName: string; url: string }[];
+}
+
+/**
+ * Discriminated result of `resolveZipBundle` — the SW-manifest handler and
+ * the server-side streaming handler both call this so they produce
+ * byte-identical archives. `ok: false` carries the HTTP status the caller
+ * should return.
+ */
+export type ResolveZipResult =
+  | { ok: true; zipName: string; files: ZipFile[] }
+  | { ok: false; status: number; error: string };
+
+export interface ResolveZipArgs {
+  queries: Queries;
+  token: string;
+  /** Single-release download; falsy means "whole order or selected tracks". */
+  releaseId?: number | string | null;
+  /** Comma-separated track IDs for partial-order downloads. */
+  trackIdsParam?: string | null;
+  /** "mp3" or "wav". */
+  format?: string;
+  /** Optional artist-name prefix; see `DownloadDeps.zipNamePrefix`. */
+  zipNamePrefix?: string;
+}
+
+/** Prepend the artist prefix when configured; otherwise return `base` untouched. */
+function applyZipNamePrefix(prefix: string | undefined, base: string): string {
+  const trimmed = prefix?.trim();
+  return trimmed ? `${trimmed} - ${base}` : base;
+}
+
+/**
+ * Auth + file-list resolution for a customer's bulk download. The
+ * `createDownloadZipHandler` (SW manifest path) and
+ * `createDownloadZipStreamHandler` (server-side streaming path) both call
+ * this so the two routes stay in lockstep on auth and on what ends up
+ * in the archive.
+ */
+export async function resolveZipBundle(args: ResolveZipArgs): Promise<ResolveZipResult> {
+  const { queries, token } = args;
+  const format = args.format ?? "mp3";
+  const audioContentType = format === "wav" ? "audio/wav" : "audio/mpeg";
+  const releaseIdRaw = args.releaseId == null ? null : String(args.releaseId);
+  const trackIdsParam = args.trackIdsParam ?? null;
+
+  const downloadToken = await queries.getDownloadToken(token);
+  if (!downloadToken) {
+    return { ok: false, status: 404, error: "Invalid download link" };
+  }
+
+  const order = await queries.getOrderById(downloadToken.orderId);
+  if (!order) {
+    return { ok: false, status: 404, error: "Invalid download link" };
+  }
+
+  return resolveBundle({
+    order,
+    releaseId: releaseIdRaw,
+    trackIdsParam,
+    format,
+    audioContentType,
+    zipNamePrefix: args.zipNamePrefix,
+  });
+}
+
+/**
+ * Build the GET handler for the zip-manifest endpoint. Returns the JSON
+ * manifest the service worker (shipped from `@gigamusic/ui`'s
+ * `public/sw-zip.js`) consumes — the SW pipes presigned R2 URLs through
+ * `client-zip` and streams the archive straight from R2 to the browser, with
+ * the Vercel function never touching audio bytes.
+ *
+ * Query-param branches:
+ *  - `trackIds` set → curated track list, flat layout
+ *  - `releaseId` set → single-release bundle with cover art
+ *  - neither set → whole order (releases + à-la-carte tracks)
+ */
+export function createDownloadZipHandler(
+  deps: DownloadDeps,
+): (req: NextRequest, ctx: RouteContext) => Promise<Response> {
+  const { queries, storage } = deps;
+
+  return async (req: NextRequest, ctx: RouteContext): Promise<Response> => {
+    const { token } = await ctx.params;
+    const url = new URL(req.url);
+    const resolution = await resolveZipBundle({
+      queries,
+      token,
+      releaseId: url.searchParams.get("releaseId"),
+      trackIdsParam: url.searchParams.get("trackIds"),
+      format: url.searchParams.get("format") ?? "mp3",
+      zipNamePrefix: deps.zipNamePrefix,
+    });
+    if (!resolution.ok) {
+      return Response.json({ error: resolution.error }, { status: resolution.status });
+    }
+
+    const manifest: ZipManifest = {
+      zipName: resolution.zipName,
+      files: await presignZipFiles(storage, resolution.files),
+    };
+    return Response.json(manifest);
+  };
+}
+
+type Resolution =
+  | { ok: true; zipName: string; files: ZipFile[] }
+  | { ok: false; status: number; error: string };
+
+interface ResolveArgs {
+  order: OrderWithItems;
+  releaseId: string | null;
+  trackIdsParam: string | null;
+  format: string;
+  audioContentType: string;
+  zipNamePrefix?: string;
+}
+
+function resolveBundle(args: ResolveArgs): Resolution {
+  const { order, releaseId, trackIdsParam, format, audioContentType, zipNamePrefix } = args;
+  const fmt = format.toUpperCase();
+
+  if (trackIdsParam) {
+    return resolveTrackList(order, trackIdsParam, format, audioContentType, fmt, zipNamePrefix);
+  }
+  if (releaseId) {
+    const id = Number(releaseId);
+    if (!Number.isFinite(id)) {
+      return { ok: false, status: 404, error: "Release not found" };
+    }
+    return resolveSingleRelease(order, id, format, audioContentType, fmt, zipNamePrefix);
+  }
+  return resolveWholeOrder(order, format, audioContentType, fmt, zipNamePrefix);
+}
+
+function resolveTrackList(
+  order: OrderWithItems,
+  trackIdsParam: string,
+  format: string,
+  audioContentType: string,
+  fmt: string,
+  zipNamePrefix: string | undefined,
+): Resolution {
+  const requestedTrackIds = trackIdsParam
+    .split(",")
+    .map((s) => Number(s.trim()))
+    .filter((n) => Number.isFinite(n));
+  const ownership = trackOwnership(order);
+  const allOwned = requestedTrackIds.every((id) => ownership.owns(id));
+  if (!allOwned) {
+    return { ok: false, status: 403, error: "Track not in order" };
+  }
+
+  const files: ZipFile[] = [];
+  for (const id of requestedTrackIds) {
+    const ctx = ownership.locate(id);
+    if (!ctx) continue;
+    const file = ctx.track.files.find((f) => f.format === format);
+    if (!file) continue;
+    files.push({
+      fileName: zipEntryPath(ctx.release?.name ?? null, file.fileName),
+      storageKey: file.storageKey,
+      contentType: audioContentType,
+    });
+  }
+  if (files.length === 0) {
+    return {
+      ok: false,
+      status: 404,
+      error: "No audio files have been uploaded for these tracks yet.",
+    };
+  }
+  return {
+    ok: true,
+    zipName: applyZipNamePrefix(zipNamePrefix, `Tracks (${fmt}).zip`),
+    files,
+  };
+}
+
+function resolveSingleRelease(
+  order: OrderWithItems,
+  releaseId: number,
+  format: string,
+  audioContentType: string,
+  fmt: string,
+  zipNamePrefix: string | undefined,
+): Resolution {
+  const orderHasRelease = order.items.some((item) => item.releaseId === releaseId);
+  if (!orderHasRelease) {
+    return { ok: false, status: 403, error: "Release not in order" };
+  }
+
+  const release = order.items.find((item) => item.release?.id === releaseId)?.release;
+  if (!release) {
+    return { ok: false, status: 404, error: "Release not found" };
+  }
+
+  const files: ZipFile[] = release.tracks
+    .map((track) => {
+      const file = track.files.find((f) => f.format === format);
+      if (!file) return null;
+      return {
+        fileName: zipEntryPath(null, file.fileName),
+        storageKey: file.storageKey,
+        contentType: audioContentType,
+      } satisfies ZipFile;
+    })
+    .filter((f): f is ZipFile => f !== null);
+
+  if (files.length > 0 && release.coverImageUrl) {
+    files.push(...coverArtEntries(release.name, release.coverImageUrl, "", files));
+  }
+
+  if (files.length === 0) {
+    return {
+      ok: false,
+      status: 404,
+      error: "No audio files have been uploaded for these tracks yet.",
+    };
+  }
+  return {
+    ok: true,
+    zipName: applyZipNamePrefix(zipNamePrefix, `${release.name} (${fmt}).zip`),
+    files,
+  };
+}
+
+function resolveWholeOrder(
+  order: OrderWithItems,
+  format: string,
+  audioContentType: string,
+  fmt: string,
+  zipNamePrefix: string | undefined,
+): Resolution {
+  const releaseFiles: ZipFile[] = [];
+  const aLaCarteFiles: ZipFile[] = [];
+
+  for (const item of order.items) {
+    if (item.release) {
+      const release = item.release;
+      const entries: ZipFile[] = [];
+      for (const track of release.tracks) {
+        const file = track.files.find((f) => f.format === format);
+        if (!file) continue;
+        entries.push({
+          fileName: zipEntryPath(release.name, file.fileName),
+          storageKey: file.storageKey,
+          contentType: audioContentType,
+        });
+      }
+      if (entries.length > 0 && release.coverImageUrl) {
+        entries.push(
+          ...coverArtEntries(
+            release.name,
+            release.coverImageUrl,
+            `${sanitizeSegment(release.name)}/`,
+            entries,
+          ),
+        );
+      }
+      releaseFiles.push(...entries);
+    } else if (item.track) {
+      const track = item.track;
+      const release = track.release ?? null;
+      const file = track.files.find((f) => f.format === format);
+      if (!file) continue;
+      aLaCarteFiles.push({
+        fileName: zipEntryPath(release?.name ?? null, file.fileName),
+        storageKey: file.storageKey,
+        contentType: audioContentType,
+      });
+    }
+  }
+
+  const files = [...releaseFiles, ...aLaCarteFiles];
+  if (files.length === 0) {
+    return {
+      ok: false,
+      status: 404,
+      error: "No audio files have been uploaded for these tracks yet.",
+    };
+  }
+  return {
+    ok: true,
+    zipName: applyZipNamePrefix(zipNamePrefix, `Order ${order.id} (${fmt}).zip`),
+    files,
+  };
+}
+
+interface TrackContext {
+  track: TrackWithFiles;
+  release?: ReleaseWithTracks | null;
+}
+
+/** Index every track an order grants access to so the manifest resolver can both check ownership and locate file rows. */
+function trackOwnership(order: OrderWithItems) {
+  const byId = new Map<number, TrackContext>();
+  for (const item of order.items) {
+    if (item.release) {
+      for (const t of item.release.tracks) {
+        byId.set(t.id, { track: t, release: item.release });
+      }
+    }
+    if (item.track) {
+      byId.set(item.track.id, {
+        track: item.track,
+        release: (item.track.release as ReleaseWithTracks | null | undefined) ?? null,
+      });
+    }
+  }
+  return {
+    owns: (id: number) => byId.has(id),
+    locate: (id: number) => byId.get(id) ?? null,
+  };
+}
+
+/** Strip path separators so a release/track name can't spawn unintended zip subfolders. */
+export function sanitizeSegment(name: string): string {
+  return name.replace(/[/\\]+/g, "-").trim();
+}
+
+/**
+ * Detects extended-mix tracks from their filename. The catalog marks them
+ * inconsistently ("Extended", "(Extended)", "[EXTENDED MIX]"), so a loose
+ * whole-word match on "extended" catches every variant.
+ */
+export function isExtendedMix(fileName: string): boolean {
+  return /\bextended\b/i.test(fileName);
+}
+
+/**
+ * Build a zip entry path: `[Release Name/][Extended/]filename`. Extended mixes
+ * are nested in their own `Extended/` subfolder so they don't clutter the main
+ * release listing. `releaseName` is null for single-release zips (which stay
+ * flat apart from the `Extended/` split).
+ */
+export function zipEntryPath(releaseName: string | null, fileName: string): string {
+  const clean = cleanDownloadFilename(fileName);
+  const segments: string[] = [];
+  if (releaseName) segments.push(sanitizeSegment(releaseName));
+  if (isExtendedMix(clean)) segments.push("Extended");
+  segments.push(clean);
+  return segments.join("/");
+}
+
+/** Zip filename for a release's cover art. */
+export function coverArtFilename(releaseName: string): string {
+  return `${sanitizeSegment(releaseName)} - COVER ART.jpg`;
+}
+
+/**
+ * Cover-art zip entries for a release: the artwork alongside the tracks, plus
+ * a duplicate inside the `Extended/` subfolder when any track entry uses one.
+ * `folder` is the release's `Name/` prefix for multi-release zips, or "" for
+ * flat single-release zips.
+ */
+export function coverArtEntries(
+  releaseName: string,
+  coverImageUrl: string,
+  folder: string,
+  trackEntries: ZipFile[],
+): ZipFile[] {
+  const file = coverArtFilename(releaseName);
+  const entries: ZipFile[] = [
+    { fileName: `${folder}${file}`, storageKey: coverImageUrl, contentType: "image/jpeg" },
+  ];
+  if (trackEntries.some((e) => e.fileName.split("/").includes("Extended"))) {
+    entries.push({
+      fileName: `${folder}Extended/${file}`,
+      storageKey: coverImageUrl,
+      contentType: "image/jpeg",
+    });
+  }
+  return entries;
+}
+
+/** Presign every zip entry into the `{ fileName, url }` manifest shape the service worker consumes. */
+async function presignZipFiles(
+  storage: StorageProvider,
+  files: ZipFile[],
+): Promise<ZipManifest["files"]> {
+  return Promise.all(
+    files.map(async (t) => ({
+      fileName: t.fileName,
+      url: await storage.getPresignedDownloadUrl(t.storageKey, {
+        filename: t.fileName.split("/").pop() ?? t.fileName,
+        contentType: t.contentType,
+      }),
+    })),
+  );
+}
+
+export type { Queries };