@gigamusic/checkout 4.7.0 → 4.8.0

package/README.md

@@ -14,6 +14,58 @@ export const POST = createCheckoutHandler({
 });
 ```
 
+## Bulk downloads and URL expiry
+
+`createDownloadZipHandler` returns a manifest of `{ fileName, url }` for the
+service worker to stream through `client-zip`. Those URLs point back at
+**`createDownloadHandler` on the same origin**, not directly at presigned
+storage URLs — the 302 mints the signature at the moment the SW reaches that
+entry.
+
+That matters because the SW fetches entries strictly sequentially (a zip is a
+sequential format; `client-zip` drains one body before opening the next), so a
+multi-gigabyte bundle is still working through the list long after the click.
+Signing every URL up front gave each one the storage default of 5 minutes;
+everything past minute five 403'd, and because R2's signature failures carry no
+CORS headers the SW saw an opaque `NetworkError` rather than a readable status
+and wrote a `_FAILED_*.txt` placeholder — a broken download that looks
+successful.
+
+Two things follow for consumers:
+
+- **`/download/[token]` must be mounted** for bulk downloads to work. It always
+  was, for the per-track buttons; it's now load-bearing for zips too. If the
+  manifest route isn't a direct child of it, set `downloadPath` (e.g.
+  `"/files/{token}/get"`).
+- Cover art is addressed as `?asset=cover&releaseId=…`, tracks as
+  `?trackId=…&format=…`. Both check the token grant.
+
+The manifest shape is unchanged, so an already-deployed service worker needs no
+edits.
+
+`createDownloadZipStreamHandler` (the server-side fallback) always signed
+per-file inside its loop, so it never had the expiry bug. Its ceiling is the
+platform function timeout instead — audio proxies through the function, so
+large bundles need `export const maxDuration` raised in the route.
+
+### Knowing when a bulk download broke
+
+The per-file `_FAILED_<name>.txt` policy keeps one bad object from corrupting
+the whole archive, at the cost of making a broken purchase look like a
+successful download. Pass `onZipEntryFailure` to hear about them:
+
+```ts
+export const GET = createDownloadZipStreamHandler({
+  queries,
+  storage,
+  onZipEntryFailure: ({ token, fileName, reason }) =>
+    alerting.warn(`zip entry failed: ${fileName} (${token}): ${reason}`),
+});
+```
+
+Failures are also logged individually plus an `n/total entries failed` summary
+line per request, so they're greppable without wiring anything up.
+
 ## Bundles — discounted subsets of the catalog
 
 `catalogPurchase` is all-or-nothing. For a curated pack ("the remix EPs", "2024

package/dist/index.d.ts

@@ -158,9 +158,49 @@ interface WebhookDeps extends FulfillSessionDeps, PurchaseConfirmationDeps {
     stripeSecret?: string;
     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.
+ */
+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;
+}
 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
@@ -284,9 +324,34 @@ interface RouteContext$2 {
  * 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.
  */
 declare function createDownloadHandler(deps: DownloadDeps): (req: NextRequest, ctx: RouteContext$2) => Promise<Response>;
 
@@ -298,9 +363,21 @@ interface RouteContext$1 {
 /**
  * Build the GET handler for the zip-manifest endpoint. Returns the JSON
  * manifest the consumer-shipped service worker (`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.
+ * consumes — the SW pipes each URL through `client-zip` and streams the
+ * archive straight from storage to the browser, with the serverless function
+ * never touching audio bytes.
+ *
+ * Manifest URLs point back at `createDownloadHandler` on this same origin
+ * rather than directly at presigned R2 URLs. That route 302s to a *freshly*
+ * signed URL, so the signature is minted at the moment the SW reaches that
+ * entry — however many hours into the archive that is. Signing everything up
+ * front meant every URL in a multi-gigabyte bundle died 5 minutes after the
+ * click; see `ZIP_MANIFEST_EXPIRES_IN_SECONDS`. The redirect adds one cheap
+ * function invocation per file and gives failures a server-side trace they
+ * never had while the SW talked straight to R2.
+ *
+ * The manifest shape (`{ zipName, files: [{ fileName, url }] }`) is unchanged,
+ * so an already-deployed service worker keeps working without modification.
  *
  * Query-param branches:
  *  - `trackIds` set → curated track list, flat layout
@@ -332,7 +409,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.
  */
 declare function createDownloadZipStreamHandler(deps: DownloadDeps): (req: NextRequest, ctx: RouteContext) => Promise<Response>;
 
