@gigamusic/checkout 4.8.0 → 4.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gigamusic/checkout",
-  "version": "4.8.0",
+  "version": "4.9.0",
   "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": {
@@ -31,7 +31,7 @@
     "archiver": "^7.0.1",
     "stripe": "^22.0.0",
     "@gigamusic/core": "4.2.0",
-    "@gigamusic/db": "4.8.0",
+    "@gigamusic/db": "4.9.0",
     "@gigamusic/email": "4.2.0",
     "@gigamusic/storage": "3.0.0"
   },
@@ -51,7 +51,7 @@
     "dev": "tsup --watch",
     "lint": "eslint src",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.tests.json",
     "clean": "rm -rf dist .turbo *.tsbuildinfo"
   }
 }

package/src/checkout.ts

@@ -12,6 +12,21 @@ import type { CheckoutCartItem, CheckoutDeps } from "./types.js";
  */
 const STRIPE_MIN_CHARGE_CENTS = 50;
 
+/**
+ * Stripe turns Managed Payments — its merchant-of-record product — on by
+ * default for newly created accounts. Left alone it rejects every line item
+ * built here, because Managed Payments requires a `product_data.tax_code` we
+ * don't set. Supplying one isn't the fix: the session then quietly comes back
+ * with `managed_payments.enabled: true`, which sells through Link as merchant
+ * of record, adds a per-transaction fee, replaces our purchase emails with
+ * Link's, and lets Stripe refund customers on our behalf.
+ *
+ * Sites composing this package sell as their own merchant, so opt out per
+ * session rather than depending on an account-level default that differs
+ * between an artist's old and new Stripe accounts.
+ */
+const MANAGED_PAYMENTS_DISABLED = { enabled: false } as const;
+
 /**
  * Resolve the per-line `unit_amount`: a positive pay-what-you-want override
  * (clamped up to the Stripe minimum) when supplied, otherwise the catalog
@@ -170,6 +185,7 @@ export function createCheckoutHandler(
             release_ids: JSON.stringify(releases.map((r) => r.id)),
             track_ids: "[]",
           },
+          managed_payments: MANAGED_PAYMENTS_DISABLED,
           success_url: successUrl,
           cancel_url: cancelUrl,
         });
@@ -388,6 +404,7 @@ export function createCheckoutHandler(
           // items — but invaluable when supporting "what did I actually buy?".
           ...(bundleIds.length > 0 ? { bundle_ids: JSON.stringify(bundleIds) } : {}),
         },
+        managed_payments: MANAGED_PAYMENTS_DISABLED,
         success_url: successUrl,
         cancel_url: cancelUrl,
       });

package/src/types.ts

@@ -212,6 +212,33 @@ export interface DownloadDeps {
    * download that is otherwise still producing bytes.
    */
   onZipEntryFailure?: (failure: ZipEntryFailure) => void;
