@gigamusic/checkout 4.4.0 → 4.5.0

package/README.md

@@ -13,3 +13,41 @@ export const POST = createCheckoutHandler({
   baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
 });
 ```
+
+## Fulfilling without waiting for the webhook
+
+Stripe redirects the customer to your success page and delivers the webhook in
+parallel — nothing orders those two. A success page that only *reads* the order
+will sometimes find nothing and leave a paying customer with no download links.
+
+`fulfillCheckoutSession` is the same idempotent write the webhook uses, exported
+so the success page can fulfill on the spot. Whichever path runs first writes the
+row (the unique constraint on `stripeSessionId` settles the race); the other gets
+`already-recorded` and skips the email, so exactly one confirmation goes out.
+
+```ts
+import { fulfillCheckoutSession, sendPurchaseConfirmation } from "@gigamusic/checkout";
+import { after } from "next/server";
+
+const session = await stripe.checkout.sessions.retrieve(sessionId);
+const result = await fulfillCheckoutSession(session, { queries, site });
+
+if (result.status === "created") {
+  after(() =>
+    sendPurchaseConfirmation(
+      {
+        orderId: result.order.id,
+        customerEmail: result.customerEmail,
+        itemNames: result.itemNames,
+        totalCents: result.totalCents,
+      },
+      emailDeps,
+    ),
+  );
+}
+```
+
+`status: "skipped"` carries a `reason` — `"site-mismatch"` (a session from
+another site sharing the Stripe account, or a forged `session_id`), `"no-items"`,
+or `"unpaid"` (a delayed-notification payment that hasn't cleared; wait for the
+webhook rather than handing over downloads).

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { NextRequest } from 'next/server';
 import Stripe from 'stripe';
-import { Queries } from '@gigamusic/db';
+import { Queries, OrderWithItems } from '@gigamusic/db';
 import { StorageProvider } from '@gigamusic/storage';
 import { EmailProvider, EmailBranding, PurchaseConfirmationArgs } from '@gigamusic/email';
 
@@ -58,23 +58,19 @@ interface CheckoutDeps {
         productName: string;
     } | null | undefined>);
 }
-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. */
+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. */
+interface PurchaseConfirmationDeps {
     email: EmailProvider;
     branding: EmailBranding;
     emailFrom: string;
@@ -99,6 +95,16 @@ interface WebhookDeps {
      */
     renderConfirmation?: (args: PurchaseConfirmationArgs) => RenderedEmail | Promise<RenderedEmail>;
 }
+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;
+}
 interface DownloadDeps {
     queries: Queries;
     storage: StorageProvider;
@@ -126,35 +132,92 @@ declare function createCheckoutHandler(deps: CheckoutDeps): (req: NextRequest) =
 
 /**
  * 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.
+ *
+ * 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.
+ */
+declare function createStripeWebhookHandler(deps: WebhookDeps): (req: NextRequest) => Promise<Response>;
+
+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.
  *
- * 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.
+ * Only `status: "created"` should trigger side effects (the confirmation
+ * email) — that status is returned to exactly one caller per session.
  *
  * ### Published-only resolution (gotcha)
  *
- * The handler resolves the release/track IDs from `session.metadata` against
+ * Release/track IDs from `session.metadata` are resolved 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.
+ * 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 this handler are:
- *  - an admin unpublishes between session-create and webhook-delivery
+ * 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 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.
+ * 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.
  */
-declare function createStripeWebhookHandler(deps: WebhookDeps): (req: NextRequest) => Promise<Response>;
+declare function fulfillCheckoutSession(session: Stripe.Checkout.Session, deps: FulfillSessionDeps): Promise<FulfillSessionResult>;
+/**
+ * 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.
+ */
+declare function sendPurchaseConfirmation(args: {
+    orderId: number;
+    customerEmail: string;
+    itemNames: string[];
+    totalCents: number;
+}, deps: PurchaseConfirmationDeps): Promise<void>;
 
 interface RouteContext$2 {
     params: Promise<{
@@ -237,4 +300,4 @@ declare function createDownloadZipStreamHandler(deps: DownloadDeps): (req: NextR
  */
 declare function createSwZipFallbackHandler(): () => Response;
 
-export { type CheckoutCartItem, type CheckoutDeps, type DownloadDeps, type WebhookDeps, createCheckoutHandler, createDownloadHandler, createDownloadZipHandler, createDownloadZipStreamHandler, createStripeWebhookHandler, createSwZipFallbackHandler };
+export { type CheckoutCartItem, type CheckoutDeps, type DownloadDeps, type FulfillSessionDeps, type FulfillSessionResult, type PurchaseConfirmationDeps, type WebhookDeps, createCheckoutHandler, createDownloadHandler, createDownloadZipHandler, createDownloadZipStreamHandler, createStripeWebhookHandler, createSwZipFallbackHandler, fulfillCheckoutSession, sendPurchaseConfirmation };

package/dist/index.js

@@ -170,13 +170,74 @@ function jsonError(message, status, cause) {
   }
   return Response.json({ error: message }, { status });
 }
-function createStripeWebhookHandler(deps) {
+async function fulfillCheckoutSession(session, deps) {
+  const { queries, site } = deps;
+  if (session.metadata?.site !== site) {
+    return { status: "skipped", reason: "site-mismatch" };
+  }
+  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);
+  const chargedAmounts = safeAmountMap(session.metadata?.amounts);
+  if (releaseIds.length === 0 && trackIds.length === 0) {
+    return { status: "skipped", reason: "no-items" };
+  }
+  const allReleases = await queries.listPublishedReleases();
+  const releaseById = new Map(allReleases.map((r) => [r.id, r]));
+  const trackContext = /* @__PURE__ */ new Map();
+  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 !== void 0);
+  const matchedTracks = trackIds.map((id) => trackContext.get(id)).filter(
+    (c) => c !== void 0
+  );
+  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;
+  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) {
+    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} \u2014 ${track.name}`)
+  ];
+  return { status: "created", order, itemNames, customerEmail, totalCents };
+}
+async function sendPurchaseConfirmation(args, deps) {
   const {
-    stripe: stripeOverride,
-    stripeSecret,
-    webhookSecret,
-    queries,
-    site,
     email,
     branding,
     emailFrom,
@@ -186,119 +247,33 @@ function createStripeWebhookHandler(deps) {
     verifyPath = "/orders/verify",
     renderConfirmation = renderPurchaseConfirmation
   } = deps;
-  if (!stripeOverride && !stripeSecret) {
-    throw new Error(
-      "createStripeWebhookHandler: must supply either `stripe` or `stripeSecret`"
+  if (!args.customerEmail) {
+    console.warn(
+      `[gigamusic/checkout] order ${args.orderId} has no customer email \u2014 recorded, but the customer cannot retrieve downloads.`
     );
+    return;
   }
-  const stripe = stripeOverride ?? new Stripe(stripeSecret, { typescript: true });
-  return async (req) => {
-    const body = await req.text();
-    const sig = req.headers.get("stripe-signature");
-    if (!sig) {
-      return Response.json({ error: "Missing signature" }, { status: 400 });
-    }
-    let event;
-    try {
-      event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
-    } catch {
-      return Response.json({ error: "Invalid signature" }, { status: 400 });
-    }
-    if (event.type !== "checkout.session.completed") {
-      return Response.json({ received: true });
-    }
-    const session = event.data.object;
-    if (session.metadata?.site !== site) {
-      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);
-    const chargedAmounts = safeAmountMap(session.metadata?.amounts);
-    if (releaseIds.length === 0 && trackIds.length === 0) {
-      return Response.json({ received: true });
-    }
-    const allReleases = await queries.listPublishedReleases();
-    const releaseById = new Map(allReleases.map((r) => [r.id, r]));
-    const trackContext = /* @__PURE__ */ new Map();
-    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 !== void 0);
-    const matchedTracks = trackIds.map((id) => trackContext.get(id)).filter(
-      (c) => c !== void 0
-    );
-    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) {
-      if (isUniqueConstraintError(err)) {
-        return Response.json({ received: true });
-      }
-      throw err;
-    }
-    if (!customerEmail) {
-      console.warn(
-        `[stripe-webhook] checkout.session.completed (session=${session.id}) has no customer_details.email \u2014 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} \u2014 ${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
-        );
-      }
+  try {
+    const verifyToken = await signOrderToken({
+      orderId: String(args.orderId),
+      email: args.customerEmail,
+      secret: orderTokenSecret,
+      expiresIn: orderTokenExpiry
     });
-    return Response.json({ received: true });
-  };
+    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
+    );
+  }
 }
 function safeAmountMap(value) {
   if (!value) return {};
@@ -326,6 +301,50 @@ function safeJsonIdList(value) {
   }
 }
 
+// src/webhook.ts
+function createStripeWebhookHandler(deps) {
+  const { stripe: stripeOverride, stripeSecret, webhookSecret, queries, site } = deps;
+  if (!stripeOverride && !stripeSecret) {
+    throw new Error(
+      "createStripeWebhookHandler: must supply either `stripe` or `stripeSecret`"
+    );
+  }
+  const stripe = stripeOverride ?? new Stripe(stripeSecret, { typescript: true });
+  return async (req) => {
+    const body = await req.text();
+    const sig = req.headers.get("stripe-signature");
+    if (!sig) {
+      return Response.json({ error: "Missing signature" }, { status: 400 });
+    }
+    let event;
+    try {
+      event = stripe.webhooks.constructEvent(body, sig, webhookSecret);
+    } catch {
+      return Response.json({ error: "Invalid signature" }, { status: 400 });
+    }
+    if (event.type !== "checkout.session.completed") {
+      return Response.json({ received: true });
+    }
+    const session = event.data.object;
+    const result = await fulfillCheckoutSession(session, { queries, site });
+    if (result.status !== "created") {
+      return Response.json({ received: true });
+    }
+    after(
+      () => sendPurchaseConfirmation(
+        {
+          orderId: result.order.id,
+          customerEmail: result.customerEmail,
+          itemNames: result.itemNames,
+          totalCents: result.totalCents
+        },
+        deps
+      )
+    );
+    return Response.json({ received: true });
+  };
+}
+
 // src/download.ts
 function createDownloadHandler(deps) {
   const { queries, storage } = deps;
@@ -757,6 +776,6 @@ function createSwZipFallbackHandler() {
   };
 }
 
-export { createCheckoutHandler, createDownloadHandler, createDownloadZipHandler, createDownloadZipStreamHandler, createStripeWebhookHandler, createSwZipFallbackHandler };
+export { createCheckoutHandler, createDownloadHandler, createDownloadZipHandler, createDownloadZipStreamHandler, createStripeWebhookHandler, createSwZipFallbackHandler, fulfillCheckoutSession, sendPurchaseConfirmation };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map