@openlup/platform 0.26.0 → 0.27.0

package/src/commerce/server/commerceCheckoutHandlerAdmission.ts

@@ -0,0 +1,157 @@
+import type { z } from "zod";
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import type { CheckoutKind, ConfiguratorIntent } from "../contracts/index.js";
+
+export interface CheckoutRateLimitDecision {
+  allowed: boolean;
+  reason?: "ip_quota" | "email_quota";
+}
+
+export interface CheckoutAdmissionRequest {
+  method?: string;
+  body?: unknown;
+  headers: Record<string, string | string[] | undefined>;
+}
+
+type CheckoutAdmissionResponse = HttpResponse;
+
+export interface CheckoutAdmissionDeps<Intent> {
+  checkRateLimit: (
+    req: CheckoutAdmissionRequest,
+    intent: Intent,
+    paymentAttemptSequence: number | undefined,
+  ) => Promise<CheckoutRateLimitDecision>;
+  rateLimitMessage: (reason: "ip_quota" | "email_quota" | undefined) => string;
+  checkRiskBlocklist?: (
+    req: CheckoutAdmissionRequest,
+    intent: Intent,
+  ) => Promise<{ blocked: boolean }>;
+  subscriptionCheckoutContractEnabled?: () => boolean;
+  deliveryRequired?: () => boolean;
+  promotionAcceptanceEnforced?: boolean;
+  offerPolicy?: unknown;
+}
+
+
+
+export function createCheckoutAdmission<Intent extends ConfiguratorIntent, Data extends { intent: Intent; expectedQuote?: unknown; paymentAttemptSequence?: number }>(bindings: {
+  requestSchema: z.ZodType<Data>; responder: BffResponder;
+  minimumOrderUnits?: number;
+  deliveryAllowed(intent: Intent): boolean; respondDeliveryRequired(res: HttpResponse): void;
+  rejectMissingPromotionExpectedQuote(input: { res: HttpResponse; enforced: boolean; intent: Intent; expectedQuote?: unknown }): boolean;
+}) {
+  const { sendBffError, sendMethodNotAllowed } = bindings.responder;
+async function admitCheckoutRequest(input: {
+  req: CheckoutAdmissionRequest;
+  res: CheckoutAdmissionResponse;
+  deps: CheckoutAdmissionDeps<Intent>;
+  record: <T>(
+    stage: "rate_limit" | "risk_blocklist",
+    operation: () => Promise<T>,
+  ) => Promise<T>;
+}): Promise<{ kind: "accepted"; data: Data; intent: Intent; checkoutKind: CheckoutKind } | { kind: "responded"; outcome: "error" | "rejected" }> {
+  const { req, res, deps } = input;
+  if (req.method !== "POST") {
+    sendMethodNotAllowed(res, ["POST"]);
+    return { kind: "responded", outcome: "rejected" };
+  }
+
+  const parsed = bindings.requestSchema.safeParse(req.body);
+  if (!parsed.success) {
+    sendBffError(res, "BAD_REQUEST", "Invalid checkout request", {
+      details: parsed.error.flatten(),
+    });
+    return { kind: "responded", outcome: "rejected" };
+  }
+
+  const intent = parsed.data.intent;
+  // An untrusted minimum cannot waive the host floor without an offer resolver.
+  if (bindings.minimumOrderUnits !== undefined && !deps.offerPolicy) {
+    const selectedUnits = intent.selectedVariants.reduce((total, variant) => total + variant.qty, 0);
+    const reason = selectedUnits < bindings.minimumOrderUnits
+      ? `selected variants require at least ${bindings.minimumOrderUnits} total units`
+      : intent.minimumUnits !== undefined || intent.offerVersion !== undefined
+        ? "offer_version_unsupported" : null;
+    if (reason) {
+      sendBffError(res, "BAD_REQUEST", "Invalid checkout request", {
+        details: { formErrors: [], fieldErrors: { intent: [reason] } },
+      });
+      return { kind: "responded", outcome: "rejected" };
+    }
+  }
+  const checkoutKind = checkoutKindForIntent(intent);
+  if (bindings.rejectMissingPromotionExpectedQuote({
+    res,
+    enforced: deps.promotionAcceptanceEnforced ?? false,
+    intent,
+    expectedQuote: parsed.data.expectedQuote,
+  })) {
+    return { kind: "responded", outcome: "rejected" };
+  }
+
+  if ((deps.deliveryRequired?.() ?? false) && !bindings.deliveryAllowed(intent)) {
+    bindings.respondDeliveryRequired(res);
+    return { kind: "responded", outcome: "rejected" };
+  }
+
+  if (
+    checkoutKind === "subscription_initial" &&
+    !(deps.subscriptionCheckoutContractEnabled?.() ?? false)
+  ) {
+    sendBffError(res, "BAD_REQUEST", "Subscription checkout contract is disabled", {
+      details: {
+        feature: "checkout",
+        featureFlag: "COMMERCE_V2_W11_SUBSCRIPTION_CHECKOUT_CONTRACT_ENABLED",
+        reason: "subscription_checkout_contract_disabled",
+      },
+    });
+    return { kind: "responded", outcome: "rejected" };
+  }
+
+  let decision: CheckoutRateLimitDecision;
+  try {
+    decision = await input.record("rate_limit", () =>
+      deps.checkRateLimit(req, intent, parsed.data.paymentAttemptSequence),
+    );
+  } catch {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout rate limit unavailable", {
+      details: { feature: "checkout", reason: "rate_limit_unavailable" },
+    });
+    return { kind: "responded", outcome: "error" };
+  }
+  if (!decision.allowed) {
+    sendBffError(res, "RATE_LIMITED", deps.rateLimitMessage(decision.reason), {
+      details: { feature: "checkout", reason: decision.reason ?? "ip_quota" },
+    });
+    return { kind: "responded", outcome: "rejected" };
+  }
+
+  if (deps.checkRiskBlocklist) {
+    try {
+      const risk = await input.record("risk_blocklist", () =>
+        deps.checkRiskBlocklist!(req, intent),
+      );
+      if (risk.blocked) {
+        sendBffError(res, "FORBIDDEN", "Checkout cannot be completed", {
+          details: { feature: "checkout", reason: "risk_blocked_checkout" },
+        });
+        return { kind: "responded", outcome: "rejected" };
+      }
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout risk check unavailable", {
+        details: { feature: "checkout", reason: "risk_check_unavailable" },
+      });
+      return { kind: "responded", outcome: "error" };
+    }
+  }
+
+  return { kind: "accepted", data: parsed.data, intent, checkoutKind };
+}
+
+function checkoutKindForIntent(intent: Intent): CheckoutKind {
+  return intent.mode === "subscription" ? "subscription_initial" : "one_time";
+}
+
+return { admitCheckoutRequest };
+}

