@gigamusic/checkout 4.6.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
@@ -38,28 +90,45 @@ export const POST = createCheckoutHandler({
 });
 ```
 
+A bundle's members can also be individual tracks — a "bundle of singles" —
+via `trackIds`. Both member lists are optional; supply at least one, and mix
+them freely if that's the product you're selling:
+
+```ts
+return {
+  totalCents: bundle.discountedPrice,
+  productName: `${bundle.name} (${bundle.trackIds.length} songs)`,
+  trackIds: bundle.trackIds,
+};
+```
+
 As with the catalog, the consumer owns pricing math. The handler:
 
 - clamps `totalCents` up to the Stripe card minimum;
-- resolves `releaseIds` against `listPublishedReleases()`, dropping any that
-  aren't published;
+- resolves `releaseIds` against `listPublishedReleases()` and `trackIds`
+  against those releases' tracks, dropping any that aren't published — a track
+  whose release is unpublished goes the same way as an unpublished release;
 - **apportions** the charged total across the surviving members, proportional
   to list price with largest-remainder rounding, so the `amounts` metadata sums
   to exactly what Stripe charged — and therefore so do the `order_items` rows
-  `fulfillCheckoutSession` writes;
+  `fulfillCheckoutSession` writes. Releases and tracks apportion as one set, so
+  a mixed bundle is split once rather than rounded twice;
 - stamps `bundle_ids` onto the session for support. Fulfillment ignores it:
-  bundles decompose into per-release order items, so downloads and order
-  history need no special handling.
+  bundles decompose into per-release / per-track order items, so downloads and
+  order history need no special handling.
 
 Bundles compose with loose `release` / `track` items in a single session. A
-release charged by both a bundle and a loose line yields one deduped order item
-whose price is the sum.
+release or track charged by both a bundle and a loose line yields one deduped
+order item whose price is the sum.
+
+A track has no cover of its own, so a track-only bundle's line item shows the
+cover of the release its first member belongs to.
 
 Two rejections worth handling in the cart UI:
 
 | Case | Response |
 | --- | --- |
-| Resolver returns `null`, or every member is unpublished | `409 { error: "bundle-unavailable", bundleIds }` |
+| Resolver returns `null`, or every member (of either kind) is unpublished | `409 { error: "bundle-unavailable", bundleIds }` |
 | Cart mixes `kind: "catalog"` with `kind: "bundle"` | `400` |
 
 The 409 is the expected path when an admin deletes or unpublishes a bundle still

package/dist/index.d.ts

@@ -73,9 +73,10 @@ 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
@@ -84,7 +85,14 @@ interface CheckoutDeps {
      */
     bundlePurchase?: (bundleId: string) => 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.
+ */
 interface ResolvedBundle {
     /** Final charged price for the whole bundle, in cents. Clamped up to the Stripe card minimum. */
     totalCents: number;
@@ -92,10 +100,16 @@ 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[];
+    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.
+     */
+    trackIds?: number[];
 }
 /** What `fulfillCheckoutSession` needs to turn a paid Stripe session into an order row. */
 interface FulfillSessionDeps {
@@ -144,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
@@ -270,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>;
 
@@ -284,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
@@ -318,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>;
 
@@ -339,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

@@ -24,13 +24,13 @@ function apportion(totalCents, members) {
   const exact = weights.map((w) => total * w);
   const base = exact.map((v) => Math.floor(v));
   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);
+  const order = members.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;
     base[i] += 1;
     remainder -= 1;
   }
-  members.forEach((m, i) => result.set(m.id, base[i]));
+  members.forEach((m, i) => result.set(m.key, base[i]));
   return result;
 }
 function createCheckoutHandler(deps) {
@@ -161,12 +161,16 @@ function createCheckoutHandler(deps) {
         };
       });
       const bundleLineItems = [];
-      const bundleMemberIds = [];
+      const bundleReleaseMemberIds = [];
+      const bundleTrackMemberIds = [];
       const unavailableBundleIds = [];
       for (const bundleId of bundleIds) {
         const resolved = await bundlePurchase(bundleId);
-        const members = (resolved?.releaseIds ?? []).map((id) => releaseById.get(id)).filter((r) => r !== void 0);
-        if (!resolved || members.length === 0) {
+        const releaseMembers = (resolved?.releaseIds ?? []).map((id) => releaseById.get(id)).filter((r) => r !== void 0);
+        const trackMembers = (resolved?.trackIds ?? []).map((id) => trackContext.get(id)).filter(
+          (c) => c !== void 0
+        );
+        if (!resolved || releaseMembers.length + trackMembers.length === 0) {
           unavailableBundleIds.push(bundleId);
           continue;
         }
@@ -174,7 +178,7 @@ function createCheckoutHandler(deps) {
           STRIPE_MIN_CHARGE_CENTS,
           Math.round(resolved.totalCents)
         );
-        const cover = members.find((m) => m.coverImageUrl)?.coverImageUrl;
+        const cover = releaseMembers.find((m) => m.coverImageUrl)?.coverImageUrl ?? trackMembers.find((c) => c.release.coverImageUrl)?.release.coverImageUrl;
         bundleLineItems.push({
           price_data: {
             currency,
@@ -186,13 +190,14 @@ function createCheckoutHandler(deps) {
           },
           quantity: 1
         });
-        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);
+        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) {
         return Response.json(
@@ -207,10 +212,15 @@ function createCheckoutHandler(deps) {
       const resolvedReleaseIds = [
         .../* @__PURE__ */ new Set([
           ...releaseLineItems.length ? releaseIds.filter((id) => releaseById.has(id)) : [],
-          ...bundleMemberIds
+          ...bundleReleaseMemberIds
+        ])
+      ];
+      const resolvedTrackIds = [
+        .../* @__PURE__ */ 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",
         line_items: lineItems,
@@ -423,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 });
     }
@@ -442,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 });
     }
@@ -457,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;
@@ -519,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);
   };
@@ -555,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) {
@@ -586,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 {
@@ -618,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
@@ -640,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 }
       });
     }
   }
@@ -678,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);
 }
@@ -692,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) => {
@@ -741,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;
@@ -773,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}.
@@ -791,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.
@@ -799,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);