create-ailk 0.2.0 → 0.3.0

package/templates/apps/api/src/routes/webhooks/stripe.ts

@@ -1,481 +0,0 @@
-/**
- * POST /api/webhooks/stripe
- *
- * Receives Stripe webhook events. Verifies the signature on the raw
- * request body using the secret from STRIPE_WEBHOOK_SECRET. Dispatches
- * verified events through a `switch (event.type)` statement.
- *
- * Error mapping (in priority order):
- *   1. STRIPE_WEBHOOK_SECRET missing      → 503 webhook-not-configured
- *   2. Body is not a Buffer (parser miss) → 400 invalid-request
- *   3. Stripe-Signature header missing    → 400 signature-missing
- *   4. Signature verification fails       → 400 signature-invalid
- *
- * Successful dispatch always 200s — including unknown event types.
- * Telemetry failures are caught, logged, and do NOT change the response.
- *
- * Billing upsert (customer.created / checkout.session.completed):
- *   Billing-entity routing (org-scoped billing, #3601, spec D2): a checkout
- *   carrying metadata.organizationId links the Organization (multi-tenant
- *   module); absent → the existing User path (single-tenant), byte-for-byte.
- *
- *   Organization path (metadata.organizationId present):
- *     1. Typed composite match already pointing at this org → idempotent no-op
- *     2. Else link the target Organization (by id) billing fields
- *
- *   User path (no organizationId — unchanged):
- *     1. Typed composite match: (billingProvider="stripe", billingCustomerId=customer)
- *     2. Email fallback: User.findUnique({ where: { email } }) → update billing fields
- *     3. No match → 200 + warn log; no User row created (pre-signup state)
- *
- * Recommender purchase stamp (checkout.session.completed / .expired, #4838):
- *   A session carrying metadata.flowCheckoutId (the FlowCheckout buyer row
- *   #4841 opened it with) is stamped `completed` / `expired` by ONE guarded
- *   `updateMany` on `{ id, status: "created" }` — the durable idempotency key
- *   (D1): a replay, a restart between deliveries, or a late `expired` after a
- *   `completed` all match zero rows and log `stale_or_unknown`. Runs BESIDE the
- *   telemetry + billing tasks (D4), never instead of them; a charged/quoted
- *   mismatch is logged, never reconciled by overwrite (D2). Always 200. A
- *   `completed` session stamps only when `payment_status` is `"paid"` or
- *   `"no_payment_required"` (a 100%-off promo code, #4862) — anything else
- *   logs `outcome: "unpaid"` and leaves the row `created`.
- */
-import { track } from "@working-theory/analytics/server";
-import type { FastifyReply, FastifyRequest } from "fastify";
-
-import { config } from "../../config/index.js";
-import { prisma } from "../../lib/prisma.js";
-import {
-  StripeWebhookSignatureError,
-  verifyWebhookSignature,
-} from "../../lib/stripe.js";
-import { hasSeen, markSeen } from "../../lib/webhook-idempotency.js";
-
-const TELEMETRY_TIMEOUT_MS = 2000;
-
-export const stripeWebhookHandler = async (
-  request: FastifyRequest,
-  reply: FastifyReply,
-): Promise<void> => {
-  const secret = config.STRIPE_WEBHOOK_SECRET;
-  if (!secret) {
-    request.log.warn("stripe webhook hit but STRIPE_WEBHOOK_SECRET is not set");
-    await reply.code(503).send({ error: "webhook-not-configured" });
-    return;
-  }
-
-  const rawBody = request.body;
-  if (!Buffer.isBuffer(rawBody)) {
-    request.log.error(
-      "stripe webhook body is not a Buffer — content-type parser misconfigured",
-    );
-    await reply.code(400).send({ error: "invalid-request" });
-    return;
-  }
-
-  const signature = request.headers["stripe-signature"];
-  if (typeof signature !== "string" || signature.length === 0) {
-    await reply.code(400).send({ error: "signature-missing" });
-    return;
-  }
-
-  let event;
-  try {
-    event = verifyWebhookSignature(rawBody, signature, secret);
-  } catch (err) {
-    if (err instanceof StripeWebhookSignatureError) {
-      request.log.warn(
-        { reason: err.message },
-        "stripe webhook signature verification failed",
-      );
-      await reply.code(400).send({ error: "signature-invalid" });
-      return;
-    }
-    throw err;
-  }
-
-  const eventIdPrefix = event.id.substring(0, 8);
-  request.log.info(
-    { eventType: event.type, eventIdPrefix },
-    "stripe webhook event received",
-  );
-
-  // AILK-layer idempotency. Stripe guarantees at-least-once delivery and
-  // dashboard "resend" replays a previously-delivered event verbatim. Skip
-  // side effects on the second arrival; still 200 so Stripe stops retrying.
-  if (hasSeen(event.id)) {
-    request.log.info(
-      { eventType: event.type, eventIdPrefix },
-      "duplicate stripe webhook event — idempotent short-circuit",
-    );
-    await reply.code(200).send({ received: true });
-    return;
-  }
-  markSeen(event.id);
-
-  switch (event.type) {
-    case "customer.created": {
-      const customer = event.data.object as {
-        id: string;
-        email?: string | null;
-        metadata?: Record<string, string> | null;
-      };
-      // Billing-entity routing (spec D2): a multi-tenant checkout stamps the
-      // target Organization id in metadata.organizationId (an individual → their
-      // sentinel default org). Present → link the Organization; absent → the
-      // existing User path, byte-for-byte (single-tenant, degrade-clean).
-      const organizationId = customer.metadata?.["organizationId"] ?? null;
-      if (organizationId) {
-        await upsertOrgBillingIdentity(request, {
-          organizationId,
-          customerId: customer.id,
-          eventIdPrefix,
-        });
-      } else {
-        await upsertBillingIdentity(request, {
-          customerId: customer.id,
-          email: customer.email ?? null,
-          eventIdPrefix,
-        });
-      }
-      break;
-    }
-    case "checkout.session.completed": {
-      const session = event.data.object as CheckoutSessionObject;
-      const props = {
-        amount: session.amount_total ?? undefined,
-        currency: session.currency ?? undefined,
-        productId:
-          session.metadata?.["productId"] ??
-          session.metadata?.["product_id"] ??
-          undefined,
-        eventType: event.type,
-        eventIdPrefix,
-      };
-
-      // Billing-entity routing (spec D2): metadata.organizationId → Organization
-      // path; absent → the existing User path, unchanged (single-tenant).
-      const organizationId = session.metadata?.["organizationId"] ?? null;
-      let billingTask: Promise<void> = Promise.resolve();
-      if (session.customer) {
-        billingTask = organizationId
-          ? upsertOrgBillingIdentity(request, {
-              organizationId,
-              customerId: session.customer,
-              eventIdPrefix,
-            })
-          : upsertBillingIdentity(request, {
-              customerId: session.customer,
-              email: session.customer_details?.email ?? null,
-              eventIdPrefix,
-            });
-      }
-
-      // Telemetry, billing upsert and the recommender stamp are independent —
-      // run in parallel (the stamp is a no-op without metadata.flowCheckoutId).
-      await Promise.all([
-        fireTelemetryWithTimeout(request, "purchase-completed", props),
-        billingTask,
-        stampFlowCheckout(request, { session, eventIdPrefix, outcome: "completed" }),
-      ]);
-      break;
-    }
-    case "checkout.session.expired": {
-      const session = event.data.object as CheckoutSessionObject;
-      if (!session.metadata?.["flowCheckoutId"]) {
-        // Not a recommender session — the same low-noise line the default
-        // arm emitted for this event before #4838 handled it.
-        request.log.info(
-          { eventType: event.type, eventIdPrefix },
-          "unhandled webhook event",
-        );
-        break;
-      }
-      await stampFlowCheckout(request, { session, eventIdPrefix, outcome: "expired" });
-      break;
-    }
-    default:
-      request.log.info(
-        { eventType: event.type, eventIdPrefix },
-        "unhandled webhook event",
-      );
-      break;
-  }
-
-  await reply.code(200).send({ received: true });
-};
-
-type CheckoutSessionObject = {
-  id?: string;
-  payment_status?: string | null;
-  amount_total?: number | null;
-  currency?: string | null;
-  customer?: string | null;
-  customer_details?: { email?: string | null } | null;
-  metadata?: Record<string, string> | null;
-};
-
-/**
- * Stamp the recommender's FlowCheckout buyer row from a terminal Checkout
- * Session event (#4838).
- *
- * The `status: "created"` guard on the update IS the idempotency key (D1):
- * `count === 1` → stamped; `count === 0` → the row is already terminal, or the
- * id is unknown — a warning, never a retry (Stripe would re-fire telemetry +
- * billing on eventual success). A `completed` session whose
- * `payment_status` is not `"paid"` logs `unpaid` and leaves the row `created`. A charged amount that differs from the quoted
- * `amountMinor` is logged with both integers and the stamp proceeds (D2). Log
- * lines carry only `eventIdPrefix`, an 8-char `flowCheckoutIdPrefix`, an
- * `outcome`, and the two integers — never the email, customer id, or permalink.
- *
- * Never throws — the handler's "always 200 for a verified event" contract.
- */
-async function stampFlowCheckout(
-  request: FastifyRequest,
-  {
-    session,
-    eventIdPrefix,
-    outcome,
-  }: { session: CheckoutSessionObject; eventIdPrefix: string; outcome: "completed" | "expired" },
-): Promise<void> {
-  const flowCheckoutId = session.metadata?.["flowCheckoutId"];
-  if (!flowCheckoutId) return;
-  const flowCheckoutIdPrefix = flowCheckoutId.substring(0, 8);
-
-  // A `completed` session is only a purchase once Stripe reports it paid, OR
-  // reports nothing was due (`no_payment_required` — a 100%-off promo code,
-  // #4862, still a Stripe-confirmed completion). A delayed-notification or
-  // genuinely unpaid completion leaves the row `created` (code + security
-  // review, PR #4855).
-  if (
-    outcome === "completed" &&
-    session.payment_status !== "paid" &&
-    session.payment_status !== "no_payment_required"
-  ) {
-    request.log.warn(
-      { eventIdPrefix, flowCheckoutIdPrefix, outcome: "unpaid" },
-      "flow checkout: completed session is not paid — not stamping",
-    );
-    return;
-  }
-
-  try {
-    if (outcome === "completed" && typeof session.amount_total === "number") {
-      const row = await prisma.flowCheckout.findUnique({
-        where: { id: flowCheckoutId },
-        select: { amountMinor: true },
-      });
-      if (row && row.amountMinor !== session.amount_total) {
-        request.log.warn(
-          {
-            eventIdPrefix,
-            flowCheckoutIdPrefix,
-            outcome: "amount_mismatch",
-            expected: row.amountMinor,
-            received: session.amount_total,
-          },
-          "flow checkout: charged amount differs from the quoted amount — stamping anyway",
-        );
-      }
-    }
-
-    const result = await prisma.flowCheckout.updateMany({
-      where: { id: flowCheckoutId, status: "created" },
-      data:
-        outcome === "completed"
-          ? {
-              status: "completed",
-              completedAt: new Date(),
-              stripeSessionId: session.id ?? null,
-              stripeCustomerId: session.customer ?? null,
-            }
-          : { status: "expired" },
-    });
-
-    if (result.count === 1) {
-      request.log.info(
-        { eventIdPrefix, flowCheckoutIdPrefix, outcome },
-        "flow checkout stamped",
-      );
-    } else {
-      request.log.warn(
-        { eventIdPrefix, flowCheckoutIdPrefix, outcome: "stale_or_unknown" },
-        "flow checkout: no created row matched — replay, late terminal event, or unknown id",
-      );
-    }
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        flowCheckoutIdPrefix,
-        outcome: "stamp_failed",
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "flow checkout stamp failed — continuing",
-    );
-  }
-}
-
-/**
- * Link User.billingProvider + User.billingCustomerId for a Stripe customer.
- *
- * Lookup priority:
- *   1. Typed composite match: (billingProvider="stripe", billingCustomerId=customerId)
- *      → already linked; no-op (idempotent)
- *   2. Email fallback: User.findUnique({ where: { email } }) → update billing fields
- *   3. No match → warn; do NOT create a User row (pre-signup state preserved for Phase B #852)
- *
- * DB failures are caught and logged — a broken DB link should not cause Stripe to retry
- * the event (which would fire analytics + billing again on eventual success).
- */
-async function upsertBillingIdentity(
-  request: FastifyRequest,
-  {
-    customerId,
-    email,
-    eventIdPrefix,
-  }: { customerId: string; email: string | null; eventIdPrefix: string },
-): Promise<void> {
-  try {
-    const existingByBilling = await prisma.user.findFirst({
-      where: {
-        billingProvider: "stripe",
-        billingCustomerId: customerId,
-      },
-    });
-
-    if (existingByBilling) {
-      request.log.info(
-        { eventIdPrefix },
-        "billing identity already linked — idempotent no-op",
-      );
-      return;
-    }
-
-    if (email) {
-      const existingByEmail = await prisma.user.findUnique({
-        where: { email },
-      });
-
-      if (existingByEmail) {
-        await prisma.user.update({
-          where: { id: existingByEmail.id },
-          data: {
-            billingProvider: "stripe",
-            billingCustomerId: customerId,
-          },
-        });
-        request.log.info(
-          { eventIdPrefix },
-          "billing identity linked via email fallback",
-        );
-        return;
-      }
-    }
-
-    request.log.warn(
-      { eventIdPrefix },
-      "stripe webhook: no User match for billing identity — pre-signup state preserved",
-    );
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        error: err instanceof Error ? err.message : String(err),
-      },
-      "billing identity upsert failed — continuing",
-    );
-  }
-}
-
-/**
- * Link Organization.billingProvider + billingCustomerId for a Stripe customer
- * (org-scoped billing, #3601, spec D2/D3). Called when a checkout carries
- * metadata.organizationId — for a real org, or an individual's sentinel default
- * Organization (orgs-of-one; AC2 — ONE billing path inside the module).
- *
- * Idempotent: a typed-composite match (billingProvider="stripe",
- * billingCustomerId=customerId) already pointing at THIS org is a no-op on
- * replay. Otherwise the target Organization (by id from checkout metadata) is
- * linked.
- *
- * DB failures are caught and logged (never re-thrown) — a broken link must not
- * make Stripe retry (which would re-fire analytics + billing on eventual
- * success), matching the User-path contract above.
- */
-async function upsertOrgBillingIdentity(
-  request: FastifyRequest,
-  {
-    organizationId,
-    customerId,
-    eventIdPrefix,
-  }: { organizationId: string; customerId: string; eventIdPrefix: string },
-): Promise<void> {
-  try {
-    const existingByBilling = await prisma.organization.findFirst({
-      where: {
-        billingProvider: "stripe",
-        billingCustomerId: customerId,
-      },
-    });
-
-    if (existingByBilling && existingByBilling.id === organizationId) {
-      request.log.info(
-        { eventIdPrefix },
-        "org billing identity already linked — idempotent no-op",
-      );
-      return;
-    }
-
-    await prisma.organization.update({
-      where: { id: organizationId },
-      data: {
-        billingProvider: "stripe",
-        billingCustomerId: customerId,
-      },
-    });
-    request.log.info(
-      { eventIdPrefix },
-      "org billing identity linked from checkout metadata.organizationId",
-    );
-  } catch (err) {
-    request.log.error(
-      {
-        eventIdPrefix,
-        error: err instanceof Error ? err.message : String(err),
-      },
-      "org billing identity upsert failed — continuing",
-    );
-  }
-}
-
-async function fireTelemetryWithTimeout(
-  request: FastifyRequest,
-  name: string,
-  props: Record<string, unknown>,
-): Promise<void> {
-  let timeoutId!: ReturnType<typeof setTimeout>;
-  const timeout = new Promise<void>((resolve) => {
-    timeoutId = setTimeout(() => {
-      request.log.warn(
-        { telemetryEvent: name },
-        "telemetry call exceeded timeout; continuing",
-      );
-      resolve();
-    }, TELEMETRY_TIMEOUT_MS);
-  });
-
-  try {
-    await Promise.race([track(name, props), timeout]);
-  } catch (err) {
-    request.log.error(
-      {
-        telemetryEvent: name,
-        error: err instanceof Error ? err.message : String(err),
-      },
-      "telemetry call threw",
-    );
-  } finally {
-    clearTimeout(timeoutId);
-  }
-}