@gigamusic/checkout 4.6.0 → 4.8.0

package/src/checkout.ts

@@ -32,20 +32,24 @@ function resolveUnitAmount(
 }
 
 /**
- * Split a bundle's charged total across its member releases, proportional to
- * list price, using largest-remainder allocation.
+ * Split a bundle's charged total across its members, proportional to list
+ * price, using largest-remainder allocation.
+ *
+ * Members are keyed by their `amounts`-metadata key (`r<id>` / `t<id>`) rather
+ * than a bare numeric id, so a bundle holding tracks can't have a track id
+ * collide with a release id.
  *
  * The returned values sum to `totalCents` exactly. That's load-bearing: they
  * become the `amounts` metadata `fulfillCheckoutSession` turns into
  * `order_items.price` rows, and `sum(order_items) === orders.amountTotal` is
  * what refunds and admin order views rely on. Ties break deterministically
- * (remainder desc, price desc, id asc) so a retry apportions identically.
+ * (remainder desc, price desc, key asc) so a retry apportions identically.
  */
 function apportion(
   totalCents: number,
-  members: { id: number; price: number }[],
-): Map<number, number> {
-  const result = new Map<number, number>();
+  members: { key: string; price: number }[],
+): Map<string, number> {
+  const result = new Map<string, number>();
   if (members.length === 0) return result;
 
   const total = Math.max(0, Math.round(totalCents));
@@ -61,8 +65,8 @@ function apportion(
   let remainder = total - base.reduce((s, v) => s + v, 0);
 
   const order = members
-    .map((m, i) => ({ i, frac: exact[i]! - base[i]!, price: m.price, id: m.id }))
-    .sort((a, b) => b.frac - a.frac || b.price - a.price || a.id - b.id);
+    .map((m, i) => ({ i, frac: exact[i]! - base[i]!, price: m.price, key: m.key }))
+    .sort((a, b) => b.frac - a.frac || b.price - a.price || a.key.localeCompare(b.key));
 
   for (const { i } of order) {
     if (remainder <= 0) break;
@@ -70,7 +74,7 @@ function apportion(
     remainder -= 1;
   }
 
-  members.forEach((m, i) => result.set(m.id, base[i]!));
+  members.forEach((m, i) => result.set(m.key, base[i]!));
   return result;
 }
 
@@ -284,20 +288,29 @@ export function createCheckoutHandler(
         });
 
       // Bundles resolve against the same published-release snapshot as the
-      // loose lines, so member prices, names, and covers stay consistent.
+      // loose lines, so member prices, names, and covers stay consistent. A
+      // bundle may hold releases, tracks, or both — the package doesn't care
+      // which; the consumer decides what a bundle is allowed to contain.
       const bundleLineItems: typeof releaseLineItems = [];
-      const bundleMemberIds: number[] = [];
+      const bundleReleaseMemberIds: number[] = [];
+      const bundleTrackMemberIds: number[] = [];
       const unavailableBundleIds: string[] = [];
 
       for (const bundleId of bundleIds) {
         const resolved = await bundlePurchase!(bundleId);
-        const members = (resolved?.releaseIds ?? [])
+        const releaseMembers = (resolved?.releaseIds ?? [])
           .map((id) => releaseById.get(id))
           .filter((r): r is ReleaseWithTracks => r !== undefined);
+        const trackMembers = (resolved?.trackIds ?? [])
+          .map((id) => trackContext.get(id))
+          .filter(
+            (c): c is { track: TrackWithFiles; release: ReleaseWithTracks } =>
+              c !== undefined,
+          );
 
         // No such bundle, or nothing in it is published any more. Charging for
         // the latter would produce a paid order with zero items.
-        if (!resolved || members.length === 0) {
+        if (!resolved || releaseMembers.length + trackMembers.length === 0) {
           unavailableBundleIds.push(bundleId);
           continue;
         }
@@ -306,7 +319,11 @@ export function createCheckoutHandler(
           STRIPE_MIN_CHARGE_CENTS,
           Math.round(resolved.totalCents),
         );
-        const cover = members.find((m) => m.coverImageUrl)?.coverImageUrl;
+        // A track carries no cover of its own, so a track-only bundle falls
+        // back to the cover of the release the first member belongs to.
+        const cover =
+          releaseMembers.find((m) => m.coverImageUrl)?.coverImageUrl ??
+          trackMembers.find((c) => c.release.coverImageUrl)?.release.coverImageUrl;
         bundleLineItems.push({
           price_data: {
             currency,
@@ -319,13 +336,16 @@ export function createCheckoutHandler(
           quantity: 1 as const,
         });
 
-        for (const [id, cents] of apportion(
-          total,
-          members.map((m) => ({ id: m.id, price: m.price })),
-        )) {
-          chargedAmounts[`r${id}`] = (chargedAmounts[`r${id}`] ?? 0) + cents;
-          bundleMemberIds.push(id);
+        // Apportioned jointly across both member kinds — the total has to land
+        // on the members as one set, not split per kind and rounded twice.
+        for (const [key, cents] of apportion(total, [
+          ...releaseMembers.map((m) => ({ key: `r${m.id}`, price: m.price })),
+          ...trackMembers.map(({ track }) => ({ key: `t${track.id}`, price: track.price })),
+        ])) {
+          chargedAmounts[key] = (chargedAmounts[key] ?? 0) + cents;
         }
+        bundleReleaseMemberIds.push(...releaseMembers.map((m) => m.id));
+        bundleTrackMemberIds.push(...trackMembers.map(({ track }) => track.id));
       }
 
       if (unavailableBundleIds.length > 0) {
@@ -340,17 +360,21 @@ export function createCheckoutHandler(
         return jsonError("No valid items found", 400);
       }
 
-      // Deduped: a release reachable from both a bundle and a loose line still
-      // yields one order item, whose price is the summed `amounts` entry.
+      // Deduped: a release or track reachable from both a bundle and a loose
+      // line still yields one order item, whose price is the summed `amounts`
+      // entry.
       const resolvedReleaseIds = [
         ...new Set([
           ...(releaseLineItems.length ? releaseIds.filter((id) => releaseById.has(id)) : []),
-          ...bundleMemberIds,
+          ...bundleReleaseMemberIds,
+        ]),
+      ];
+      const resolvedTrackIds = [
+        ...new Set([
+          ...(trackLineItems.length ? trackIds.filter((id) => trackContext.has(id)) : []),
+          ...bundleTrackMemberIds,
         ]),
       ];
-      const resolvedTrackIds = trackLineItems.length
-        ? [...new Set(trackIds.filter((id) => trackContext.has(id)))]
-        : [];
 
       const session = await stripe.checkout.sessions.create({
         mode: "payment",

package/src/download.ts

@@ -1,6 +1,7 @@
 import type { NextRequest } from "next/server";
-import type { Queries, TrackFile } from "@gigamusic/db";
+import type { Queries } from "@gigamusic/db";
 import type { DownloadDeps } from "./types.js";
+import { cleanDownloadFilename, coverArtFilename } from "./filenames.js";
 
 interface RouteContext {
   params: Promise<{ token: string }>;
@@ -13,9 +14,34 @@ interface RouteContext {
  * 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).
+ * Order of checks: locate the file first (so a missing-file is 404), *then*
+ * enforce the token-track grant (a wrong trackId for the given token is 403,
+ * not 404).
+ *
+ * One extra job beyond serving the order page's per-track buttons, in service
+ * of `createDownloadZipHandler`, whose manifest points every zip entry back
+ * here so the R2 signature is minted when the service worker actually reaches
+ * that file (see `zip.ts`): `?asset=cover&releaseId=…` serves a release's
+ * cover art, which isn't track-keyed and so has no `trackId` to address it by.
+ * That branch checks `queries.tokenGrantsRelease` instead.
+ *
+ * ### Lookups are keyed, not scanned
+ *
+ * Both branches resolve their target with a single keyed query
+ * (`getTrackFile` / `getReleaseById`). They must not go back to
+ * `listPublishedReleases()`: that pulls every published release with its
+ * tracks and files, and because zip manifests fan every entry through this
+ * route, one bulk download would issue that read once per file — dozens of
+ * full-catalog scans to serve a single archive, against the most expensive
+ * resource these sites have.
+ *
+ * Neither keyed query filters on `isPublished`, which is deliberate and is
+ * also what makes them a complete replacement for the catalog walk rather
+ * than a narrowing of it. Ownership is decided by the grant check below, not
+ * by catalog membership, so a release unpublished after purchase and an
+ * à-la-carte track belonging to no release both stay reachable to the customer
+ * who bought them — exactly the cases the zip resolver lists, since it reads
+ * the order rather than the catalog.
  */
 export function createDownloadHandler(
   deps: DownloadDeps,
@@ -25,9 +51,13 @@ export function createDownloadHandler(
   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 (requestUrl.searchParams.get("asset") === "cover") {
+      return handleCoverArt(deps, token, requestUrl.searchParams.get("releaseId"));
+    }
+
+    const trackIdRaw = requestUrl.searchParams.get("trackId");
     if (!trackIdRaw) {
       return Response.json({ error: "Missing trackId" }, { status: 400 });
     }
@@ -41,7 +71,7 @@ export function createDownloadHandler(
       return Response.json({ error: "Invalid download link" }, { status: 404 });
     }
 
-    const file = await findTrackFileInCatalog(queries, trackId, format);
+    const file = await queries.getTrackFile(trackId, format);
     if (!file) {
       return Response.json({ error: "File not found" }, { status: 404 });
     }
@@ -59,27 +89,44 @@ export function createDownloadHandler(
   };
 }
 
-/** 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;
+/** Serve `?asset=cover&releaseId=…` — the release-keyed twin of the track branch above. */
+async function handleCoverArt(
+  deps: DownloadDeps,
+  token: string,
+  releaseIdRaw: string | null,
+): Promise<Response> {
+  const { queries, storage } = deps;
+
+  if (!releaseIdRaw) {
+    return Response.json({ error: "Missing releaseId" }, { status: 400 });
+  }
+  const releaseId = Number(releaseIdRaw);
+  if (!Number.isFinite(releaseId)) {
+    return Response.json({ error: "Invalid releaseId" }, { status: 400 });
+  }
+
+  const downloadToken = await queries.getDownloadToken(token);
+  if (!downloadToken) {
+    return Response.json({ error: "Invalid download link" }, { status: 404 });
   }
-  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()}`;
+  const release = await queries.getReleaseById(releaseId);
+  if (!release?.coverImageUrl) {
+    return Response.json({ error: "File not found" }, { status: 404 });
+  }
+
+  const ok = await queries.tokenGrantsRelease(token, releaseId);
+  if (!ok) {
+    return Response.json({ error: "Release not in order" }, { status: 403 });
+  }
+
+  const url = await storage.getPresignedDownloadUrl(release.coverImageUrl, {
+    filename: coverArtFilename(release.name),
+    contentType: "image/jpeg",
+  });
+  return Response.redirect(url, 302);
 }
 
+export { cleanDownloadFilename };
+
 export type { Queries };

package/src/filenames.ts

@@ -0,0 +1,23 @@
+/**
+ * Filename helpers shared by the single-file download route and the zip
+ * routes. They live here rather than in either module because `download.ts`
+ * now serves cover art (and so needs `coverArtFilename`) while `zip.ts` needs
+ * `cleanDownloadFilename` — importing across the two directly would be a cycle.
+ */
+
+/** 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()}`;
+}
+
+/** 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();
+}
+
+/** Zip filename for a release's cover art. */
+export function coverArtFilename(releaseName: string): string {
+  return `${sanitizeSegment(releaseName)} - COVER ART.jpg`;
+}

package/src/index.ts

@@ -16,4 +16,5 @@ export type {
   PurchaseConfirmationDeps,
   ResolvedBundle,
   WebhookDeps,
+  ZipEntryFailure,
 } from "./types.js";

package/src/types.ts

@@ -74,9 +74,10 @@ export interface CheckoutDeps {
    *
    * Called once per distinct `bundleId` in the cart. As with the catalog, the
    * consumer owns pricing math: hand back the final `totalCents` and the
-   * member `releaseIds`, and the handler apportions the total across those
-   * members (proportional to list price, largest-remainder) so the recorded
-   * order items sum to exactly what Stripe charged.
+   * members (`releaseIds`, `trackIds`, or both), and the handler apportions
+   * the total across those members (proportional to list price,
+   * largest-remainder) so the recorded order items sum to exactly what Stripe
+   * charged.
    *
    * Resolving to `null`/`undefined` means "no such bundle" — the handler
    * replies 409 `{ error: "bundle-unavailable", bundleIds }` so the cart can
@@ -88,7 +89,14 @@ export interface CheckoutDeps {
   ) => Promise<ResolvedBundle | null | undefined> | ResolvedBundle | null | undefined;
 }
 
-/** What `bundlePurchase` returns for a bundle the consumer recognises. */
+/**
+ * What `bundlePurchase` returns for a bundle the consumer recognises.
+ *
+ * A bundle's members are `releaseIds`, `trackIds`, or both — the package
+ * imposes no rule about mixing them, so a consumer is free to model bundles as
+ * releases-only, singles-only, or a combination. Supply at least one member
+ * list; a bundle that resolves to no surviving member is reported unavailable.
+ */
 export interface ResolvedBundle {
   /** Final charged price for the whole bundle, in cents. Clamped up to the Stripe card minimum. */
   totalCents: number;
@@ -96,10 +104,16 @@ export interface ResolvedBundle {
   productName: string;
   /**
    * Member release ids. Resolved against `listPublishedReleases()` — ids that
-   * aren't published are dropped, and a bundle left with none is treated as
-   * unavailable rather than charging for an order with no items.
+   * aren't published are dropped, and a bundle left with no members at all is
+   * treated as unavailable rather than charging for an order with no items.
+   */
+  releaseIds?: number[];
+  /**
+   * Member track ids — individual songs, for a "bundle of singles". Resolved
+   * against the tracks of `listPublishedReleases()`, so a track whose release
+   * is unpublished is dropped on the same terms as an unpublished release.
    */
-  releaseIds: number[];
+  trackIds?: number[];
 }
 
 /** What `fulfillCheckoutSession` needs to turn a paid Stripe session into an order row. */
@@ -154,9 +168,50 @@ export interface WebhookDeps extends FulfillSessionDeps, PurchaseConfirmationDep
   webhookSecret: string;
 }
 
+/**
+ * One entry `createDownloadZipStreamHandler` could not stream into the
+ * archive. The customer still gets a zip — the entry is replaced by a
+ * `_FAILED_<name>.txt` placeholder so one bad object doesn't corrupt the rest
+ * — which is exactly why the failure needs surfacing somewhere the operator
+ * will see it: from the outside, a half-empty archive looks like a successful
+ * download.
+ */
+export interface ZipEntryFailure {
+  /** Download token whose bundle was being streamed — identifies the order. */
+  token: string;
+  /** Path of the entry inside the archive, e.g. `"Album/track.wav"`. */
+  fileName: string;
+  storageKey: string;
+  /** Message from the failed storage fetch or mid-stream error. */
+  reason: string;
+  /** Bytes received before the failure; 0 when the fetch never got going. */
+  bytesReceived: number;
+}
+
 export interface DownloadDeps {
   queries: Queries;
   storage: StorageProvider;
+  /**
+   * Path of the single-file download route (`createDownloadHandler`) that
+   * `createDownloadZipHandler`'s manifest addresses its entries through, with
+   * `{token}` as the placeholder — e.g. `"/downloads/{token}/file"`.
+   *
+   * Defaults to the manifest route's own path minus its last segment, which
+   * resolves to `/download/[token]` under the layout `docs/setup.md`
+   * prescribes. Only set this if you mount the two routes such that the
+   * relationship doesn't hold.
+   */
+  downloadPath?: string;
+  /**
+   * Called by `createDownloadZipStreamHandler` once per entry it fails to
+   * stream, so a broken bulk download can raise an alert instead of silently
+   * shipping a zip full of `_FAILED_*.txt` placeholders. Failures are also
+   * logged, with a per-request summary line carrying the failed/total count.
+   *
+   * Errors thrown here are swallowed — reporting must never take down a
+   * download that is otherwise still producing bytes.
+   */
+  onZipEntryFailure?: (failure: ZipEntryFailure) => void;
   /**
    * Optional artist-name prefix prepended to zip filenames — both the SW
    * manifest and the server-side stream output use it. Example: passing

package/src/zip-stream.ts

@@ -3,7 +3,7 @@ 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 type { DownloadDeps, ZipEntryFailure } from "./types.js";
 import { resolveZipBundle } from "./zip.js";
 
 interface RouteContext {
@@ -28,7 +28,18 @@ interface RouteContext {
  *
  * 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.
+ * whole archive. Because that turns a broken purchase into an
+ * apparently-successful download, every failure is reported through
+ * `deps.onZipEntryFailure` and summarised in a single log line at the end of
+ * the request.
+ *
+ * Unlike the manifest path, this handler presigns each file *inside* the loop,
+ * immediately before fetching it, so signature expiry can't bite. Its own
+ * ceiling is the platform's function timeout: audio bytes proxy through the
+ * function, so the whole archive has to be produced within `maxDuration`
+ * (Vercel: 300s by default, up to 800s on Fluid compute). Multi-gigabyte
+ * bundles need that raised in the consuming route — `export const maxDuration`
+ * — or they'll be cut off mid-stream.
  */
 export function createDownloadZipStreamHandler(
   deps: DownloadDeps,
@@ -63,6 +74,17 @@ export function createDownloadZipStreamHandler(
     // Tear the pipeline down if the client disconnects mid-download.
     req.signal.addEventListener("abort", () => archive.abort());
 
+    const failures: ZipEntryFailure[] = [];
+    /** Record one unusable entry and hand it to the consumer's reporter, never letting that reporter break the stream. */
+    const reportFailure = (failure: ZipEntryFailure) => {
+      failures.push(failure);
+      try {
+        deps.onZipEntryFailure?.(failure);
+      } catch (err) {
+        console.warn("[zip-stream] onZipEntryFailure threw:", err);
+      }
+    };
+
     // 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
@@ -115,6 +137,13 @@ export function createDownloadZipStreamHandler(
               `[zip-stream] body stream error for ${file.fileName} ` +
                 `(storageKey=${file.storageKey}, bytesReceived=${bytesReceived}): ${detail}`,
             );
+            reportFailure({
+              token,
+              fileName: file.fileName,
+              storageKey: file.storageKey,
+              reason: detail,
+              bytesReceived,
+            });
             try {
               archive.append(
                 `Streaming "${file.fileName}" from storage failed after ${bytesReceived} bytes: ${detail}.\n` +
@@ -132,6 +161,13 @@ export function createDownloadZipStreamHandler(
           if (req.signal.aborted) return;
           const detail = err instanceof Error ? err.message : String(err);
           console.warn(`[zip-stream] fetch failed for ${file.fileName}:`, detail);
+          reportFailure({
+            token,
+            fileName: file.fileName,
+            storageKey: file.storageKey,
+            reason: detail,
+            bytesReceived: 0,
+          });
           archive.append(
             `Failed to download "${file.fileName}" from storage: ${detail}.\n` +
               `Try downloading the track individually from your order page.\n`,
@@ -139,6 +175,12 @@ export function createDownloadZipStreamHandler(
           );
         }
       }
+      if (failures.length > 0) {
+        console.error(
+          `[zip-stream] ${failures.length}/${resolution.files.length} entries failed ` +
+            `for token ${token}: ${failures.map((f) => f.fileName).join(", ")}`,
+        );
+      }
       await archive.finalize();
     })().catch((err) => {
       console.error("[zip-stream] pipeline error:", err);