@gigamusic/checkout 4.3.2 → 4.5.0

package/src/fulfill.ts

@@ -0,0 +1,266 @@
+import type Stripe from "stripe";
+import { signOrderToken } from "@gigamusic/core";
+import {
+  isUniqueConstraintError,
+  type OrderWithItems,
+  type ReleaseWithTracks,
+  type TrackWithFiles,
+} from "@gigamusic/db";
+import { renderPurchaseConfirmation } from "@gigamusic/email";
+import type { FulfillSessionDeps, PurchaseConfirmationDeps } from "./types.js";
+
+export type FulfillSessionResult =
+  /** This call wrote the order row. The caller owns sending the confirmation email. */
+  | {
+      status: "created";
+      order: OrderWithItems;
+      itemNames: string[];
+      customerEmail: string;
+      totalCents: number;
+    }
+  /**
+   * The order was already on disk — either the pre-flight lookup found it or a
+   * concurrent writer won the unique-constraint race. `order` is null only if
+   * the re-read after a lost race somehow came back empty.
+   */
+  | { status: "already-recorded"; order: OrderWithItems | null }
+  /** Nothing was written and nothing is owed. */
+  | { status: "skipped"; reason: "site-mismatch" | "no-items" | "unpaid" };
+
+/**
+ * Turn a completed Stripe Checkout Session into a persisted order, idempotently.
+ *
+ * This is the single fulfillment path shared by the Stripe webhook and any
+ * consumer that wants to fulfill synchronously — e.g. a post-checkout success
+ * page that would otherwise have to wait on webhook delivery to show download
+ * links. Whoever calls first writes the row; everyone after gets
+ * `already-recorded`. That guarantee rests on the unique constraint over
+ * `stripeSessionId` inside `recordCompletedOrder`, not on call ordering, so
+ * concurrent callers are safe.
+ *
+ * Only `status: "created"` should trigger side effects (the confirmation
+ * email) — that status is returned to exactly one caller per session.
+ *
+ * ### Published-only resolution (gotcha)
+ *
+ * Release/track IDs from `session.metadata` are resolved against
+ * `queries.listPublishedReleases()`. Anything not in the published catalog at
+ * fulfillment time 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 here are:
+ *  - an admin unpublishes between session-create and fulfillment
+ *    (a several-second race window),
+ *  - a consumer bypasses `createCheckoutHandler` and creates Stripe sessions
+ *    directly with their own metadata.
+ *
+ * If either 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 async function fulfillCheckoutSession(
+  session: Stripe.Checkout.Session,
+  deps: FulfillSessionDeps,
+): Promise<FulfillSessionResult> {
+  const { queries, site } = deps;
+
+  // One Stripe account fans every event out to every registered endpoint, and
+  // a success URL can be hand-forged. Ignore sessions belonging to a different
+  // site so we never record a foreign purchase (with zero matched line items)
+  // under this one.
+  if (session.metadata?.site !== site) {
+    return { status: "skipped", reason: "site-mismatch" };
+  }
+
+  // Delayed-notification methods (bank debits, vouchers) complete checkout with
+  // the money still in flight; the session only flips to `paid` later, via
+  // `checkout.session.async_payment_succeeded`. Handing over downloads at that
+  // point would be giving away unpaid goods. `no_payment_required` (fully
+  // discounted) and legacy sessions with no `payment_status` are fulfillable.
+  if (session.payment_status === "unpaid") {
+    return { status: "skipped", reason: "unpaid" };
+  }
+
+  const existing = await queries.getOrderByStripeSessionId(session.id);
+  if (existing) {
+    return { status: "already-recorded", order: existing };
+  }
+
+  const releaseIds = safeJsonIdList(session.metadata?.release_ids);
+  const trackIds = safeJsonIdList(session.metadata?.track_ids);
+  // Per-line amounts the customer actually paid, keyed `r<id>` / `t<id>`,
+  // stamped by `createCheckoutHandler`. Absent on pre-upgrade sessions and on
+  // catalog purchases — those fall back to the catalog price below.
+  const chargedAmounts = safeAmountMap(session.metadata?.amounts);
+
+  if (releaseIds.length === 0 && trackIds.length === 0) {
+    return { status: "skipped", reason: "no-items" };
+  }
+
+  // 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: chargedAmounts[`r${r.id}`] ?? r.price,
+    })),
+    ...matchedTracks.map(({ track }) => ({
+      trackId: track.id,
+      price: chargedAmounts[`t${track.id}`] ?? track.price,
+    })),
+  ];
+
+  const customerEmail = session.customer_details?.email ?? "";
+  const totalCents = session.amount_total ?? 0;
+
+  let order: OrderWithItems;
+  try {
+    order = await queries.recordCompletedOrder({
+      stripeSessionId: session.id,
+      stripePaymentId:
+        typeof session.payment_intent === "string" ? session.payment_intent : null,
+      email: customerEmail,
+      amountTotal: totalCents,
+      items: orderItems,
+    });
+  } catch (err) {
+    // Two callers can both pass the pre-flight lookup and race here — a webhook
+    // retry, or the success page rendering while the webhook is mid-flight. The
+    // unique constraint on `stripeSessionId` guarantees only one row lands; the
+    // loser surfaces as a 23505 unique-violation. Re-read so the loser still
+    // gets the order to render, but without claiming the "created" side effects.
+    if (isUniqueConstraintError(err)) {
+      return {
+        status: "already-recorded",
+        order: (await queries.getOrderByStripeSessionId(session.id)) ?? null,
+      };
+    }
+    throw err;
+  }
+
+  const itemNames = [
+    ...matchedReleases.map((r) => r.name),
+    ...matchedTracks.map(({ track, release }) => `${release.name} — ${track.name}`),
+  ];
+
+  return { status: "created", order, itemNames, customerEmail, totalCents };
+}
+
+/**
+ * Render and send the post-purchase confirmation email carrying the durable
+ * magic link back to the customer's downloads.
+ *
+ * Errors are logged, never thrown: the order is already recorded and paid for,
+ * so a mail-provider hiccup must not fail the caller (a webhook returning 500
+ * would make Stripe retry a fulfillment that already succeeded). Callers
+ * typically wrap this in `after()` so the response isn't blocked on it.
+ */
+export async function sendPurchaseConfirmation(
+  args: {
+    orderId: number;
+    customerEmail: string;
+    itemNames: string[];
+    totalCents: number;
+  },
+  deps: PurchaseConfirmationDeps,
+): Promise<void> {
+  const {
+    email,
+    branding,
+    emailFrom,
+    baseUrl,
+    orderTokenSecret,
+    orderTokenExpiry = null,
+    verifyPath = "/orders/verify",
+    renderConfirmation = renderPurchaseConfirmation,
+  } = deps;
+
+  if (!args.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(
+      `[gigamusic/checkout] order ${args.orderId} has no customer email — recorded, but the customer cannot retrieve downloads.`,
+    );
+    return;
+  }
+
+  try {
+    const verifyToken = await signOrderToken({
+      orderId: String(args.orderId),
+      email: args.customerEmail,
+      secret: orderTokenSecret,
+      expiresIn: orderTokenExpiry,
+    });
+    const verifyUrl = `${baseUrl}${verifyPath}?token=${verifyToken}`;
+    const { subject, html } = await renderConfirmation({
+      branding,
+      verifyUrl,
+      itemNames: args.itemNames,
+      totalCents: args.totalCents,
+    });
+    await email.send({ from: emailFrom, to: args.customerEmail, subject, html });
+  } catch (err) {
+    console.error(
+      `[gigamusic/checkout] failed to send purchase confirmation to ${args.customerEmail} for order ${args.orderId}:`,
+      err,
+    );
+  }
+}
+
+/**
+ * Parse the JSON-stringified `{ "r<id>" | "t<id>": cents }` amount map from
+ * Stripe metadata, returning `{}` on any failure. Non-finite values are
+ * dropped so a malformed entry falls back to the catalog price at the call site.
+ */
+function safeAmountMap(value: string | undefined | null): Record<string, number> {
+  if (!value) return {};
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (typeof parsed !== "object" || parsed === null) return {};
+    const out: Record<string, number> = {};
+    for (const [key, raw] of Object.entries(parsed as Record<string, unknown>)) {
+      const n = Number(raw);
+      if (Number.isFinite(n)) out[key] = n;
+    }
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/** 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/index.ts

@@ -1,13 +1,18 @@
 export { createCheckoutHandler } from "./checkout.js";
 export { createStripeWebhookHandler } from "./webhook.js";
+export { fulfillCheckoutSession, sendPurchaseConfirmation } from "./fulfill.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 { FulfillSessionResult } from "./fulfill.js";
+
 export type {
   CheckoutCartItem,
   CheckoutDeps,
   DownloadDeps,
+  FulfillSessionDeps,
+  PurchaseConfirmationDeps,
   WebhookDeps,
 } from "./types.js";

package/src/types.ts

@@ -60,23 +60,20 @@ export interface CheckoutDeps {
     | (() => Promise<{ totalCents: 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;
+/** What `fulfillCheckoutSession` needs to turn a paid Stripe session into an order row. */
+export interface FulfillSessionDeps {
   queries: Queries;
   /**
-   * The site (alias) this endpoint serves. Stripe broadcasts every event to
-   * every registered endpoint, so the handler ignores any
-   * `checkout.session.completed` whose `metadata.site` doesn't match — this is
+   * The site (alias) this fulfillment path serves. Stripe broadcasts every
+   * event to every registered endpoint (and a success URL can be hand-forged),
+   * so any session whose `metadata.site` doesn't match is skipped — this is
    * what lets one Stripe account safely back multiple sites.
    */
   site: string;
+}
+
+/** What `sendPurchaseConfirmation` needs to mail the customer their magic link. */
+export interface PurchaseConfirmationDeps {
   email: EmailProvider;
   branding: EmailBranding;
   emailFrom: string;
@@ -104,6 +101,17 @@ export interface WebhookDeps {
   ) => RenderedEmail | Promise<RenderedEmail>;
 }
 
+export interface WebhookDeps extends FulfillSessionDeps, PurchaseConfirmationDeps {
+  /**
+   * 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;
+}
+
 export interface DownloadDeps {
   queries: Queries;
   storage: StorageProvider;

package/src/webhook.ts

@@ -1,58 +1,25 @@
 import { after, type NextRequest } from "next/server";
 import Stripe from "stripe";
-import { signOrderToken } from "@gigamusic/core";
-import { isUniqueConstraintError, type ReleaseWithTracks, type TrackWithFiles } from "@gigamusic/db";
-import { renderPurchaseConfirmation } from "@gigamusic/email";
+import { fulfillCheckoutSession, sendPurchaseConfirmation } from "./fulfill.js";
 import type { WebhookDeps } from "./types.js";
 
 /**
  * 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.
+ * signature, records the order on `checkout.session.completed` via the shared
+ * `fulfillCheckoutSession`, 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 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.
+ * The handler is not the only fulfillment path — a consumer's success page can
+ * call `fulfillCheckoutSession` directly rather than waiting on webhook
+ * delivery. Whichever runs first writes the row; the other gets
+ * `already-recorded` and skips the email, so the customer is mailed exactly
+ * once no matter who wins. Every non-`created` outcome answers Stripe with
+ * `{ received: true }` so it doesn't retry.
  */
 export function createStripeWebhookHandler(
   deps: WebhookDeps,
 ): (req: NextRequest) => Promise<Response> {
-  const {
-    stripe: stripeOverride,
-    stripeSecret,
-    webhookSecret,
-    queries,
-    site,
-    email,
-    branding,
-    emailFrom,
-    baseUrl,
-    orderTokenSecret,
-    orderTokenExpiry = null,
-    verifyPath = "/orders/verify",
-    renderConfirmation = renderPurchaseConfirmation,
-  } = deps;
+  const { stripe: stripeOverride, stripeSecret, webhookSecret, queries, site } = deps;
 
   if (!stripeOverride && !stripeSecret) {
     throw new Error(
@@ -83,164 +50,23 @@ export function createStripeWebhookHandler(
 
     const session = event.data.object as Stripe.Checkout.Session;
 
-    // One Stripe account fans every event out to every registered endpoint.
-    // Ignore sessions that belong to a different site so we don't record a
-    // foreign purchase (with zero matched line items) under this site.
-    if (session.metadata?.site !== site) {
+    const result = await fulfillCheckoutSession(session, { queries, site });
+    if (result.status !== "created") {
       return Response.json({ received: true });
     }
 
-    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);
-    // Per-line amounts the customer actually paid, keyed `r<id>` / `t<id>`,
-    // stamped by `createCheckoutHandler`. Absent on pre-upgrade sessions and
-    // on catalog purchases — those fall back to the catalog price below.
-    const chargedAmounts = safeAmountMap(session.metadata?.amounts);
-
-    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: chargedAmounts[`r${r.id}`] ?? r.price,
-      })),
-      ...matchedTracks.map(({ track }) => ({
-        trackId: track.id,
-        price: chargedAmounts[`t${track.id}`] ?? 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 a 23505 unique-violation. 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,
-          expiresIn: orderTokenExpiry,
-        });
-        const verifyUrl = `${baseUrl}${verifyPath}?token=${verifyToken}`;
-        const { subject, html } = await renderConfirmation({
-          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,
-        );
-      }
-    });
+    after(() =>
+      sendPurchaseConfirmation(
+        {
+          orderId: result.order.id,
+          customerEmail: result.customerEmail,
+          itemNames: result.itemNames,
+          totalCents: result.totalCents,
+        },
+        deps,
+      ),
+    );
 
     return Response.json({ received: true });
   };
 }
-
-/**
- * Parse the JSON-stringified `{ "r<id>" | "t<id>": cents }` amount map from
- * Stripe metadata, returning `{}` on any failure. Non-finite values are
- * dropped so a malformed entry falls back to the catalog price at the call site.
- */
-function safeAmountMap(value: string | undefined | null): Record<string, number> {
-  if (!value) return {};
-  try {
-    const parsed: unknown = JSON.parse(value);
-    if (typeof parsed !== "object" || parsed === null) return {};
-    const out: Record<string, number> = {};
-    for (const [key, raw] of Object.entries(parsed as Record<string, unknown>)) {
-      const n = Number(raw);
-      if (Number.isFinite(n)) out[key] = n;
-    }
-    return out;
-  } catch {
-    return {};
-  }
-}
-
-/** 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 [];
-  }
-}