@@ -353,4 +441,4 @@ declare function createDownloadZipStreamHandler(deps: DownloadDeps): (req: NextR
  */
 declare function createSwZipFallbackHandler(): () => Response;
 
-export { type CheckoutCartItem, type CheckoutDeps, type DownloadDeps, type FulfillSessionDeps, type FulfillSessionResult, type PurchaseConfirmationDeps, type ResolvedBundle, type WebhookDeps, createCheckoutHandler, createDownloadHandler, createDownloadZipHandler, createDownloadZipStreamHandler, createStripeWebhookHandler, createSwZipFallbackHandler, fulfillCheckoutSession, sendPurchaseConfirmation };
+export { type CheckoutCartItem, type CheckoutDeps, type DownloadDeps, type FulfillSessionDeps, type FulfillSessionResult, type PurchaseConfirmationDeps, type ResolvedBundle, type WebhookDeps, type ZipEntryFailure, createCheckoutHandler, createDownloadHandler, createDownloadZipHandler, createDownloadZipStreamHandler, createStripeWebhookHandler, createSwZipFallbackHandler, fulfillCheckoutSession, sendPurchaseConfirmation };

package/dist/index.js

@@ -433,14 +433,30 @@ function createStripeWebhookHandler(deps) {
   };
 }
 
+// src/filenames.ts
+function cleanDownloadFilename(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return name.trim();
+  return `${name.slice(0, dot).trim()}${name.slice(dot).trim()}`;
+}
+function sanitizeSegment(name) {
+  return name.replace(/[/\\]+/g, "-").trim();
+}
+function coverArtFilename(releaseName) {
+  return `${sanitizeSegment(releaseName)} - COVER ART.jpg`;
+}
+
 // src/download.ts
 function createDownloadHandler(deps) {
   const { queries, storage } = deps;
   return async (req, ctx) => {
     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 });
     }
@@ -452,7 +468,7 @@ function createDownloadHandler(deps) {
     if (!downloadToken) {
       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 });
     }
@@ -467,23 +483,36 @@ function createDownloadHandler(deps) {
     return Response.redirect(url, 302);
   };
 }
-async function findTrackFileInCatalog(queries, trackId, format) {
-  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;
+async function handleCoverArt(deps, token, releaseIdRaw) {
+  const { queries, storage } = deps;
+  if (!releaseIdRaw) {
+    return Response.json({ error: "Missing releaseId" }, { status: 400 });
   }
-  return null;
-}
-function cleanDownloadFilename(name) {
-  const dot = name.lastIndexOf(".");
-  if (dot <= 0) return name.trim();
-  return `${name.slice(0, dot).trim()}${name.slice(dot).trim()}`;
+  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 });
+  }
+  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);
 }
 
 // src/zip.ts
+var ZIP_MANIFEST_EXPIRES_IN_SECONDS = 12 * 60 * 60;
 function applyZipNamePrefix(prefix, base) {
   const trimmed = prefix?.trim();
   return trimmed ? `${trimmed} - ${base}` : base;
@@ -529,7 +558,11 @@ function createDownloadZipHandler(deps) {
     }
     const manifest = {
       zipName: resolution.zipName,
-      files: await presignZipFiles(storage, resolution.files)
+      files: await buildManifestFiles(
+        storage,
+        resolution.files,
+        downloadRouteUrl(url, token, deps.downloadPath)
+      )
     };
     return Response.json(manifest);
   };
