@gigamusic/checkout 4.4.0 → 4.6.0

package/README.md

@@ -13,3 +13,93 @@ export const POST = createCheckoutHandler({
   baseUrl: process.env.NEXT_PUBLIC_BASE_URL!,
 });
 ```
+
+## Bundles — discounted subsets of the catalog
+
+`catalogPurchase` is all-or-nothing. For a curated pack ("the remix EPs", "2024
+releases"), send `{ kind: "bundle", bundleId }` and supply a `bundlePurchase`
+resolver. It's called once per distinct `bundleId` in the cart.
+
+```ts
+export const POST = createCheckoutHandler({
+  stripeSecret: process.env.STRIPE_SECRET_KEY!,
+  queries,
+  site,
+  baseUrl,
+  bundlePurchase: async (bundleId) => {
+    const bundle = await getBundle(bundleId); // your storage, your pricing
+    if (!bundle) return null;                 // -> 409 bundle-unavailable
+    return {
+      totalCents: bundle.discountedPrice,
+      productName: `${bundle.name} (${bundle.releaseIds.length} releases)`,
+      releaseIds: bundle.releaseIds,
+    };
+  },
+});
+```
+
+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;
+- **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;
+- 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 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.
+
+Two rejections worth handling in the cart UI:
+
+| Case | Response |
+| --- | --- |
+| Resolver returns `null`, or every member 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
+sitting in a customer's saved cart — surface it as "this bundle is no longer
+available" with a one-click remove, rather than a generic failure.
+
+## 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';
 
@@ -9,10 +9,20 @@ interface RenderedEmail {
     subject: string;
     html: string;
 }
-/** Cart item shape accepted by `createCheckoutHandler`. `id` is required for "release" / "track"; ignored for "catalog". */
+/**
+ * Cart item shape accepted by `createCheckoutHandler`. `id` is required for
+ * "release" / "track" and ignored for "catalog"; "bundle" carries `bundleId`
+ * instead, since bundle identifiers belong to the consumer and needn't be
+ * numeric.
+ */
 interface CheckoutCartItem {
-    kind: "release" | "track" | "catalog";
+    kind: "release" | "track" | "catalog" | "bundle";
     id?: number;
+    /**
+     * Required for `kind: "bundle"`. Opaque to the package — handed straight to
+     * `bundlePurchase` for the consumer to resolve.
+     */
+    bundleId?: string;
     /**
      * Pay-what-you-want override, in cents. When present and ≥ the Stripe card
      * minimum, the customer is charged this instead of the catalog price — the
@@ -57,24 +67,49 @@ interface CheckoutDeps {
         totalCents: number;
         productName: string;
     } | null | undefined>);
+    /**
+     * Resolves a `kind: "bundle"` cart item — a discounted subset of the
+     * catalog, as opposed to `catalogPurchase`'s all-or-nothing line.
+     *
+     * 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.
+     *
+     * Resolving to `null`/`undefined` means "no such bundle" — the handler
+     * replies 409 `{ error: "bundle-unavailable", bundleIds }` so the cart can
+     * offer to drop it. That's the expected path when an admin deletes or
+     * unpublishes a bundle still sitting in someone's saved cart.
+     */
+    bundlePurchase?: (bundleId: string) => Promise<ResolvedBundle | null | undefined> | ResolvedBundle | null | undefined;
 }
-interface WebhookDeps {
+/** What `bundlePurchase` returns for a bundle the consumer recognises. */
+interface ResolvedBundle {
+    /** Final charged price for the whole bundle, in cents. Clamped up to the Stripe card minimum. */
+    totalCents: number;
+    /** Stripe line-item name, e.g. `"Summer Pack (3 releases, 20% off)"`. */
+    productName: string;
     /**
-     * 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.
+     * 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.
      */
-    stripe?: Stripe;
-    stripeSecret?: string;
-    webhookSecret: string;
+    releaseIds: number[];
+}
+/** 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 +134,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 +171,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.
  *
- * 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.
+ * 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.
+ *
+ * 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 +339,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 ResolvedBundle, type WebhookDeps, createCheckoutHandler, createDownloadHandler, createDownloadZipHandler, createDownloadZipStreamHandler, createStripeWebhookHandler, createSwZipFallbackHandler, fulfillCheckoutSession, sendPurchaseConfirmation };