package/src/commerce/server/commerceCheckoutHandlerHelpers.ts

@@ -0,0 +1,223 @@
+import type { z } from "zod";
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import { projectPublicQuoteSnapshot } from "../../pricing/index.js";
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import type { CheckoutKind, ConfiguratorIntentPersistencePort, ConfiguratorIntent as NeutralIntent } from "../contracts/index.js";
+import { ConfiguratorIntentPersistenceConflictError } from "./configuratorIntentPersistenceHandler.js";
+import type { OrchestratedCheckoutResult } from "./commercePaidOrderOrchestration.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+import type { CheckoutExecutionProvider } from "./checkoutRuntimeTypes.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+import { subscriptionResponse, type CheckoutResumeGuardDeps } from "./commerceCheckoutResumeGuard.js";
+import type { ResolveSavedMethodResult } from "./commerceCheckoutSavedPaymentMethod.js";
+const ACCOUNT_LINK_TIMEOUT_MS = 1500;
+export async function runBestEffortAccountLink(
+  linkCustomerAccount: (email: string) => Promise<void>,
+  email: string,
+  context?: { trigger: string },
+): Promise<void> {
+  let timeout: ReturnType<typeof setTimeout> | null = null;
+  try {
+    const outcome = await Promise.race([
+      linkCustomerAccount(email).then(() => "completed" as const),
+      new Promise<"timed_out">((resolve) => {
+        timeout = setTimeout(() => resolve("timed_out"), ACCOUNT_LINK_TIMEOUT_MS);
+      }),
+    ]);
+    if (outcome === "timed_out") {
+      console.warn("checkout_account_link_timed_out", JSON.stringify({ ...context }));
+    }
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+export function createCheckoutHandlerHelpers<Intent extends NeutralIntent, Provisioned extends { clientId: string }, Snapshot extends CheckoutQuoteSnapshot, Response>(bindings: {
+  checkoutClientAction(input: { provider: string; status: "paid" | "processing" | "failed"; providerClientSecret: string | null; providerRedirectUrl: string | null }): unknown;
+  responder: BffResponder; responseSchema: z.ZodType<Response>;
+  statusUrl(orderId: string, paymentIntentId: string, clientId: string): string;
+  resolveResumeOpenOrderResponse(input: { deps: CheckoutResumeGuardDeps; clientId: string; checkoutKind: CheckoutKind; intent: Intent; now: () => Date }): Promise<Response | null>;
+}) {
+  const { sendBffError, sendBffSuccess } = bindings.responder;
+
+
+async function persistCheckoutIdentityOrRespond(input: {
+  res: HttpResponse;
+  persistencePort: ConfiguratorIntentPersistencePort<Intent, Provisioned>;
+  resumeGuardDeps: CheckoutResumeGuardDeps;
+  intent: Intent;
+  checkoutKind: CheckoutKind;
+  now: () => Date;
+  previewDiagnosticsEnabled: boolean;
+  recordPersistStage: <T>(operation: () => Promise<T>) => Promise<T>;
+}): Promise<
+  | { kind: "provisioned"; provisioned: Provisioned }
+  | { kind: "responded"; outcome: "error" | "rejected" }
+> {
+  const { res, persistencePort, resumeGuardDeps, intent, checkoutKind, now } = input;
+  try {
+    return {
+      kind: "provisioned",
+      provisioned: await input.recordPersistStage(() => persistencePort.persistIntent(intent)),
+    };
+  } catch (error) {
+    if (error instanceof ConfiguratorIntentPersistenceConflictError) {
+      await respondToProvisionIdentityConflict({
+        res,
+        persistencePort,
+        resumeGuardDeps,
+        intent,
+        checkoutKind,
+        now,
+      });
+      return { kind: "responded", outcome: "rejected" };
+    }
+    const provisioningCause = safeCommerceDiagnosticValue(
+      error instanceof Error ? error.message : String(error),
+    );
+    console.error(
+      "checkout_identity_provisioning_failed",
+      JSON.stringify({ message: provisioningCause }),
+    );
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Checkout identity provisioning failed", {
+      details: {
+        feature: "checkout",
+        stage: "provision_identity",
+        ...(input.previewDiagnosticsEnabled && provisioningCause
+          ? { diagnostic: provisioningCause }
+          : {}),
+      },
+    });
+    return { kind: "responded", outcome: "error" };
+  }
+}
+
+function respondToSavedPaymentMethodRejection(
+  res: HttpResponse,
+  reason: Extract<ResolveSavedMethodResult, { kind: "rejected" }>["reason"],
+): void {
+  if (reason === "saved_payment_method_resolver_unavailable") {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Saved payment method resolver is unavailable", {
+      details: { feature: "checkout", reason },
+    });
+    return;
+  }
+  if (reason === "saved_payment_method_session_required") {
+    sendBffError(res, "UNAUTHORIZED", "Customer session required", {
+      details: { feature: "checkout", reason },
+    });
+    return;
+  }
+  if (reason === "saved_payment_method_read_failed") {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Saved payment method read failed", {
+      details: { feature: "checkout", reason },
+    });
+    return;
+  }
+  sendBffError(res, "BAD_REQUEST", "Saved payment method is unavailable", {
+    details: { feature: "checkout", reason },
+  });
+}
+
+function buildCheckoutSuccessResponse(input: {
+  orchestrated: OrchestratedCheckoutResult<Snapshot>;
+  paymentProvider: CheckoutExecutionProvider;
+  checkoutKind: CheckoutKind;
+  intent: Intent;
+  clientId: string;
+}): Response {
+  const { orchestrated, paymentProvider, checkoutKind, intent, clientId } = input;
+  const { orderId, paymentIntentId, providerClientSecret, providerPaymentId, providerRedirectUrl, status } =
+    orchestrated;
+
+  const clientAction = bindings.checkoutClientAction({
+    provider: paymentProvider,
+    status,
+    providerClientSecret,
+    providerRedirectUrl,
+  });
+  const statusUrl =
+    status === "processing"
+      ? bindings.statusUrl(orderId, paymentIntentId, clientId)
+      : undefined;
+
+  return bindings.responseSchema.parse({
+    contractVersion: CHECKOUT_CONTRACT_VERSION,
+    checkoutKind,
+    orderRef: `order_${orderId}`,
+    orderId,
+    status,
+    paymentIntentId,
+    ...(providerPaymentId ? { providerPaymentId } : {}),
+    clientId,
+    clientAction,
+    ...(statusUrl ? { statusUrl } : {}),
+    subscription: subscriptionResponse(intent, checkoutKind),
+    payment: { requiresReusablePaymentMethod: checkoutKind === "subscription_initial" },
+    authoritativeQuote: projectPublicQuoteSnapshot(orchestrated.quoteSnapshot),
+  });
+}
+
+async function respondToProvisionIdentityConflict(input: {
+  res: HttpResponse;
+  persistencePort: ConfiguratorIntentPersistencePort<Intent, Provisioned>;
+  resumeGuardDeps: CheckoutResumeGuardDeps;
+  intent: Intent;
+  checkoutKind: CheckoutKind;
+  now: () => Date;
+}): Promise<void> {
+  const { res, persistencePort, resumeGuardDeps, intent, checkoutKind, now } = input;
+  const existing = await resolveCompletedIdentity(persistencePort, intent.idempotencyKey);
+  if (existing) {
+    // No `acceptedQuote`: this path runs before any quote, and deliberately so.
+    // (persist-intent updates the identity in place), so what survives to this
+    // point is a double-submit race — same payload, twice — where resuming IS
+    // the duplicate-charge guard. See the parameter's docblock.
+    const resumeResponse = await bindings.resolveResumeOpenOrderResponse({
+      deps: resumeGuardDeps,
+      clientId: existing.clientId,
+      checkoutKind,
+      intent,
+      now,
+    });
+    if (resumeResponse) {
+      sendBffSuccess(res, resumeResponse, { contractVersion: CHECKOUT_CONTRACT_VERSION });
+      return;
+    }
+  }
+  console.warn(
+    "checkout_identity_provisioning_conflict",
+    JSON.stringify({ stage: "provision_identity", resumed: false }),
+  );
+  sendBffError(res, "CONFLICT", "Checkout already submitted", {
+    details: {
+      feature: "checkout",
+      stage: "provision_identity",
+      reason: "checkout_already_submitted",
+    },
+  });
+}
+
+async function resolveCompletedIdentity(
+  port: ConfiguratorIntentPersistencePort<Intent, Provisioned>,
+  idempotencyKey: string,
+): Promise<Provisioned | null> {
+  if (!port.findCompletedIdentity) return null;
+  try {
+    return await port.findCompletedIdentity(idempotencyKey);
+  } catch (error) {
+    console.warn(
+      "checkout_identity_conflict_lookup_failed",
+      JSON.stringify({
+        message: safeCommerceDiagnosticValue(
+          error instanceof Error ? error.message : String(error),
+        ),
+      }),
+    );
+    return null;
+  }
+}
+
+return { persistCheckoutIdentityOrRespond, respondToSavedPaymentMethodRejection, buildCheckoutSuccessResponse, respondToProvisionIdentityConflict };
+}