@@ -565,7 +598,8 @@ function resolveTrackList(order, trackIdsParam, format, audioContentType, fmt, z
     files.push({
       fileName: zipEntryPath(ctx.release?.name ?? null, file.fileName),
       storageKey: file.storageKey,
-      contentType: audioContentType
+      contentType: audioContentType,
+      source: { kind: "track", trackId: id, format }
     });
   }
   if (files.length === 0) {
@@ -596,11 +630,12 @@ function resolveSingleRelease(order, releaseId, format, audioContentType, fmt, z
     return {
       fileName: zipEntryPath(null, file.fileName),
       storageKey: file.storageKey,
-      contentType: audioContentType
+      contentType: audioContentType,
+      source: { kind: "track", trackId: track.id, format }
     };
   }).filter((f) => f !== null);
   if (files.length > 0 && release.coverImageUrl) {
-    files.push(...coverArtEntries(release.name, release.coverImageUrl, "", files));
+    files.push(...coverArtEntries(release, release.coverImageUrl, "", files));
   }
   if (files.length === 0) {
     return {
@@ -628,13 +663,14 @@ function resolveWholeOrder(order, format, audioContentType, fmt, zipNamePrefix)
         entries.push({
           fileName: zipEntryPath(release.name, file.fileName),
           storageKey: file.storageKey,
-          contentType: audioContentType
+          contentType: audioContentType,
+          source: { kind: "track", trackId: track.id, format }
         });
       }
       if (entries.length > 0 && release.coverImageUrl) {
         entries.push(
           ...coverArtEntries(
-            release.name,
+            release,
             release.coverImageUrl,
             `${sanitizeSegment(release.name)}/`,
             entries
@@ -650,7 +686,8 @@ function resolveWholeOrder(order, format, audioContentType, fmt, zipNamePrefix)
       aLaCarteFiles.push({
         fileName: zipEntryPath(release?.name ?? null, file.fileName),
         storageKey: file.storageKey,
-        contentType: audioContentType
+        contentType: audioContentType,
+        source: { kind: "track", trackId: track.id, format }
       });
     }
   }
@@ -688,9 +725,6 @@ function trackOwnership(order) {
     locate: (id) => byId.get(id) ?? null
   };
 }
-function sanitizeSegment(name) {
-  return name.replace(/[/\\]+/g, "-").trim();
-}
 function isExtendedMix(fileName) {
   return /\bextended\b/i.test(fileName);
 }
@@ -702,34 +736,62 @@ function zipEntryPath(releaseName, fileName) {
   segments.push(clean);
   return segments.join("/");
 }
-function coverArtFilename(releaseName) {
-  return `${sanitizeSegment(releaseName)} - COVER ART.jpg`;
-}
-function coverArtEntries(releaseName, coverImageUrl, folder, trackEntries) {
-  const file = coverArtFilename(releaseName);
+function coverArtEntries(release, coverImageUrl, folder, trackEntries) {
+  const file = coverArtFilename(release.name);
+  const source = { kind: "cover", releaseId: release.id };
   const entries = [
-    { fileName: `${folder}${file}`, storageKey: coverImageUrl, contentType: "image/jpeg" }
+    {
+      fileName: `${folder}${file}`,
+      storageKey: coverImageUrl,
+      contentType: "image/jpeg",
+      source
+    }
   ];
   if (trackEntries.some((e) => e.fileName.split("/").includes("Extended"))) {
     entries.push({
       fileName: `${folder}Extended/${file}`,
       storageKey: coverImageUrl,
-      contentType: "image/jpeg"
+      contentType: "image/jpeg",
+      source
     });
   }
   return entries;
 }
-async function presignZipFiles(storage, files) {
+function downloadRouteUrl(manifestUrl, token, downloadPath) {
+  if (downloadPath) {
+    return new URL(downloadPath.replace("{token}", encodeURIComponent(token)), manifestUrl);
+  }
+  const segments = manifestUrl.pathname.replace(/\/+$/, "").split("/");
+  segments.pop();
+  const url = new URL(manifestUrl.toString());
+  url.search = "";
+  url.hash = "";
+  url.pathname = segments.join("/") || "/";
+  return url;
+}
+async function buildManifestFiles(storage, files, downloadUrl) {
   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
+    files.map(async (file) => ({
+      fileName: file.fileName,
+      url: file.source ? sourceUrl(downloadUrl, file.source) : await storage.getPresignedDownloadUrl(file.storageKey, {
+        filename: file.fileName.split("/").pop() ?? file.fileName,
+        contentType: file.contentType,
+        expiresInSeconds: ZIP_MANIFEST_EXPIRES_IN_SECONDS
       })
     }))
   );
 }
+function sourceUrl(downloadUrl, source) {
+  const url = new URL(downloadUrl.toString());
+  if (source.kind === "track") {
+    url.searchParams.set("trackId", String(source.trackId));
+    url.searchParams.set("format", source.format);
+  } else {
+    url.searchParams.set("asset", "cover");
+    url.searchParams.set("releaseId", String(source.releaseId));
+  }
+  return url.toString();
+}
 function createDownloadZipStreamHandler(deps) {
   const { queries, storage } = deps;
   return async (req, ctx) => {
@@ -751,6 +813,15 @@ function createDownloadZipStreamHandler(deps) {
       console.error("[zip-stream] archiver error:", err);
     });
     req.signal.addEventListener("abort", () => archive.abort());
+    const failures = [];
+    const reportFailure = (failure) => {
+      failures.push(failure);
+      try {
+        deps.onZipEntryFailure?.(failure);
+      } catch (err) {
+        console.warn("[zip-stream] onZipEntryFailure threw:", err);
+      }
+    };
     (async () => {
       for (const file of resolution.files) {
         if (req.signal.aborted) return;
@@ -783,6 +854,13 @@ function createDownloadZipStreamHandler(deps) {
             console.error(
               `[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}.
@@ -801,6 +879,13 @@ Try downloading the track individually from your order page.
           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}.
 Try downloading the track individually from your order page.
@@ -809,6 +894,11 @@ Try downloading the track individually from your order page.
           );
         }
       }
+      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);