@vandenberghinc/volt 1.2.6 → 1.2.7

package/backend/dist/esm/backend/src/payments/stripe/subscriptions.js

@@ -0,0 +1,754 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2026 - 2026 Daan van den Bergh. All rights reserved
+ */
+import * as vlib from "@vandenberghinc/vlib";
+import { ExternalStripeError, InternalStripeError } from "./error.js";
+import { ensure_stripe_customer } from "./customers.js";
+import { assert, public_assert, stripe_api_call, is_non_empty_string, stable_idempotency_key } from "./utils.js";
+import { Collection } from "../../database/collection.js";
+// ----------------------------------------------------------------------------
+// Caching.
+/**
+ * Cache for loading the subscription record of a user.
+ *
+ * This is a short lived cache for hot paths,
+ * since changes accross multiple forks & multi-load server
+ * are not persisted to this cache.
+ */
+const subscription_record_cache = new vlib.Cache({
+    max_size: 250_000,
+    ttl: {
+        sliding: true,
+        // Short lived cache, see docstring why
+        duration: 1000 * 60 * 5,
+    },
+});
+/**
+ * List all subscriptions for a user.
+ *
+ * We do not use any caching here by design, dont change this since it will break current implementations.
+ *
+ * Stripe docs:
+ * - List subscriptions: https://docs.stripe.com/api/subscriptions/list
+ * - Expand: https://docs.stripe.com/expand
+ */
+async function list_all_customer_subscriptions(client, server, uid, customer_id) {
+    /** Validate input early to avoid cache poisoning with ambiguous keys. */
+    assert(uid.trim().length > 0, "invalid_argument", "Uid must be a non-empty string.", { uid });
+    // Ensure customer.
+    const ensured_customer_id = customer_id ?? await ensure_stripe_customer(client, server, uid);
+    // Fetch subscriptions.
+    const subscriptions = [];
+    let starting_after;
+    for (;;) {
+        const page = await stripe_api_call(() => client.subscriptions.list({
+            customer: ensured_customer_id,
+            status: "all",
+            limit: 100,
+            starting_after,
+            // ALWAYS expand, since the callee's expect this.
+            expand: ["data.items.data.price"],
+        }), { operation: "subscriptions.list", customer_id: ensured_customer_id, starting_after });
+        subscriptions.push(...page.data);
+        if (!page.has_more || page.data.length === 0) {
+            break;
+        }
+        const last = page.data[page.data.length - 1];
+        assert(last !== undefined, "api_error", "Stripe subscriptions pagination returned an empty last item.", {
+            customer_id: ensured_customer_id,
+            returned: page.data.length,
+        });
+        starting_after = last.id;
+    }
+    return subscriptions;
+}
+/**
+ * Resolve the parent subscription product for a plan.
+ * This is needed to apply subscription-level rules (trial_days, billing_anchor).
+ */
+function resolve_plan_parent_subscription(opts) {
+    for (const product of opts.all_products) {
+        if (product.type === "subscription" && product.id === opts.plan.subscription_id) {
+            return product;
+        }
+    }
+    // If we cannot find it, this indicates a corrupted initialization state.
+    throw new InternalStripeError("invalid_product", "Subscription plan refers to a missing parent subscription product.", { plan_id: opts.plan.id, subscription_id: opts.plan.subscription_id });
+}
+/**
+ * Retrieve a Stripe customer and safely resolve the default payment method id for invoices/subscriptions.
+ *
+ * Stripe docs:
+ * - Retrieve customer: https://docs.stripe.com/api/customers/retrieve
+ * - invoice_settings.default_payment_method: https://docs.stripe.com/api/customers/object#customer_object-invoice_settings
+ */
+async function resolve_default_payment_method_id(client, opts) {
+    // We expand default_payment_method so we can always read `.id` without extra requests.
+    const customer = await stripe_api_call(() => client.customers.retrieve(opts.stripe_customer_id, {
+        expand: ["invoice_settings.default_payment_method"],
+    }), { operation: "customers.retrieve", uid: opts.uid, stripe_customer_id: opts.stripe_customer_id });
+    // Stripe can return DeletedCustomer; we must never proceed if the customer is deleted.
+    public_assert(customer.deleted !== true, "customer_not_found", "Stripe customer was not found.", { uid: opts.uid, stripe_customer_id: opts.stripe_customer_id });
+    // We avoid any unsafe casts by narrowing through `unknown` and structural checks.
+    const invoice_settings = customer.invoice_settings;
+    const default_payment_method = invoice_settings?.default_payment_method;
+    // invoice_settings.default_payment_method is string | PaymentMethod | null.
+    if (typeof default_payment_method === "string") {
+        return default_payment_method;
+    }
+    if (default_payment_method && typeof default_payment_method === "object") {
+        const id = default_payment_method.id;
+        if (typeof id === "string" && id.trim().length > 0) {
+            return id;
+        }
+    }
+    // User-facing: without a default payment method, we cannot bill off-session securely.
+    throw new ExternalStripeError("payment_method_missing", "No default payment method on file. Please add a payment method before subscribing.", { uid: opts.uid, stripe_customer_id: opts.stripe_customer_id });
+}
+/**
+ * Extract a PaymentIntent from an expanded subscription.latest_invoice.payment_intent.
+ *
+ * Stripe docs:
+ * - Subscription object: https://docs.stripe.com/api/subscriptions/object
+ * - Invoice.payment_intent: https://docs.stripe.com/api/invoices/object#invoice_object-payment_intent
+ * - PaymentIntent statuses: https://docs.stripe.com/api/payment_intents/object#payment_intent_object-status
+ */
+function resolve_payment_intent_from_subscription(subscription) {
+    const latest_invoice = subscription.latest_invoice;
+    // latest_invoice is string | Invoice | null.
+    if (!latest_invoice || typeof latest_invoice === "string") {
+        return null;
+    }
+    const payment_intent = latest_invoice.payment_intent;
+    // payment_intent is string | PaymentIntent | null.
+    if (!payment_intent || typeof payment_intent === "string") {
+        return null;
+    }
+    return payment_intent;
+}
+/**
+ * Build SubscriptionCreateParams.SubscriptionData from our initialized product configuration.
+ */
+function build_subscription_create_params_from_product(opts) {
+    const parent = opts.parent_subscription;
+    const subscription_params = {
+        // Safe metadata for reconciliation and security auditing.
+        metadata: {
+            __volt_uid: opts.uid,
+            __volt_subscription_id: parent.id,
+        },
+    };
+    // Apply trial days if configured (Stripe requires integer days).
+    if (parent.trial_days !== undefined) {
+        subscription_params.trial_period_days = parent.trial_days;
+    }
+    // Apply billing anchor strategy.
+    //
+    // NOTE:
+    // - We only support "immediately" and "first_of_month" because those are the only ones we model.
+    // - For "first_of_month", we disable proration to avoid pro-rated invoices on anchor changes.
+    const billing_anchor = parent.billing_anchor ?? "immediately";
+    if (billing_anchor === "immediately") {
+        return subscription_params;
+    }
+    if (billing_anchor === "first_of_month") {
+        // We keep this logic consistent with checkout.ts: anchor to first day of next month
+        // after the trial ends (or now if no trial).
+        const now = new Date();
+        const trial_days = parent.trial_days;
+        const trial_end_reference = trial_days !== undefined ? new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + trial_days, now.getUTCHours(), now.getUTCMinutes(), now.getUTCSeconds(), now.getUTCMilliseconds())) : now;
+        const anchor_date = new Date(Date.UTC(trial_end_reference.getUTCFullYear(), trial_end_reference.getUTCMonth() + 1, 1, 0, 0, 0, 0));
+        // Stripe expects unix timestamp seconds.
+        subscription_params.billing_cycle_anchor = Math.floor(anchor_date.getTime() / 1000);
+        subscription_params.proration_behavior = "none";
+        return subscription_params;
+    }
+    // Future-proof exhaustive safety.
+    throw new InternalStripeError("invalid_product", "Unsupported billing_anchor value.", { billing_anchor, subscription_id: parent.id });
+}
+/**
+ * Create the stripe subscriptions database collection.
+ */
+function create_subscriptions_db(server) {
+    // Initialize the database connection.
+    return server.db.collection({
+        name: "Volt.Stripe.Subscriptions",
+        indexes: [
+            {
+                keys: { uid: 1 },
+                unique: true,
+            },
+        ],
+        // Ensure its not unique so we retrieve the cached collection if already created.
+        unique: false,
+    });
+}
+// ----------------------------------------------------------------------------
+// Internal but exported API.
+/**
+ * Update the subscriptions record for a user after a subscription mutation.
+ * @note This includes the meter subscriptions.
+ * @internal
+ */
+export async function update_subscription_record(client, server, opts) {
+    // List all subscriptions.
+    const subscriptions = await list_all_customer_subscriptions(client, server, opts.uid, undefined);
+    // Map subscription plan price ids to their plan ids for quick lookup.
+    const sub_price_id_to_plan_id = new Map();
+    const meter_price_id_to_product_id = new Map();
+    for (const product of opts.all_products) {
+        if (product.type === "subscription") {
+            for (const plan of product.plans) {
+                sub_price_id_to_plan_id.set(plan.stripe_price_id, plan.id);
+            }
+        }
+        else if (product.type === "meter") {
+            meter_price_id_to_product_id.set(product.stripe_price_id, product.id);
+        }
+        else if (product.type !== "one_time") {
+            // @ts-expect-error Future-proof exhaustive safety.
+            product.toString();
+        }
+    }
+    // Create record.
+    const record = {
+        uid: opts.uid,
+        subscriptions: {},
+        meters: {},
+    };
+    // Iterate.
+    for (const subscription of subscriptions) {
+        switch (subscription.status) {
+            // Store all semi-active statuses, they can later be filtered.
+            case "active":
+            case "trialing":
+            case "past_due": {
+                for (const item of subscription.items.data) {
+                    const price = item.price;
+                    if (!price) {
+                        continue;
+                    }
+                    if (sub_price_id_to_plan_id.has(price.id)) {
+                        const plan_id = sub_price_id_to_plan_id.get(price.id);
+                        if (!plan_id) {
+                            continue;
+                        }
+                        record.subscriptions[plan_id] = subscription.status;
+                    }
+                    if (meter_price_id_to_product_id.has(price.id)) {
+                        const product_id = meter_price_id_to_product_id.get(price.id);
+                        if (!product_id) {
+                            continue;
+                        }
+                        record.meters[product_id] = subscription.status;
+                    }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    // Save the record.
+    const db = create_subscriptions_db(server);
+    await db.set({ uid: opts.uid }, record, {
+        // ensure we do not flatten the subscriptions object so we can remove old plans that are no longer active.
+        flatten: false,
+        upsert: true,
+        retry: 3,
+    });
+}
+/**
+ * Load a subscription record with caching.
+ */
+async function load_subscription_record(server, opts) {
+    const use_cache = opts.cache ?? true;
+    // Check cache first.
+    if (use_cache) {
+        const cached = subscription_record_cache.get(opts.uid);
+        if (cached != null) {
+            return cached;
+        }
+    }
+    // Load.
+    const db = create_subscriptions_db(server);
+    const record = await db.load({ uid: opts.uid }, { throw: false });
+    if (record instanceof Error) {
+        if (record instanceof Collection.NotFoundError) {
+            // Cache empty record to avoid repeated db hits for users without subscriptions.
+            const empty_record = { uid: opts.uid, subscriptions: {}, meters: {} };
+            subscription_record_cache.set(opts.uid, empty_record);
+            return empty_record;
+        }
+        throw record;
+    }
+    // Cache always and return.
+    subscription_record_cache.set(opts.uid, record);
+    return record;
+}
+// ----------------------------------------------------------------------------
+// Public API.
+/**
+ * Delete a user from the subscription caches.
+ * Should be called after any mutation to the user's subscriptions to avoid stale cache entries.
+ */
+export function delete_subscription_caches(uid) {
+    subscription_record_cache.delete(uid);
+}
+/**
+ * List all subscribed product plans for a given user.
+ */
+export async function list_subscribed_plans(client, server, opts) {
+    /** Validate input early to avoid cache poisoning with ambiguous keys. */
+    assert(opts.uid.trim().length > 0, "invalid_argument", "Uid must be a non-empty string.", { uid: opts.uid });
+    // Load record.
+    const record = await load_subscription_record(server, { uid: opts.uid });
+    // Subscription statuses that represent a live (entitlement-granting) subscription.
+    const active_statuses = new Set(opts.status ?? [
+        "active",
+        "trialing",
+        "past_due",
+    ]);
+    // Walk all subscriptions.
+    const active = {};
+    for (const [id, status] of Object.entries(record.subscriptions)) {
+        if (!active_statuses.has(status)) {
+            continue;
+        }
+        active[id] = status;
+    }
+    return active;
+}
+/**
+ * List all meter product id's that a customer is currently subscribed (entitled) to.
+ *
+ * We require an active-ish subscription that contains a subscription item for the meter product's price id.
+ * This prevents accidental/abusive usage reporting for users who aren't subscribed.
+ *
+ * Stripe docs:
+ * - List subscriptions: https://docs.stripe.com/api/subscriptions/list
+ * - Expand: https://docs.stripe.com/expand
+ */
+export async function list_subscribed_meters(client, server, opts) {
+    // Load record.
+    const record = await load_subscription_record(server, { uid: opts.uid });
+    // Subscription statuses that represent a live (entitlement-granting) subscription.
+    const active_statuses = new Set(opts.status ?? [
+        "active",
+        // We dont allow `trialing` and `past_due` to reduce risk of accidental/abusive access.
+    ]);
+    // Walk all subscriptions.
+    const active = {};
+    for (const [id, status] of Object.entries(record.meters)) {
+        if (!active_statuses.has(status)) {
+            continue;
+        }
+        active[id] = status;
+    }
+    return active;
+}
+/**
+ * Check whether a user (by uid) is subscribed to a specific subscription (plan) or meter product.
+ *
+ * @returns `true` if the user has an active subscription to the subscription (plan) or meter product, `false` otherwise.
+ */
+export async function is_user_subscribed_to(client, server, opts) {
+    /** Validate inputs early. */
+    assert(opts.plan.id.trim().length > 0, "invalid_argument", "Plan.id must be a non-empty string.", { plan_id: opts.plan.id });
+    // Meter product path.
+    if (opts.plan.type === "meter") {
+        const subscribed_plans = await list_subscribed_meters(client, server, {
+            uid: opts.uid,
+            stripe_customer_id: opts.customer_id ?? await ensure_stripe_customer(client, server, opts.uid),
+            all_products: opts.all_products,
+            status: opts.status,
+        });
+        return Object.keys(subscribed_plans).includes(opts.plan.id);
+    }
+    // Subscription (plan) path.
+    else {
+        // Retrieve subscribed plans.
+        const subscribed_plans = await list_subscribed_plans(client, server, {
+            uid: opts.uid,
+            customer_id: opts.customer_id,
+            all_products: opts.all_products,
+            status: opts.status,
+        });
+        return Object.keys(subscribed_plans).includes(opts.plan.id);
+    }
+    // Not subscribed.
+    return false;
+}
+/**
+ * Create a subscription for either:
+ * - a subscription plan (licensed recurring)
+ * - a meter product (metered recurring)
+ *
+ * This uses the customer's default invoice payment method for off-session billing and
+ * returns a "requires_action" payload when SCA/3DS confirmation is needed in the UI.
+ *
+ * Stripe docs:
+ * - Create subscription: https://docs.stripe.com/api/subscriptions/create
+ * - Payment behavior (default_incomplete): https://docs.stripe.com/billing/subscriptions/overview#handling-incomplete-subscriptions
+ * - Expand: https://docs.stripe.com/expand
+ * - PaymentIntents: https://docs.stripe.com/api/payment_intents
+ *
+ * @warning This function intentionally creates subscriptions with `payment_behavior="default_incomplete"`
+ *          so we can reliably detect and surface required customer actions (SCA).
+ */
+export async function create_user_subscription(client, server, opts) {
+    // -------------------------------------------------------------------------
+    // Validate inputs (user-facing where appropriate).
+    public_assert(is_non_empty_string(opts.uid), "invalid_argument", "Property 'uid' must be a non-empty string.");
+    assert(Array.isArray(opts.all_products), "invalid_argument", "Property 'all_products' must be an array.");
+    assert(opts.target.id.trim().length > 0, "invalid_argument", "Target.id must be non-empty.", { target_id: opts.target.id });
+    // Any mutation can change entitlements; invalidate cache up-front to reduce stale reads.
+    delete_subscription_caches(opts.uid);
+    // -------------------------------------------------------------------------
+    // Ensure customer + default payment method.
+    const stripe_customer_id = await ensure_stripe_customer(client, server, opts.uid);
+    const default_payment_method_id = await resolve_default_payment_method_id(client, {
+        uid: opts.uid,
+        stripe_customer_id,
+    });
+    // -------------------------------------------------------------------------
+    // Build subscription create params.
+    const idempotency_key = stable_idempotency_key(`sub_create:${opts.uid}:${opts.idempotency_key}`);
+    // Base params shared for both plan and meter.
+    const base_params = {
+        customer: stripe_customer_id,
+        // We always charge automatically for subscriptions.
+        // Docs: https://docs.stripe.com/api/subscriptions/create#create_subscription-collection_method
+        collection_method: "charge_automatically",
+        // Use the default invoice payment method for off-session charges.
+        // Docs: https://docs.stripe.com/api/subscriptions/create#create_subscription-default_payment_method
+        default_payment_method: default_payment_method_id,
+        // Crucial: create an incomplete subscription when payment can't be completed immediately,
+        // so we can surface the PaymentIntent client_secret to the UI for SCA/3DS.
+        // Docs: https://docs.stripe.com/billing/subscriptions/overview#handling-incomplete-subscriptions
+        payment_behavior: "default_incomplete",
+        // Safe metadata only.
+        metadata: {
+            __volt_uid: opts.uid,
+            __volt_target_id: opts.target.id,
+            __volt_target_type: opts.target.type,
+        },
+    };
+    // Items differ per target type.
+    if (opts.target.type === "subscription_plan") {
+        // Resolve parent subscription product to apply trial/billing anchor coherently.
+        const parent_subscription = resolve_plan_parent_subscription({
+            plan: opts.target,
+            all_products: opts.all_products,
+        });
+        const subscription_level_params = build_subscription_create_params_from_product({
+            uid: opts.uid,
+            parent_subscription,
+        });
+        // Stripe docs: items.price https://docs.stripe.com/api/subscriptions/create#create_subscription-items-price
+        base_params.items = [{ price: opts.target.stripe_price_id, quantity: 1 }];
+        // Apply subscription-level options (trial, anchor, metadata).
+        base_params.trial_period_days = subscription_level_params.trial_period_days;
+        base_params.billing_cycle_anchor = subscription_level_params.billing_cycle_anchor;
+        base_params.proration_behavior = subscription_level_params.proration_behavior;
+        // Merge metadata (preserve base keys).
+        base_params.metadata = {
+            ...(base_params.metadata ?? {}),
+            ...(subscription_level_params.metadata ?? {}),
+            __volt_subscription_id: parent_subscription.id,
+            __volt_plan_id: opts.target.id,
+        };
+    }
+    else if (opts.target.type === "meter") {
+        // Meter products are metered recurring prices already linked to a Stripe Billing Meter during initialization.
+        // Stripe docs: https://docs.stripe.com/api/prices/create (recurring.meter)
+        base_params.items = [{ price: opts.target.stripe_price_id, quantity: 1 }];
+        // Useful context for reconciliation.
+        base_params.metadata = {
+            ...(base_params.metadata ?? {}),
+            __volt_meter_product_id: opts.target.id,
+            __volt_meter_event_name: opts.target.meter_event_name,
+        };
+    }
+    else {
+        // Exhaustive safety for future target types.
+        // @ts-expect-error should be never
+        opts.target.toString();
+        throw new InternalStripeError("invalid_argument", "Unsupported subscription target type.", { target_type: opts.target.type });
+    }
+    // -------------------------------------------------------------------------
+    // Create subscription (expand latest_invoice.payment_intent so we can surface UI actions).
+    const subscription = await stripe_api_call(() => client.subscriptions.create({
+        ...base_params,
+        // Expand payment intent so we can return client_secret for SCA, if required.
+        // Docs: https://docs.stripe.com/expand
+        expand: ["latest_invoice.payment_intent"],
+    }, { idempotencyKey: idempotency_key }), {
+        operation: "subscriptions.create",
+        uid: opts.uid,
+        stripe_customer_id,
+        target_id: opts.target.id,
+        target_type: opts.target.type,
+    });
+    // Mutation happened: invalidate cache again post-mutation to reduce stale reads.
+    delete_subscription_caches(opts.uid);
+    // -------------------------------------------------------------------------
+    // Handle outcomes:
+    // - active/trialing/past_due => success
+    // - incomplete + requires_action => UI must confirm the PaymentIntent
+    // - incomplete + requires_payment_method => user must add/replace payment method
+    const payment_intent = resolve_payment_intent_from_subscription(subscription);
+    // If Stripe indicates the PaymentIntent needs customer action, return client_secret to the UI.
+    if (payment_intent && payment_intent.status === "requires_action") {
+        const client_secret = payment_intent.client_secret;
+        public_assert(is_non_empty_string(client_secret), "subscription_payment_action_required", "Additional payment verification is required, but Stripe did not return a client secret.", { subscription_id: subscription.id, payment_intent_id: payment_intent.id });
+        return {
+            type: "requires_action",
+            subscription_id: subscription.id,
+            stripe_customer_id,
+            payment_intent_id: payment_intent.id,
+            client_secret,
+            status: subscription.status,
+        };
+    }
+    // If payment method was rejected/invalid, surface a user-actionable error.
+    if (payment_intent && payment_intent.status === "requires_payment_method") {
+        throw new ExternalStripeError("payment_method_missing", "Your default payment method could not be charged. Please update your payment method and try again.", { subscription_id: subscription.id, payment_intent_id: payment_intent.id });
+    }
+    // Some accounts/flows may produce an "incomplete" subscription without an expanded PI; treat as internal inconsistency.
+    if (subscription.status === "incomplete" || subscription.status === "incomplete_expired") {
+        throw new InternalStripeError("subscription_create_error", "Subscription was created in an incomplete state without a resolvable PaymentIntent.", {
+            uid: opts.uid,
+            stripe_customer_id,
+            subscription_id: subscription.id,
+            status: subscription.status,
+            has_latest_invoice: subscription.latest_invoice != null,
+            has_payment_intent: payment_intent != null,
+        });
+    }
+    // Otherwise, consider it created (active/trialing/past_due/etc).
+    return {
+        type: "created",
+        subscription_id: subscription.id,
+        stripe_customer_id,
+        status: subscription.status,
+    };
+}
+/**
+ * Cancel a user's Stripe subscription(s) matching a specific subscription plan.
+ *
+ * Important behavior change:
+ * - If the matched Stripe Subscription contains multiple subscription items (multiple plans),
+ *   we still cancel the *entire* subscription (all items) to keep semantics simple and consistent.
+ *
+ * Stripe docs:
+ * - Cancel a subscription: https://docs.stripe.com/api/subscriptions/cancel
+ * - Update a subscription (cancel_at_period_end): https://docs.stripe.com/api/subscriptions/update
+ * - List subscriptions: https://docs.stripe.com/api/subscriptions/list
+ *
+ * @note If a user is not subscribed to the specified plan, this function succeeds without doing anything (idempotent).
+ *
+ * @returns The affected subscriptions which were canceled/updated.
+ */
+export async function cancel_user_subscription(client, server, opts) {
+    // -------------------------------------------------------------------------
+    // Validate inputs.
+    const uid = opts.uid;
+    /** Validate uid so we never act on an ambiguous identity. */
+    assert(uid.trim().length > 0, "invalid_argument", "Uid must be a non-empty string.", { uid });
+    /** Validate plan fields so we only match the intended Stripe price. */
+    assert(opts.plan.id.trim().length > 0, "invalid_argument", "Plan.id must be non-empty.", { plan_id: opts.plan.id });
+    assert(opts.plan.stripe_price_id.trim().length > 0, "invalid_argument", "Plan.stripe_price_id must be non-empty.", { plan_id: opts.plan.id });
+    const cancel_at_period_end = opts.cancel_at_period_end ?? true;
+    // Any mutation can change entitlements; invalidate cache up-front to reduce stale reads.
+    delete_subscription_caches(uid);
+    // -------------------------------------------------------------------------
+    // Fetch subscriptions.
+    /** Fetch all subscriptions (paginated). */
+    const subscriptions = await list_all_customer_subscriptions(client, server, uid, opts.customer_id);
+    // -------------------------------------------------------------------------
+    // Identify matching subscriptions.
+    // Subscription statuses that represent a live (entitlement-granting) subscription.
+    const active_sub_status = new Set([
+        "active",
+        "trialing",
+        "past_due", // since Stripe can keep subscriptions in past_due while retrying payment.
+    ]);
+    const affected_subscriptions = [];
+    for (const subscription of subscriptions) {
+        // We only operate on active-ish subscriptions; canceled/unpaid ones are ignored.
+        if (!active_sub_status.has(subscription.status)) {
+            continue;
+        }
+        // Match if any subscription item uses the plan's Stripe price id.
+        let matches_plan = false;
+        for (const item of subscription.items.data) {
+            const price = item.price;
+            if (!price) {
+                continue;
+            }
+            if (price.id === opts.plan.stripe_price_id) {
+                matches_plan = true;
+                break;
+            }
+        }
+        if (!matches_plan) {
+            continue;
+        }
+        affected_subscriptions.push(subscription);
+    }
+    // Idempotent semantics: if nothing matches, succeed without doing anything.
+    if (affected_subscriptions.length === 0) {
+        // Best-effort cache invalidation so the next read doesn't serve stale positives.
+        delete_subscription_caches(uid);
+        return [];
+    }
+    // -------------------------------------------------------------------------
+    // Cancel/update subscriptions.
+    //
+    // NOTE: Even if a subscription contains multiple items (multiple plans),
+    // we cancel the entire subscription to avoid partial-cancel surprises.
+    await Promise.all(affected_subscriptions.map(async (subscription) => {
+        if (cancel_at_period_end) {
+            // Non-destructive cancel: the subscription stays active until end of period, then cancels.
+            await stripe_api_call(() => client.subscriptions.update(subscription.id, { cancel_at_period_end: true }, { idempotencyKey: stable_idempotency_key(`sub_update_cancel_at_period_end:${subscription.id}`) }), {
+                operation: "subscriptions.update",
+                action: "cancel_at_period_end",
+                uid,
+                subscription_id: subscription.id,
+                plan_id: opts.plan.id,
+                stripe_price_id: opts.plan.stripe_price_id,
+            });
+        }
+        else {
+            // Immediate cancellation.
+            await stripe_api_call(() => client.subscriptions.cancel(subscription.id, undefined, { idempotencyKey: stable_idempotency_key(`sub_cancel_immediate:${subscription.id}`) }), {
+                operation: "subscriptions.cancel",
+                action: "cancel_immediately",
+                uid,
+                subscription_id: subscription.id,
+                plan_id: opts.plan.id,
+                stripe_price_id: opts.plan.stripe_price_id,
+            });
+        }
+    }));
+    // Mutation happened: invalidate cache again post-mutation to reduce stale reads.
+    delete_subscription_caches(uid);
+    // Response.
+    return affected_subscriptions;
+}
+/**
+ * Enforce that a user can only have **one active subscription plan per SubscriptionProduct**.
+ *
+ * Workflow:
+ * 1. Accepts the newly created/updated Stripe.Subscription (expanded items.price).
+ * 2. Resolves which internal SubscriptionProduct it belongs to by matching *all* known plan price IDs.
+ * 3. Lists all customer subscriptions.
+ * 4. Cancels (immediately) all other active subscriptions that contain *any* plan
+ *    from the same SubscriptionProduct, excluding the newly created subscription.
+ *
+ * Safety guarantees:
+ * - Does nothing if the new subscription is not live.
+ * - Does nothing if the subscription does not map to any known SubscriptionProduct.
+ * - Cancels only subscriptions that clearly overlap with the same SubscriptionProduct.
+ */
+export async function enforce_single_subscription_plan(client, server, opts) {
+    assert(opts.uid.length > 0, "invalid_argument", "uid must be provided");
+    assert(opts.stripe_customer_id.length > 0, "invalid_argument", "stripe_customer_id must be provided");
+    const { new_subscription, all_products } = opts;
+    // Subscription statuses that represent a live (entitlement-granting) subscription.
+    // Keep inline to avoid confusion with `active_subscription_statuses`.
+    const active_sub_status = new Set([
+        "active",
+        "trialing",
+        "past_due",
+    ]);
+    // Only enforce for live subscriptions
+    if (!active_sub_status.has(new_subscription.status)) {
+        return [];
+    }
+    // Build a map of price_id -> SubscriptionProduct
+    const price_to_subscription_product = new Map();
+    for (const product of all_products) {
+        if (product.type !== "subscription")
+            continue;
+        for (const plan of product.plans) {
+            price_to_subscription_product.set(plan.stripe_price_id, product);
+        }
+    }
+    // Resolve which SubscriptionProduct this new subscription belongs to
+    const resolved_products = new Set();
+    for (const item of new_subscription.items.data) {
+        const price = item.price;
+        if (!price)
+            continue;
+        // Enforce expanded price object, otherwise we can't safely map price ids.
+        assert(typeof price !== "string", "invalid_argument", "new_subscription.items.data.price must be expanded.", {
+            subscription_id: new_subscription.id,
+        });
+        const sub_product = price_to_subscription_product.get(price.id);
+        if (sub_product) {
+            resolved_products.add(sub_product);
+        }
+    }
+    // If we can't resolve exactly one subscription product, do nothing
+    if (resolved_products.size === 0) {
+        return [];
+    }
+    if (resolved_products.size > 1) {
+        throw new InternalStripeError("subscription_resolution_error", "Subscription resolves to multiple subscription products.", {
+            subscription_id: new_subscription.id,
+            subscription_product_ids: [...resolved_products].map((p) => p.id),
+        });
+    }
+    const [subscription_product] = [...resolved_products];
+    // All Stripe price ids belonging to this SubscriptionProduct
+    const product_price_ids = new Set(subscription_product.plans.map((p) => p.stripe_price_id));
+    // Fetch all customer subscriptions
+    const all_subscriptions = await list_all_customer_subscriptions(client, server, opts.uid, opts.stripe_customer_id);
+    const canceled = [];
+    for (const sub of all_subscriptions) {
+        // Skip the newly created subscription
+        if (sub.id === new_subscription.id)
+            continue;
+        // Only cancel live subscriptions
+        if (!active_sub_status.has(sub.status))
+            continue;
+        // Check if this subscription contains *any* plan from the same SubscriptionProduct
+        let overlaps = false;
+        for (const item of sub.items.data) {
+            const price = item.price;
+            if (!price)
+                continue;
+            assert(typeof price !== "string", "api_error", "Expected expanded item.price from subscriptions.list expand.", {
+                subscription_id: sub.id,
+            });
+            if (product_price_ids.has(price.id)) {
+                overlaps = true;
+                break;
+            }
+        }
+        if (!overlaps)
+            continue;
+        // Cancel immediately (idempotent)
+        await stripe_api_call(() => client.subscriptions.cancel(sub.id, undefined, {
+            idempotencyKey: opts.idempotency_key ?? stable_idempotency_key(`enforce_single_plan:${opts.stripe_customer_id}:${new_subscription.id}:${sub.id}`),
+        }), {
+            operation: "subscriptions.cancel",
+            action: "enforce_single_plan",
+            uid: opts.uid,
+            stripe_customer_id: opts.stripe_customer_id,
+            kept_subscription_id: new_subscription.id,
+            canceled_subscription_id: sub.id,
+            subscription_product_id: subscription_product.id,
+        });
+        canceled.push(sub);
+    }
+    // Invalidate cache.
+    if (canceled.length > 0) {
+        delete_subscription_caches(opts.uid);
+    }
+    // Return.
+    return canceled;
+}