package/src/commerce/server/commerceCheckoutOrchestrationError.ts

@@ -0,0 +1,15 @@
+/**
+ * Carries the order id only after inventory may need compensation. A nullable
+ * reason lets the handler distinguish safe conflicts from generic failures.
+ */
+export class CheckoutOrchestrationError extends Error {
+  readonly orderIdForCompensation: string | null;
+  readonly reason: string | null;
+
+  constructor(message: string, orderIdForCompensation: string | null, reason: string | null = null) {
+    super(message);
+    this.name = "CheckoutOrchestrationError";
+    this.orderIdForCompensation = orderIdForCompensation;
+    this.reason = reason;
+  }
+}

package/src/commerce/server/commerceCheckoutPromotionPriceChange.ts

@@ -0,0 +1,83 @@
+import type { HttpResponse } from "../../http/index.js";
+import type { BffResponder } from "../../bff/index.js";
+import { CHECKOUT_CONTRACT_VERSION } from "../checkoutSchemas.js";
+import type { CheckoutKind, ConfiguratorIntent as NeutralIntent } from "../contracts/index.js";
+import type { CommerceQuotePort } from "../ports.js";
+import type { PricingPolicySnapshot } from "../../pricing/index.js";
+import type { CheckoutQuoteSnapshot } from "./checkoutQuoteTypes.js";
+import { safeCommerceDiagnosticValue } from "./commerceDiagnostics.js";
+export function createPromotionPriceChange<Intent extends NeutralIntent, Provisioned extends { clientId: string }, Request, Snapshot extends CheckoutQuoteSnapshot, Response>(bindings: {
+  responder: BffResponder;
+  buildQuoteRequest(intent: Intent, provisioned: Provisioned, policy?: PricingPolicySnapshot): Request;
+  buildCheckoutPriceChangedResponse(input: { checkoutKind: CheckoutKind; expectedQuote: { totalGross: { amountMinor: number; currency: string } }; authoritativeQuote: Snapshot }): Response;
+  respondQuoteFailure(res: HttpResponse, error: unknown): boolean;
+}) {
+  const { sendBffError, sendBffSuccess } = bindings.responder;
+
+type PromotionPriceChangeInput = {
+  res: HttpResponse;
+  quotePort: CommerceQuotePort<Request, Snapshot, import("../../pricing/index.js").CreateQuoteOptions>;
+  intent: Intent;
+  provisioned: Provisioned;
+  checkoutKind: CheckoutKind;
+  expectedQuote?: {
+    totalGross: { amountMinor: number; currency: string };
+    pricingPolicy?: PricingPolicySnapshot;
+  };
+  resolvePricingPolicy?: (
+    request: Request,
+  ) => PricingPolicySnapshot | undefined | Promise<PricingPolicySnapshot | undefined>;
+  acceptedQuoteSnapshot: Snapshot | null;
+  recordQuote: <T>(operation: () => Promise<T>) => Promise<T>;
+}
+
+function rejectMissingPromotionExpectedQuote(input: {
+  res: HttpResponse;
+  enforced: boolean;
+  intent: Intent;
+  expectedQuote?: unknown;
+}): boolean {
+  if (!input.enforced || input.intent.promoCodes.length === 0 || input.expectedQuote) return false;
+  sendBffError(input.res, "BAD_REQUEST", "Promotion checkout requires an expected quote", {
+    details: { feature: "checkout", reason: "promotion_expected_quote_missing" },
+  });
+  return true;
+}
+
+async function respondToPromotionCodePriceChange(input: PromotionPriceChangeInput): Promise<boolean> {
+  let authoritativeQuote: Snapshot;
+  try {
+    const quoteRequest = bindings.buildQuoteRequest(
+      input.intent,
+      input.provisioned,
+      input.expectedQuote?.pricingPolicy,
+    );
+    const pricingPolicy = await input.resolvePricingPolicy?.(quoteRequest);
+    const offerVersion = input.acceptedQuoteSnapshot?.quote.context?.offerVersion;
+    authoritativeQuote = await input.recordQuote(() =>
+      input.quotePort.createQuote(quoteRequest, {
+        clientId: input.provisioned.clientId,
+        ...(pricingPolicy ? { pricingPolicy } : {}),
+        ...(offerVersion ? { offerVersion } : {}),
+      }),
+    );
+  } catch (error) {
+    if (bindings.respondQuoteFailure(input.res, error)) return true;
+    console.error("checkout_promotion_price_changed_requote_failed",
+      safeCommerceDiagnosticValue(error instanceof Error ? error.message : String(error)));
+    sendBffError(input.res, "UPSTREAM_UNAVAILABLE", "Checkout failed", {
+      details: { feature: "checkout", stage: "quote" },
+    });
+    return false;
+  }
+  const expectedQuote = input.expectedQuote ?? {
+    totalGross: input.acceptedQuoteSnapshot?.quote.totalGross ?? authoritativeQuote.quote.totalGross,
+  };
+  sendBffSuccess(input.res, bindings.buildCheckoutPriceChangedResponse({
+    checkoutKind: input.checkoutKind, expectedQuote, authoritativeQuote,
+  }), { contractVersion: CHECKOUT_CONTRACT_VERSION });
+  return true;
+}
+
+return { rejectMissingPromotionExpectedQuote, respondToPromotionCodePriceChange };
+}

