feat(paykit): harden subscription checkout sessions

.changeset/checkout-session-hardening.md

@@ -0,0 +1,5 @@
+---
+"paykitjs": minor
+---
+
+Add subscription Checkout hardening options, checkout session IDs in subscribe results, and a server-side method to expire Stripe Checkout Sessions with customer ownership checks.

.changeset/subscription-quantity.md

@@ -0,0 +1,5 @@
+---
+"paykitjs": minor
+---
+
+Add subscription quantity support to subscribe flows and Stripe provider sync.

packages/paykit/src/api/methods.ts

@@ -9,14 +9,15 @@ import {
   upsertCustomer,
 } from "../customer/customer.api";
 import { check, report } from "../entitlement/entitlement.api";
-import { subscribe } from "../subscription/subscription.api";
+import { expireCheckoutSession, subscribe } from "../subscription/subscription.api";
 import { advanceTestClock, getTestClock } from "../testing/testing.api";
 import type { PayKitOptions } from "../types/options";
 import { receiveWebhook } from "../webhook/webhook.api";
 import type { PayKitMethod } from "./define-route";
 
 export const baseMethods = {
   subscribe,
+  expireCheckoutSession,
   customerPortal,
   upsertCustomer,
   getCustomer,

packages/paykit/src/core/create-paykit.ts

@@ -20,15 +20,19 @@ export function isPayKitInstance(value: unknown): value is PayKitInstance {
 }
 
 const _global = globalThis as unknown as { __paykitDevChecksRan?: boolean };
-const dynamicImport = new Function("specifier", "return import(specifier)") as (
-  specifier: string,
-) => Promise<unknown>;
+
+function hiddenDynamicImport(specifier: string): Promise<unknown> {
+  const dynamicImport = new Function("specifier", "return import(specifier)") as (
+    specifier: string,
+  ) => Promise<unknown>;
+  return dynamicImport(specifier);
+}
 
 async function runDevChecks(ctx: PayKitContext): Promise<void> {
   if (_global.__paykitDevChecksRan) return;
   _global.__paykitDevChecksRan = true;
   if (process.env.PAYKIT_DISABLE_DEPENDENCY_CHECKER !== "1") {
-    const { checkPayKitDependencies } = (await dynamicImport(
+    const { checkPayKitDependencies } = (await hiddenDynamicImport(
       ["..", "utilities", "dependencies", "index.js"].join("/"),
     )) as {
       checkPayKitDependencies: () => Promise<void>;

packages/paykit/src/core/errors.ts

@@ -21,6 +21,10 @@ export const PAYKIT_ERROR_CODES = defineErrorCodes({
   PROVIDER_REQUIRED: "A provider is required",
   PROVIDER_INVALID_CONFIG: "Provider config is invalid",
   PROVIDER_CUSTOMER_NOT_FOUND: "Customer not found in provider",
+  PROVIDER_CHECKOUT_SESSION_CUSTOMER_MISMATCH:
+    "Provider checkout session does not belong to customer",
+  PROVIDER_CHECKOUT_SESSION_NOT_EXPIREABLE: "Provider checkout session cannot be expired",
+  PROVIDER_CHECKOUT_SESSION_NOT_FOUND: "Provider checkout session not found",
   PROVIDER_SESSION_INVALID: "Provider session did not include a URL",
   PROVIDER_SIGNATURE_MISSING: "Missing provider webhook signature",
   PROVIDER_SUBSCRIPTION_MISSING_ITEMS: "Provider subscription did not include any items",

packages/paykit/src/index.ts

@@ -12,14 +12,20 @@ export type {
   PayKitClientGetTestClockInput,
   PayKitClientSubscribeInput,
   PayKitGetTestClockInput,
+  PayKitExpireCheckoutSessionInput,
+  PayKitExpireCheckoutSessionResult,
   PayKitInstance,
   PayKitCheckInput,
   PayKitCustomerPortalInput,
   PayKitReportInput,
   PayKitSubscribeInput,
   PayKitSubscribeResult,
 } from "./types/instance";
-export type { SubscribeResult } from "./subscription/subscription.types";
+export type {
+  ExpireCheckoutSessionResult,
+  SubscribeResult,
+  SubscriptionCheckoutOptions,
+} from "./subscription/subscription.types";
 export type {
   CheckResult,
   EntitlementBalance,

packages/paykit/src/providers/provider.ts

@@ -64,6 +64,7 @@ export interface ProviderSubscription {
   endedAt?: Date | null;
   providerSubscriptionId: string;
   providerSubscriptionScheduleId?: string | null;
+  quantity?: number;
   status: string;
 }
 
@@ -75,6 +76,24 @@ export interface ProviderSubscriptionResult {
   subscription?: ProviderSubscription | null;
 }
 
+export interface ProviderSubscriptionCheckoutOptions {
+  allowPromotionCodes?: boolean;
+  automaticTax?: {
+    enabled: boolean;
+  };
+  billingAddressCollection?: "auto" | "required";
+  customerUpdate?: {
+    address?: "auto" | "never";
+    name?: "auto" | "never";
+    shipping?: "auto" | "never";
+  };
+  idempotencyKey?: string;
+  taxIdCollection?: {
+    enabled: boolean;
+    required?: "if_supported" | "never";
+  };
+}
+
 export interface PaymentProvider {
   readonly id: string;
   readonly name: string;
@@ -106,21 +125,30 @@ export interface PaymentProvider {
   }): Promise<{ url: string }>;
 
   createSubscriptionCheckout(data: {
+    checkout?: ProviderSubscriptionCheckoutOptions;
     providerCustomerId: string;
     providerProduct: Record<string, string>;
     successUrl: string;
     cancelUrl?: string;
     metadata?: Record<string, string>;
+    quantity: number;
   }): Promise<{ paymentUrl: string; providerCheckoutSessionId: string }>;
 
   createSubscription(data: {
     providerCustomerId: string;
     providerProduct: Record<string, string>;
+    quantity: number;
   }): Promise<ProviderSubscriptionResult>;
 
+  expireCheckoutSession(data: {
+    providerCheckoutSessionId: string;
+    providerCustomerId: string;
+  }): Promise<{ providerCheckoutSessionId: string; status: "expired" }>;
+
   updateSubscription(data: {
     providerProduct: Record<string, string>;
     providerSubscriptionId: string;
+    quantity: number;
   }): Promise<ProviderSubscriptionResult>;
 
   createInvoice(data: {
@@ -133,6 +161,7 @@ export interface PaymentProvider {
     providerProduct?: Record<string, string> | null;
     providerSubscriptionScheduleId?: string | null;
     providerSubscriptionId: string;
+    quantity: number;
   }): Promise<ProviderSubscriptionResult>;
 
   cancelSubscription(data: {