+  /**
+   * How long `createDownloadZipStreamHandler` lets the customer's connection
+   * go without accepting a byte before it treats the download as abandoned,
+   * tears the archive down and stops paying for R2 egress. Defaults to 30s.
+   *
+   * This exists because `req.signal` cannot be relied on to fire when a
+   * customer closes a bulk download on Vercel — abandoned streams were
+   * observed running the function's full `maxDuration` and stacking up on one
+   * instance until it ran out of memory. Raise it only if you serve customers
+   * slow enough to spend that long on a single 256 KB window; lower it to
+   * reclaim capacity faster.
+   */
+  zipStreamIdleTimeoutMs?: number;
+  /**
+   * Set `false` to make `createDownloadZipStreamHandler` stream without a
+   * `Content-Length`, as it did before the header was introduced.
+   *
+   * The header is what lets a browser notice that a zip arrived truncated
+   * instead of filing a corrupt archive as a finished download, so leaving it
+   * on is strongly preferred. The escape hatch is here for one scenario: the
+   * declared length is computed from `track_files.fileSize`, so a catalog
+   * whose recorded sizes have drifted from the objects in storage would fail
+   * every bulk download rather than silently shipping a mismatched body.
+   * Turning this off restores the old behaviour without a package downgrade
+   * while the rows are repaired. Defaults to `true`.
+   */
+  zipStreamContentLength?: boolean;
   /**
    * 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-length.ts

@@ -0,0 +1,128 @@
+/**
+ * Byte-exact size prediction for the archives `createDownloadZipStreamHandler`
+ * produces, so that route can send a real `Content-Length`.
+ *
+ * Why this matters: without `Content-Length` the response is chunked, and a
+ * function that dies mid-body (timeout, OOM) looks *complete* to the browser.
+ * The customer ends up with a file full of valid MP3 bytes and no
+ * End-of-Central-Directory record — macOS Archive Utility calls that
+ * "Error 79 – Inappropriate file type or format". Declaring the length up
+ * front turns that silent corruption into a download the browser itself flags
+ * as failed.
+ *
+ * The numbers below are not guesses about the zip spec in general; they are
+ * the exact byte counts `compress-commons@6`'s `ZipArchiveOutputStream` emits
+ * for the specific shape of archive this handler builds — every entry `store`d
+ * (no DEFLATE) and appended from a *stream*, which is what forces a data
+ * descriptor after each entry's payload. A buffer-sourced entry has a
+ * different layout (real sizes in the local header, no data descriptor), which
+ * is one reason the stream handler abandons its `Content-Length` the moment it
+ * has to substitute a `_FAILED_*.txt` placeholder.
+ */
+
+/** signature + version + flags + method + mtime + crc + csize + size + name len + extra len */
+const LOCAL_FILE_HEADER_BYTES = 30;
+/** LFH fields + version made by + comment len + disk + attrs + LFH offset */
+const CENTRAL_FILE_HEADER_BYTES = 46;
+/** signature + crc + csize + size, all 32-bit. */
+const DATA_DESCRIPTOR_BYTES = 16;
+/** Same, with 64-bit sizes — used once an entry itself crosses 4 GiB. */
+const ZIP64_DATA_DESCRIPTOR_BYTES = 24;
+/** header id + payload len + size + csize + LFH offset (three 64-bit fields). */
+const ZIP64_EXTRA_FIELD_BYTES = 28;
+/** signature + disks + counts + CD size + CD offset + comment len, comment empty. */
+const END_OF_CENTRAL_DIRECTORY_BYTES = 22;
+/** The zip64 EOCD record plus its locator, written as a pair or not at all. */
+const ZIP64_END_OF_CENTRAL_DIRECTORY_BYTES = 56 + 20;
+
+/** Largest value a 32-bit zip field can hold; anything above forces zip64 encoding. */
+const ZIP64_MAGIC = 0xffffffff;
+/** Largest entry count the classic 16-bit EOCD record can express. */
+const ZIP64_MAGIC_SHORT = 0xffff;
+
+/** One entry as it will be appended: the in-archive path and the payload's exact byte count. */
+export interface PredictedZipEntry {
+  name: string;
+  size: number;
+}
+
+/**
+ * Reject any entry name whose bytes archiver would rewrite.
+ *
+ * `archiver` runs every entry name through `sanitizePath` (collapse separator
+ * runs, `\` → `/`, drop a `scheme:` prefix, drop leading `/` and `../`) before
+ * writing it, and the name's byte length lands in three separate headers. If
+ * our prediction is computed from a name archiver then shortens, the declared
+ * `Content-Length` is wrong — which is worse than sending none at all. Rather
+ * than reimplementing that normalisation and hoping the two stay in step, we
+ * only predict for names that are already fixed points of it.
+ */
+export function isPredictableZipEntryName(name: string): boolean {
+  if (name.length === 0) return false;
+  if (name.includes("\\")) return false;
+  if (name.includes("//")) return false;
+  if (name.startsWith("/")) return false;
+  if (name.startsWith("../")) return false;
+  if (name.endsWith("/")) return false;
+  return !/^\w+:/.test(name);
+}
+
+/**
+ * Exact byte length of the stored, stream-appended zip built from `entries`,
+ * or `null` when the layout can't be pinned down — an unusable entry name, a
+ * non-integer size, or a total large enough to lose precision as a JS number.
+ * Callers must treat `null` as "omit the header and fall back to chunked".
+ *
+ * Both zip64 escalations are modelled, because either one silently changes the
+ * byte count: an individual entry past 4 GiB widens its data descriptor and
+ * gains a central-directory extra field, and an archive whose central
+ * directory starts (or ends up) past 4 GiB — or that holds more than 65535
+ * entries — gains a zip64 EOCD record and locator ahead of the classic EOCD.
+ */
+export function predictStoredZipLength(entries: PredictedZipEntry[]): number | null {
+  if (entries.length === 0) return null;
+
+  let localBytes = 0;
+  let centralBytes = 0;
+
+  for (const entry of entries) {
+    if (!Number.isSafeInteger(entry.size) || entry.size < 0) return null;
+    if (!isPredictableZipEntryName(entry.name)) return null;
+
+    const nameBytes = Buffer.byteLength(entry.name, "utf8");
+    const entryIsZip64 = entry.size > ZIP64_MAGIC;
+    // The entry's own local-header offset, captured before this entry moves it.
+    const localHeaderOffset = localBytes;
+
+    localBytes +=
+      LOCAL_FILE_HEADER_BYTES +
+      nameBytes +
+      entry.size +
+      (entryIsZip64 ? ZIP64_DATA_DESCRIPTOR_BYTES : DATA_DESCRIPTOR_BYTES);
+
+    centralBytes +=
+      CENTRAL_FILE_HEADER_BYTES +
+      nameBytes +
+      (entryIsZip64 || localHeaderOffset > ZIP64_MAGIC ? ZIP64_EXTRA_FIELD_BYTES : 0);
+  }
+
+  const archiveIsZip64 =
+    entries.length > ZIP64_MAGIC_SHORT ||
+    localBytes > ZIP64_MAGIC ||
+    centralBytes > ZIP64_MAGIC;
+
+  const total =
+    localBytes +
+    centralBytes +
+    (archiveIsZip64 ? ZIP64_END_OF_CENTRAL_DIRECTORY_BYTES : 0) +
+    END_OF_CENTRAL_DIRECTORY_BYTES;
+
+  return Number.isSafeInteger(total) ? total : null;
+}
+
+/**
+ * Byte cost of the zip64 EOCD record + locator pair, exported so the test
+ * suite can assert it against a real `forceZip64` archive — the one zip64
+ * branch that can be exercised without a multi-gigabyte fixture.
+ */
+export const ZIP64_TRAILER_BYTES = ZIP64_END_OF_CENTRAL_DIRECTORY_BYTES;