package/src/commerce/server/commerceCheckoutProviderPayment.ts

@@ -0,0 +1,45 @@
+import type { HttpRequest } from "../../http/index.js";
+export interface CheckoutPaymentExecution { provider: string; flow?: string }
+export function createCheckoutClientAction<Embedded extends string>(embeddedProvider: Embedded, redirectProvider: string) {
+function checkoutClientAction(input: {
+  provider: string;
+  status: "paid" | "processing" | "failed";
+  providerClientSecret: string | null;
+  providerRedirectUrl: string | null;
+}) {
+  if (input.status !== "processing") return { kind: "none" as const };
+  if (input.provider === embeddedProvider) {
+    return {
+      kind: "provider_embedded" as const,
+      provider: embeddedProvider,
+      ...(input.providerClientSecret ? { clientSecret: input.providerClientSecret } : {}),
+    };
+  }
+  if (input.provider === redirectProvider && input.providerRedirectUrl) {
+    return { kind: "redirect" as const, url: input.providerRedirectUrl };
+  }
+  return { kind: "none" as const };
+}
+
+return checkoutClientAction;
+}
+
+export function providerPayerFromRequest(req: HttpRequest, intent: { contact: { email: string; firstName: string; lastName: string } }) {
+  return {
+    email: intent.contact.email,
+    name: `${intent.contact.firstName} ${intent.contact.lastName}`.trim(),
+    ip: firstHeader(req.headers["x-forwarded-for"])?.split(",")[0]?.trim() ??
+      firstHeader(req.headers["x-real-ip"]) ??
+      null,
+    userAgent: firstHeader(req.headers["user-agent"]) ?? null,
+  };
+}
+
+function firstHeader(value: string | string[] | undefined): string | null {
+  if (typeof value === "string" && value.trim()) return value.trim();
+  if (Array.isArray(value)) {
+    const first = value.find((entry) => entry.trim());
+    return first?.trim() ?? null;
+  }
+  return null;
+}