@shware/purchase 7.5.0 → 8.0.0

package/dist/stripe/config.mjs

@@ -1,7 +1,10 @@
+import { assertCatalog, assertDeclared, assertInNamespace } from "../catalog.mjs";
 import { invariant } from "@shware/utils";
 import ms from "ms";
 //#region src/stripe/config.ts
 const addMethod = Symbol("addMethod");
+/** The private constructor's one door, for this module's `define` function only. */
+const construct = Symbol("construct");
 var Product = class {
 	id;
 	config;
@@ -59,6 +62,9 @@ var StripeConfig = class StripeConfig {
 	successUrl;
 	cancellationCouponId;
 	allowPromotionCodes;
+	namespace;
+	plans;
+	billingPeriods;
 	get productIds() {
 		return Array.from(this.products.keys());
 	}
@@ -70,6 +76,10 @@ var StripeConfig = class StripeConfig {
 		return this;
 	};
 	constructor(options) {
+		assertCatalog(options);
+		this.namespace = options.namespace;
+		this.plans = options.plans;
+		this.billingPeriods = options.billingPeriods;
 		this.mode = options.mode;
 		this.returnUrl = options.returnUrl;
 		this.cancelUrl = options.cancelUrl;
@@ -77,14 +87,16 @@ var StripeConfig = class StripeConfig {
 		this.cancellationCouponId = options.cancellationCouponId;
 		this.allowPromotionCodes = options.allowPromotionCodes;
 	}
-	static create = (options) => {
-		return new StripeConfig(options);
-	};
+	static [construct] = (options) => new StripeConfig(options);
 	/**
 	* One-time products take no extra args; subscriptions require both plan and billingPeriod.
 	* A plan+period pair may be declared on only one product — version its prices in that chain.
 	*/
-	product = (productId, plan = null, billingPeriod = null) => new Product(this, productId, plan, billingPeriod);
+	product = (productId, plan = null, billingPeriod = null) => {
+		assertInNamespace(this.namespace, productId);
+		assertDeclared(this, plan, billingPeriod);
+		return new Product(this, productId, plan, billingPeriod);
+	};
 	getPlan = (productId) => {
 		const product = this.products.get(productId);
 		invariant(product, `Product not found for ${productId}`);
@@ -102,6 +114,15 @@ var StripeConfig = class StripeConfig {
 		invariant(product, `Product not found for ${productId}`);
 		return product.plan === null ? "payment" : "subscription";
 	};
+	/**
+	* Whether the config declares `productId` and sells it as a subscription, so `getPlan` and
+	* `getBillingPeriod` hold for it. False, not a throw, for an id it does not know: a product that
+	* left the config (renamed, retired) or one named by metadata set outside the app.
+	*/
+	isSubscription = (productId) => {
+		const product = this.products.get(productId);
+		return product !== void 0 && product.plan !== null;
+	};
 	/** The price new checkouts are created with: the default, or its test twin in test mode. */
 	getPriceId = (productId) => {
 		const product = this.products.get(productId);
@@ -119,6 +140,22 @@ var StripeConfig = class StripeConfig {
 		for (const product of this.products.values()) if (product.prices.has(priceId)) return product.id;
 		return null;
 	};
+	/**
+	* How switching from one subscription product to another relates them (see
+	* {@link PlanComparison}), by the order `plans` and `billingPeriods` were declared in. Throws for
+	* a product that is not a subscription.
+	*/
+	comparePlans = (fromProductId, toProductId) => {
+		const level = (productId) => ({
+			plan: this.plans.indexOf(this.getPlan(productId)),
+			period: this.billingPeriods.indexOf(this.getBillingPeriod(productId))
+		});
+		const from = level(fromProductId);
+		const to = level(toProductId);
+		if (to.plan !== from.plan) return to.plan > from.plan ? "upgrade" : "downgrade";
+		if (to.period !== from.period) return to.period > from.period ? "longer" : "shorter";
+		return "same";
+	};
 	getCreditAmount = (productId, priceId) => {
 		const product = this.products.get(productId);
 		invariant(product, `Product not found for ${productId}`);
@@ -146,7 +183,15 @@ var StripeConfig = class StripeConfig {
 		return new Date(Date.now() + expiresIn).toISOString();
 	};
 };
+/**
+* Declare the Stripe product catalog. Every type parameter is inferred from the options:
+* the namespace from `namespace`, the plans and billing periods from `plans` and `billingPeriods`
+* (`const`, so a literal array needs no `as const`). Products are then added with the fluent chain.
+*/
+function defineStripeConfig(options) {
+	return StripeConfig[construct](options);
+}
 //#endregion
-export { StripeConfig };
+export { StripeConfig, defineStripeConfig };
 
 //# sourceMappingURL=config.mjs.map

package/dist/stripe/config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"config.mjs","names":[],"sources":["../../src/stripe/config.ts"],"sourcesContent":["import { invariant } from '@shware/utils';\nimport ms from 'ms';\nimport type { Metadata } from '../types';\n\nexport type PriceId = `price_${string}`;\n\n/**\n * Which Stripe object space the config addresses. Test and live prices are\n * disjoint, so a config is built for exactly one of them. Derive it from the\n * secret key (`sk_test_` vs `sk_live_`) rather than from the deployment\n * environment: the key is what actually decides which space API calls hit.\n */\nexport type StripeMode = 'live' | 'test';\n\nconst addMethod = Symbol('addMethod');\n\nclass Product<\n  NS extends Lowercase<string> = Lowercase<string>,\n  PE extends string = string,\n  BP extends string = string,\n  PL extends string = never,\n  PI extends string = never,\n  I extends PriceId = never,\n> {\n  readonly id: string;\n  readonly config: StripeConfig<NS, PE, BP, PL, PI>;\n  readonly plan: PE | null;\n  readonly billingPeriod: BP | null;\n  readonly prices: Map<PriceId, Metadata>;\n\n  defaultPriceId: PriceId | null;\n\n  constructor(\n    config: StripeConfig<NS, PE, BP, PL, PI>,\n    id: string,\n    plan: PE | null = null,\n    billingPeriod: BP | null = null\n  ) {\n    this.id = id;\n    this.config = config;\n    this.plan = plan;\n    this.billingPeriod = billingPeriod;\n    this.prices = new Map();\n    this.defaultPriceId = null;\n  }\n\n  /**\n   * Non-default prices stay declared on purpose: they keep resolving for\n   * grandfathered subscribers and serve as price-experiment arms. Never\n   * create new checkouts with a legacy price unless that is intentional.\n   */\n  price = <K extends PriceId>(\n    priceId: K extends I ? never : K,\n    metadata: Metadata = { credits: 0, expiresIn: '0' }\n  ): Product<NS, PE, BP, PL, PI, I | K> => {\n    invariant(!this.prices.has(priceId), `Duplicate price ${priceId}`);\n    this.prices.set(priceId, metadata);\n    return this as Product<NS, PE, BP, PL, PI, I | K>;\n  };\n\n  /**\n   * `test` is the sandbox twin of the default price. In test mode it is what\n   * checkouts are created with, and it resolves to the default price's\n   * entitlement, so credits are declared once and cannot drift between the\n   * two modes. Legacy prices need no twin: a sandbox holds no grandfathered\n   * subscribers. Live mode ignores it, so a test price reaching a live config\n   * still fails as an unknown price instead of being granted an entitlement.\n   */\n  default = (defaultPriceId: I, twin?: { test: PriceId }) => {\n    const metadata = this.prices.get(defaultPriceId);\n    invariant(metadata, `Default price ${defaultPriceId} is not declared`);\n    if (this.config.mode === 'test') {\n      invariant(twin, `Test price not declared for default ${defaultPriceId} of ${this.id}`);\n      invariant(!this.prices.has(twin.test), `Duplicate price ${twin.test}`);\n      this.prices.set(twin.test, metadata);\n      this.defaultPriceId = twin.test;\n    } else {\n      this.defaultPriceId = defaultPriceId;\n    }\n    this.config[addMethod](this);\n    return this.config;\n  };\n}\n\ntype Options = {\n  mode: StripeMode;\n  returnUrl: string;\n  cancelUrl: string;\n  successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;\n  cancellationCouponId: string;\n  allowPromotionCodes: boolean;\n};\n\nexport class StripeConfig<\n  NS extends Lowercase<string> = Lowercase<string>,\n  PE extends string = string,\n  BP extends string = string,\n  PL extends string = never,\n  PI extends string = never,\n> {\n  private readonly products: Map<string, Product<NS, PE, BP, PL, PI>> = new Map();\n\n  public readonly mode: StripeMode;\n  public returnUrl: string;\n  public cancelUrl: string;\n  public successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;\n  public cancellationCouponId: string;\n  public allowPromotionCodes: boolean;\n\n  get productIds(): string[] {\n    return Array.from(this.products.keys());\n  }\n\n  // runtime mirror of the type-level guards: generic accumulation only\n  // protects a single fluent chain, not statement-style re-entry or casts\n  [addMethod] = (product: Product<NS, PE, BP, PL, PI>) => {\n    invariant(!this.products.has(product.id), `Duplicate product ${product.id}`);\n    // A Stripe price belongs to one Stripe product, and getProductId must have one answer.\n    for (const existing of this.products.values()) {\n      for (const priceId of product.prices.keys()) {\n        invariant(!existing.prices.has(priceId), `Duplicate price ${priceId} on ${existing.id}`);\n      }\n    }\n    if (product.plan !== null) {\n      for (const existing of this.products.values()) {\n        invariant(\n          existing.plan !== product.plan || existing.billingPeriod !== product.billingPeriod,\n          `Duplicate plan ${product.plan}:${product.billingPeriod}`\n        );\n      }\n    }\n    this.products.set(product.id, product);\n    return this;\n  };\n\n  private constructor(options: Options) {\n    this.mode = options.mode;\n    this.returnUrl = options.returnUrl;\n    this.cancelUrl = options.cancelUrl;\n    this.successUrl = options.successUrl;\n    this.cancellationCouponId = options.cancellationCouponId;\n    this.allowPromotionCodes = options.allowPromotionCodes;\n  }\n\n  static create = <NS extends Lowercase<string>, PE extends string, BP extends string = string>(\n    options: Options\n  ) => {\n    return new StripeConfig<NS, PE, BP>(options);\n  };\n\n  /**\n   * One-time products take no extra args; subscriptions require both plan and billingPeriod.\n   * A plan+period pair may be declared on only one product — version its prices in that chain.\n   */\n  product: {\n    <K extends `${NS}.${Lowercase<string>}`>(\n      productId: K extends PI ? never : K\n    ): Product<NS, PE, BP, PL, K | PI>;\n    <K extends `${NS}.${Lowercase<string>}`, L extends PE, P extends BP>(\n      productId: K extends PI ? never : K,\n      plan: L,\n      billingPeriod: `${L}:${P}` extends PL ? never : P\n    ): Product<NS, PE, BP, `${L}:${P}` | PL, K | PI>;\n  } = (productId: string, plan: PE | null = null, billingPeriod: BP | null = null) =>\n    // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- widens to the overloads' accumulated generics\n    new Product(this, productId, plan, billingPeriod) as never;\n\n  getPlan = (productId: string): PE => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.plan, `Product ${productId} is not a subscription`);\n    return product.plan;\n  };\n\n  getBillingPeriod = (productId: string): BP => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.billingPeriod, `Product ${productId} is not a subscription`);\n    return product.billingPeriod;\n  };\n\n  getMode = (productId: string): 'payment' | 'subscription' => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    return product.plan === null ? 'payment' : 'subscription';\n  };\n\n  /** The price new checkouts are created with: the default, or its test twin in test mode. */\n  getPriceId = (productId: string): PriceId => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return product.defaultPriceId;\n  };\n\n  /**\n   * The product that declares `priceId` (a legacy price or the test twin included), or null for a\n   * price this config does not know: one set up by hand in the dashboard, or a test price reaching\n   * a live config. Reading the product from the price a Stripe object charged, rather than from\n   * metadata that may already name the next plan, is what an invoice should be credited by.\n   */\n  getProductId = (priceId: string): string | null => {\n    for (const product of this.products.values()) {\n      if (product.prices.has(priceId as PriceId)) return product.id;\n    }\n    return null;\n  };\n\n  getCreditAmount = (productId: string, priceId?: string): number => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    if (priceId) {\n      const price = product.prices.get(priceId as PriceId);\n      invariant(price, `Price not found for ${priceId}`);\n      return price.credits;\n    }\n\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return product.prices.get(product.defaultPriceId)?.credits ?? 0;\n  };\n\n  private readonly getCreditExpiresIn = (productId: string, priceId?: string): number => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    if (priceId) {\n      const price = product.prices.get(priceId as PriceId);\n      invariant(price, `Price not found for ${priceId}`);\n      return ms(price.expiresIn);\n    }\n\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return ms(product.prices.get(product.defaultPriceId)?.expiresIn ?? '0');\n  };\n\n  getCreditExpiresAt = (productId: string, priceId?: string): string => {\n    const expiresIn = this.getCreditExpiresIn(productId, priceId);\n    return new Date(Date.now() + expiresIn).toISOString();\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"config.mjs","names":[],"sources":["../../src/stripe/config.ts"],"sourcesContent":["import { invariant } from '@shware/utils';\nimport ms from 'ms';\nimport { type Catalog, assertCatalog, assertDeclared, assertInNamespace } from '../catalog';\nimport type { Metadata } from '../types';\n\nexport type PriceId = `price_${string}`;\n\n/**\n * Which Stripe object space the config addresses. Test and live prices are\n * disjoint, so a config is built for exactly one of them. Derive it from the\n * secret key (`sk_test_` vs `sk_live_`) rather than from the deployment\n * environment: the key is what actually decides which space API calls hit.\n */\nexport type StripeMode = 'live' | 'test';\n\nconst addMethod = Symbol('addMethod');\n/** The private constructor's one door, for this module's `define` function only. */\nconst construct = Symbol('construct');\n\nclass Product<\n  NS extends Lowercase<string> = Lowercase<string>,\n  PE extends string = string,\n  BP extends string = string,\n  PL extends string = never,\n  PI extends string = never,\n  I extends PriceId = never,\n> {\n  readonly id: string;\n  readonly config: StripeConfig<NS, PE, BP, PL, PI>;\n  readonly plan: PE | null;\n  readonly billingPeriod: BP | null;\n  readonly prices: Map<PriceId, Metadata>;\n\n  defaultPriceId: PriceId | null;\n\n  constructor(\n    config: StripeConfig<NS, PE, BP, PL, PI>,\n    id: string,\n    plan: PE | null = null,\n    billingPeriod: BP | null = null\n  ) {\n    this.id = id;\n    this.config = config;\n    this.plan = plan;\n    this.billingPeriod = billingPeriod;\n    this.prices = new Map();\n    this.defaultPriceId = null;\n  }\n\n  /**\n   * Non-default prices stay declared on purpose: they keep resolving for\n   * grandfathered subscribers and serve as price-experiment arms. Never\n   * create new checkouts with a legacy price unless that is intentional.\n   */\n  price = <K extends PriceId>(\n    priceId: K extends I ? never : K,\n    metadata: Metadata = { credits: 0, expiresIn: '0' }\n  ): Product<NS, PE, BP, PL, PI, I | K> => {\n    invariant(!this.prices.has(priceId), `Duplicate price ${priceId}`);\n    this.prices.set(priceId, metadata);\n    return this as Product<NS, PE, BP, PL, PI, I | K>;\n  };\n\n  /**\n   * `test` is the sandbox twin of the default price. In test mode it is what\n   * checkouts are created with, and it resolves to the default price's\n   * entitlement, so credits are declared once and cannot drift between the\n   * two modes. Legacy prices need no twin: a sandbox holds no grandfathered\n   * subscribers. Live mode ignores it, so a test price reaching a live config\n   * still fails as an unknown price instead of being granted an entitlement.\n   */\n  default = (defaultPriceId: I, twin?: { test: PriceId }) => {\n    const metadata = this.prices.get(defaultPriceId);\n    invariant(metadata, `Default price ${defaultPriceId} is not declared`);\n    if (this.config.mode === 'test') {\n      invariant(twin, `Test price not declared for default ${defaultPriceId} of ${this.id}`);\n      invariant(!this.prices.has(twin.test), `Duplicate price ${twin.test}`);\n      this.prices.set(twin.test, metadata);\n      this.defaultPriceId = twin.test;\n    } else {\n      this.defaultPriceId = defaultPriceId;\n    }\n    this.config[addMethod](this);\n    return this.config;\n  };\n}\n\n/** `plans` and `billingPeriods` are the order {@link StripeConfig.comparePlans} reads. */\ntype Options<NS extends Lowercase<string>, PE extends string, BP extends string> = Catalog<\n  NS,\n  PE,\n  BP\n> & {\n  mode: StripeMode;\n  returnUrl: string;\n  cancelUrl: string;\n  successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;\n  cancellationCouponId: string;\n  allowPromotionCodes: boolean;\n};\n\n/**\n * How a switch between two subscription products relates them, by plan level first and billing\n * period second:\n * - `upgrade` / `downgrade`: a higher or lower plan, whatever the periods.\n * - `longer` / `shorter`: the same plan billed over a longer or shorter period (monthly → yearly\n *   is `longer`). Apple calls these crossgrades.\n * - `same`: the same plan and period.\n */\nexport type PlanComparison = 'upgrade' | 'downgrade' | 'longer' | 'shorter' | 'same';\n\nexport class StripeConfig<\n  NS extends Lowercase<string> = Lowercase<string>,\n  PE extends string = string,\n  BP extends string = string,\n  PL extends string = never,\n  PI extends string = never,\n> {\n  private readonly products: Map<string, Product<NS, PE, BP, PL, PI>> = new Map();\n\n  public readonly mode: StripeMode;\n  public returnUrl: string;\n  public cancelUrl: string;\n  public successUrl: `${string}session_id={CHECKOUT_SESSION_ID}${string}`;\n  public cancellationCouponId: string;\n  public allowPromotionCodes: boolean;\n  public readonly namespace: NS;\n  public readonly plans: readonly PE[];\n  public readonly billingPeriods: readonly BP[];\n\n  get productIds(): string[] {\n    return Array.from(this.products.keys());\n  }\n\n  // runtime mirror of the type-level guards: generic accumulation only\n  // protects a single fluent chain, not statement-style re-entry or casts\n  [addMethod] = (product: Product<NS, PE, BP, PL, PI>) => {\n    invariant(!this.products.has(product.id), `Duplicate product ${product.id}`);\n    // A Stripe price belongs to one Stripe product, and getProductId must have one answer.\n    for (const existing of this.products.values()) {\n      for (const priceId of product.prices.keys()) {\n        invariant(!existing.prices.has(priceId), `Duplicate price ${priceId} on ${existing.id}`);\n      }\n    }\n    if (product.plan !== null) {\n      for (const existing of this.products.values()) {\n        invariant(\n          existing.plan !== product.plan || existing.billingPeriod !== product.billingPeriod,\n          `Duplicate plan ${product.plan}:${product.billingPeriod}`\n        );\n      }\n    }\n    this.products.set(product.id, product);\n    return this;\n  };\n\n  private constructor(options: Options<NS, PE, BP>) {\n    assertCatalog(options);\n    this.namespace = options.namespace;\n    this.plans = options.plans;\n    this.billingPeriods = options.billingPeriods;\n    this.mode = options.mode;\n    this.returnUrl = options.returnUrl;\n    this.cancelUrl = options.cancelUrl;\n    this.successUrl = options.successUrl;\n    this.cancellationCouponId = options.cancellationCouponId;\n    this.allowPromotionCodes = options.allowPromotionCodes;\n  }\n\n  static [construct] = <NS extends Lowercase<string>, PE extends string, BP extends string>(\n    options: Options<NS, PE, BP>\n  ) => new StripeConfig<NS, PE, BP>(options);\n\n  /**\n   * One-time products take no extra args; subscriptions require both plan and billingPeriod.\n   * A plan+period pair may be declared on only one product — version its prices in that chain.\n   */\n  product: {\n    <K extends `${NS}.${Lowercase<string>}`>(\n      productId: K extends PI ? never : K\n    ): Product<NS, PE, BP, PL, K | PI>;\n    <K extends `${NS}.${Lowercase<string>}`, L extends PE, P extends BP>(\n      productId: K extends PI ? never : K,\n      plan: L,\n      billingPeriod: `${L}:${P}` extends PL ? never : P\n    ): Product<NS, PE, BP, `${L}:${P}` | PL, K | PI>;\n  } = (productId: string, plan: PE | null = null, billingPeriod: BP | null = null) => {\n    assertInNamespace(this.namespace, productId);\n    assertDeclared(this, plan, billingPeriod);\n    // oxlint-disable-next-line typescript/no-unnecessary-type-assertion -- widens to the overloads' accumulated generics\n    return new Product(this, productId, plan, billingPeriod) as never;\n  };\n\n  getPlan = (productId: string): PE => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.plan, `Product ${productId} is not a subscription`);\n    return product.plan;\n  };\n\n  getBillingPeriod = (productId: string): BP => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.billingPeriod, `Product ${productId} is not a subscription`);\n    return product.billingPeriod;\n  };\n\n  getMode = (productId: string): 'payment' | 'subscription' => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    return product.plan === null ? 'payment' : 'subscription';\n  };\n\n  /**\n   * Whether the config declares `productId` and sells it as a subscription, so `getPlan` and\n   * `getBillingPeriod` hold for it. False, not a throw, for an id it does not know: a product that\n   * left the config (renamed, retired) or one named by metadata set outside the app.\n   */\n  isSubscription = (productId: string): boolean => {\n    const product = this.products.get(productId);\n    return product !== undefined && product.plan !== null;\n  };\n\n  /** The price new checkouts are created with: the default, or its test twin in test mode. */\n  getPriceId = (productId: string): PriceId => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return product.defaultPriceId;\n  };\n\n  /**\n   * The product that declares `priceId` (a legacy price or the test twin included), or null for a\n   * price this config does not know: one set up by hand in the dashboard, or a test price reaching\n   * a live config. Reading the product from the price a Stripe object charged, rather than from\n   * metadata that may already name the next plan, is what an invoice should be credited by.\n   */\n  getProductId = (priceId: string): string | null => {\n    for (const product of this.products.values()) {\n      if (product.prices.has(priceId as PriceId)) return product.id;\n    }\n    return null;\n  };\n\n  /**\n   * How switching from one subscription product to another relates them (see\n   * {@link PlanComparison}), by the order `plans` and `billingPeriods` were declared in. Throws for\n   * a product that is not a subscription.\n   */\n  comparePlans = (fromProductId: string, toProductId: string): PlanComparison => {\n    const level = (productId: string) => ({\n      plan: this.plans.indexOf(this.getPlan(productId)),\n      period: this.billingPeriods.indexOf(this.getBillingPeriod(productId)),\n    });\n    const from = level(fromProductId);\n    const to = level(toProductId);\n    if (to.plan !== from.plan) return to.plan > from.plan ? 'upgrade' : 'downgrade';\n    if (to.period !== from.period) return to.period > from.period ? 'longer' : 'shorter';\n    return 'same';\n  };\n\n  getCreditAmount = (productId: string, priceId?: string): number => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    if (priceId) {\n      const price = product.prices.get(priceId as PriceId);\n      invariant(price, `Price not found for ${priceId}`);\n      return price.credits;\n    }\n\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return product.prices.get(product.defaultPriceId)?.credits ?? 0;\n  };\n\n  private readonly getCreditExpiresIn = (productId: string, priceId?: string): number => {\n    const product = this.products.get(productId);\n    invariant(product, `Product not found for ${productId}`);\n    if (priceId) {\n      const price = product.prices.get(priceId as PriceId);\n      invariant(price, `Price not found for ${priceId}`);\n      return ms(price.expiresIn);\n    }\n\n    invariant(product.defaultPriceId, `Default price not found for product ${productId}`);\n    return ms(product.prices.get(product.defaultPriceId)?.expiresIn ?? '0');\n  };\n\n  getCreditExpiresAt = (productId: string, priceId?: string): string => {\n    const expiresIn = this.getCreditExpiresIn(productId, priceId);\n    return new Date(Date.now() + expiresIn).toISOString();\n  };\n}\n\n/**\n * Declare the Stripe product catalog. Every type parameter is inferred from the options:\n * the namespace from `namespace`, the plans and billing periods from `plans` and `billingPeriods`\n * (`const`, so a literal array needs no `as const`). Products are then added with the fluent chain.\n */\nexport function defineStripeConfig<\n  const NS extends Lowercase<string>,\n  const PE extends string,\n  const BP extends string,\n>(options: Options<NS, PE, BP>): StripeConfig<NS, PE, BP> {\n  return StripeConfig[construct](options);\n}\n"],"mappings":"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"}

package/dist/stripe/index.cjs

@@ -9,10 +9,13 @@ const require_stripe_payment_method = require("./payment-method.cjs");
 const require_stripe_thin_handler = require("./thin-handler.cjs");
 const require_stripe_schema = require("./schema.cjs");
 const require_stripe_metadata = require("./metadata.cjs");
+const require_stripe_plan_change = require("./plan-change.cjs");
 const require_stripe_pending_checkout = require("./pending-checkout.cjs");
 exports.DECLINE_REASONS = require_stripe_decline.DECLINE_REASONS;
 exports.DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES = require_stripe_payment_method.DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES;
 exports.METADATA_KEYS = require_stripe_metadata.METADATA_KEYS;
+exports.PLAN_CHANGE_ERROR_REASONS = require_stripe_plan_change.PLAN_CHANGE_ERROR_REASONS;
+exports.PlanChangeError = require_stripe_plan_change.PlanChangeError;
 exports.StripeConfig = require_stripe_config.StripeConfig;
 exports.StripeEventHandler = require_stripe_handler.StripeEventHandler;
 exports.StripeThinEventHandler = require_stripe_thin_handler.StripeThinEventHandler;
@@ -20,6 +23,8 @@ exports.addPendingCheckout = require_stripe_pending_checkout.addPendingCheckout;
 exports.cancellationComment = require_stripe_mapper.cancellationComment;
 exports.cancellationDetailsSchema = require_stripe_schema.cancellationDetailsSchema;
 exports.createCheckoutSessionSchema = require_stripe_schema.createCheckoutSessionSchema;
+exports.createPlanChange = require_stripe_plan_change.createPlanChange;
+exports.defineStripeConfig = require_stripe_config.defineStripeConfig;
 exports.expanded = require_stripe_expandable.expanded;
 exports.getBeginCheckoutProperties = require_stripe_mapper.getBeginCheckoutProperties;
 exports.getPendingCheckouts = require_stripe_pending_checkout.getPendingCheckouts;

package/dist/stripe/index.d.cts

@@ -1,5 +1,5 @@
 import { CancellationDetails } from "../subscription/index.cjs";
-import { PriceId, StripeConfig, StripeMode } from "./config.cjs";
+import { PlanComparison, PriceId, StripeConfig, StripeMode, defineStripeConfig } from "./config.cjs";
 import { CardFailure, DECLINE_REASONS, Decline, DeclineReason, mapDecline } from "./decline.cjs";
 import { expanded, idOf } from "./expandable.cjs";
 import { StripeEventHandler } from "./handler.cjs";
@@ -9,6 +9,7 @@ import { DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, hasDelayedNotification } fro
 import { StripeThinEventHandler, StripeThinEventNotificationOf, StripeThinEventType } from "./thin-handler.cjs";
 import { AllowedOrigins, CreateCheckoutSessionDTO, CreateCheckoutSessionSchemaOptions, cancellationDetailsSchema, createCheckoutSessionSchema, returnUrlSchema } from "./schema.cjs";
 import { METADATA_KEYS } from "./metadata.cjs";
+import { PLAN_CHANGE_ERROR_REASONS, PlanChange, PlanChangeError, PlanChangeErrorReason, PlanChangeOptions, PlanChangePreview, PlanChangeResult, PlanChangeTiming, PlanSummary, ScheduledPlanChange, createPlanChange } from "./plan-change.cjs";
 import { addPendingCheckout, getPendingCheckouts, removePendingCheckout } from "./pending-checkout.cjs";
 import { Stripe } from "stripe";
-export { type AllowedOrigins, type BeginCheckoutProperties, type CancellationDetails, type CardFailure, type CheckoutSession, type CreateCheckoutSessionDTO, type CreateCheckoutSessionSchemaOptions, DECLINE_REASONS, DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, type Decline, type DeclineReason, type LineItem, METADATA_KEYS, type Money, type PaymentStatus, type Price, type PriceId, type ProductPrice, type PurchaseProperties, type Stripe, StripeConfig, StripeEventHandler, type StripeMode, type StripeSubscriptionState, StripeThinEventHandler, type StripeThinEventNotificationOf, type StripeThinEventType, addPendingCheckout, cancellationComment, cancellationDetailsSchema, createCheckoutSessionSchema, expanded, getBeginCheckoutProperties, getPendingCheckouts, getPurchaseProperties, hasDelayedNotification, idOf, mapCancellationDetails, mapCharge, mapCheckoutSession, mapDecline, mapDisputeStatus, mapInvoice, mapLineItem, mapListPrice, mapPaymentIntent, mapPaymentType, mapPrice, mapRefundStatus, mapSubscription, mapSubscriptionStatus, mapTime, minorUnits, money, price, removePendingCheckout, returnUrlSchema };
+export { type AllowedOrigins, type BeginCheckoutProperties, type CancellationDetails, type CardFailure, type CheckoutSession, type CreateCheckoutSessionDTO, type CreateCheckoutSessionSchemaOptions, DECLINE_REASONS, DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, type Decline, type DeclineReason, type LineItem, METADATA_KEYS, type Money, PLAN_CHANGE_ERROR_REASONS, type PaymentStatus, type PlanChange, PlanChangeError, type PlanChangeErrorReason, type PlanChangeOptions, type PlanChangePreview, type PlanChangeResult, type PlanChangeTiming, type PlanComparison, type PlanSummary, type Price, type PriceId, type ProductPrice, type PurchaseProperties, type ScheduledPlanChange, type Stripe, StripeConfig, StripeEventHandler, type StripeMode, type StripeSubscriptionState, StripeThinEventHandler, type StripeThinEventNotificationOf, type StripeThinEventType, addPendingCheckout, cancellationComment, cancellationDetailsSchema, createCheckoutSessionSchema, createPlanChange, defineStripeConfig, expanded, getBeginCheckoutProperties, getPendingCheckouts, getPurchaseProperties, hasDelayedNotification, idOf, mapCancellationDetails, mapCharge, mapCheckoutSession, mapDecline, mapDisputeStatus, mapInvoice, mapLineItem, mapListPrice, mapPaymentIntent, mapPaymentType, mapPrice, mapRefundStatus, mapSubscription, mapSubscriptionStatus, mapTime, minorUnits, money, price, removePendingCheckout, returnUrlSchema };

package/dist/stripe/index.d.mts

@@ -1,5 +1,5 @@
 import { CancellationDetails } from "../subscription/index.mjs";
-import { PriceId, StripeConfig, StripeMode } from "./config.mjs";
+import { PlanComparison, PriceId, StripeConfig, StripeMode, defineStripeConfig } from "./config.mjs";
 import { CardFailure, DECLINE_REASONS, Decline, DeclineReason, mapDecline } from "./decline.mjs";
 import { expanded, idOf } from "./expandable.mjs";
 import { StripeEventHandler } from "./handler.mjs";
@@ -9,6 +9,7 @@ import { DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, hasDelayedNotification } fro
 import { StripeThinEventHandler, StripeThinEventNotificationOf, StripeThinEventType } from "./thin-handler.mjs";
 import { AllowedOrigins, CreateCheckoutSessionDTO, CreateCheckoutSessionSchemaOptions, cancellationDetailsSchema, createCheckoutSessionSchema, returnUrlSchema } from "./schema.mjs";
 import { METADATA_KEYS } from "./metadata.mjs";
+import { PLAN_CHANGE_ERROR_REASONS, PlanChange, PlanChangeError, PlanChangeErrorReason, PlanChangeOptions, PlanChangePreview, PlanChangeResult, PlanChangeTiming, PlanSummary, ScheduledPlanChange, createPlanChange } from "./plan-change.mjs";
 import { addPendingCheckout, getPendingCheckouts, removePendingCheckout } from "./pending-checkout.mjs";
 import { Stripe } from "stripe";
-export { type AllowedOrigins, type BeginCheckoutProperties, type CancellationDetails, type CardFailure, type CheckoutSession, type CreateCheckoutSessionDTO, type CreateCheckoutSessionSchemaOptions, DECLINE_REASONS, DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, type Decline, type DeclineReason, type LineItem, METADATA_KEYS, type Money, type PaymentStatus, type Price, type PriceId, type ProductPrice, type PurchaseProperties, type Stripe, StripeConfig, StripeEventHandler, type StripeMode, type StripeSubscriptionState, StripeThinEventHandler, type StripeThinEventNotificationOf, type StripeThinEventType, addPendingCheckout, cancellationComment, cancellationDetailsSchema, createCheckoutSessionSchema, expanded, getBeginCheckoutProperties, getPendingCheckouts, getPurchaseProperties, hasDelayedNotification, idOf, mapCancellationDetails, mapCharge, mapCheckoutSession, mapDecline, mapDisputeStatus, mapInvoice, mapLineItem, mapListPrice, mapPaymentIntent, mapPaymentType, mapPrice, mapRefundStatus, mapSubscription, mapSubscriptionStatus, mapTime, minorUnits, money, price, removePendingCheckout, returnUrlSchema };
+export { type AllowedOrigins, type BeginCheckoutProperties, type CancellationDetails, type CardFailure, type CheckoutSession, type CreateCheckoutSessionDTO, type CreateCheckoutSessionSchemaOptions, DECLINE_REASONS, DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, type Decline, type DeclineReason, type LineItem, METADATA_KEYS, type Money, PLAN_CHANGE_ERROR_REASONS, type PaymentStatus, type PlanChange, PlanChangeError, type PlanChangeErrorReason, type PlanChangeOptions, type PlanChangePreview, type PlanChangeResult, type PlanChangeTiming, type PlanComparison, type PlanSummary, type Price, type PriceId, type ProductPrice, type PurchaseProperties, type ScheduledPlanChange, type Stripe, StripeConfig, StripeEventHandler, type StripeMode, type StripeSubscriptionState, StripeThinEventHandler, type StripeThinEventNotificationOf, type StripeThinEventType, addPendingCheckout, cancellationComment, cancellationDetailsSchema, createCheckoutSessionSchema, createPlanChange, defineStripeConfig, expanded, getBeginCheckoutProperties, getPendingCheckouts, getPurchaseProperties, hasDelayedNotification, idOf, mapCancellationDetails, mapCharge, mapCheckoutSession, mapDecline, mapDisputeStatus, mapInvoice, mapLineItem, mapListPrice, mapPaymentIntent, mapPaymentType, mapPrice, mapRefundStatus, mapSubscription, mapSubscriptionStatus, mapTime, minorUnits, money, price, removePendingCheckout, returnUrlSchema };

package/dist/stripe/index.mjs

@@ -1,4 +1,4 @@
-import { StripeConfig } from "./config.mjs";
+import { StripeConfig, defineStripeConfig } from "./config.mjs";
 import { DECLINE_REASONS, mapDecline } from "./decline.mjs";
 import { expanded, idOf } from "./expandable.mjs";
 import { StripeEventHandler } from "./handler.mjs";
@@ -8,5 +8,6 @@ import { DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, hasDelayedNotification } fro
 import { StripeThinEventHandler } from "./thin-handler.mjs";
 import { cancellationDetailsSchema, createCheckoutSessionSchema, returnUrlSchema } from "./schema.mjs";
 import { METADATA_KEYS } from "./metadata.mjs";
+import { PLAN_CHANGE_ERROR_REASONS, PlanChangeError, createPlanChange } from "./plan-change.mjs";
 import { addPendingCheckout, getPendingCheckouts, removePendingCheckout } from "./pending-checkout.mjs";
-export { DECLINE_REASONS, DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, METADATA_KEYS, StripeConfig, StripeEventHandler, StripeThinEventHandler, addPendingCheckout, cancellationComment, cancellationDetailsSchema, createCheckoutSessionSchema, expanded, getBeginCheckoutProperties, getPendingCheckouts, getPurchaseProperties, hasDelayedNotification, idOf, mapCancellationDetails, mapCharge, mapCheckoutSession, mapDecline, mapDisputeStatus, mapInvoice, mapLineItem, mapListPrice, mapPaymentIntent, mapPaymentType, mapPrice, mapRefundStatus, mapSubscription, mapSubscriptionStatus, mapTime, minorUnits, money, price, removePendingCheckout, returnUrlSchema };
+export { DECLINE_REASONS, DELAYED_NOTIFICATION_PAYMENT_METHOD_TYPES, METADATA_KEYS, PLAN_CHANGE_ERROR_REASONS, PlanChangeError, StripeConfig, StripeEventHandler, StripeThinEventHandler, addPendingCheckout, cancellationComment, cancellationDetailsSchema, createCheckoutSessionSchema, createPlanChange, defineStripeConfig, expanded, getBeginCheckoutProperties, getPendingCheckouts, getPurchaseProperties, hasDelayedNotification, idOf, mapCancellationDetails, mapCharge, mapCheckoutSession, mapDecline, mapDisputeStatus, mapInvoice, mapLineItem, mapListPrice, mapPaymentIntent, mapPaymentType, mapPrice, mapRefundStatus, mapSubscription, mapSubscriptionStatus, mapTime, minorUnits, money, price, removePendingCheckout, returnUrlSchema };

package/dist/stripe/plan-change.cjs

@@ -0,0 +1,400 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_stripe_decline = require("./decline.cjs");
+const require_stripe_expandable = require("./expandable.cjs");
+const require_stripe_mapper = require("./mapper.cjs");
+const require_stripe_payment_method = require("./payment-method.cjs");
+const require_stripe_metadata = require("./metadata.cjs");
+//#region src/stripe/plan-change.ts
+/**
+* Why a change was refused:
+* - NOT_A_SUBSCRIPTION: the target product is not a subscription in the config.
+* - ALREADY_CANCELED: the subscription has ended.
+* - NOT_SWITCHABLE: past due, unpaid, paused, incomplete or trialing; the fix is the payment
+*   method, not another charge, and what a switch mid-trial should do is the app's to decide.
+* - CANCEL_SCHEDULED: set to cancel at the period end; reactivate first.
+* - CHANGE_PENDING: an earlier immediate change still waits on its payment; only the same target
+*   may be retried.
+* - UNCHANGED: already on the target product.
+* - REQUIRES_INSTANT_METHOD: an immediate change would be paid by a bank debit
+*   (`hasDelayedNotification`); `paymentMethodType` names it.
+* - DECLINED: the card was refused; `decline` says why.
+* - CONFLICT: a concurrent change on the same snapshot was applied instead.
+* - MISCONFIGURED: the subscription or config is not what a change needs (no item, no product
+*   metadata, a price without a flat amount, a pending invoice without a payment intent).
+*/
+const PLAN_CHANGE_ERROR_REASONS = [
+	"NOT_A_SUBSCRIPTION",
+	"ALREADY_CANCELED",
+	"NOT_SWITCHABLE",
+	"CANCEL_SCHEDULED",
+	"CHANGE_PENDING",
+	"UNCHANGED",
+	"REQUIRES_INSTANT_METHOD",
+	"DECLINED",
+	"CONFLICT",
+	"MISCONFIGURED"
+];
+/** A refused change. The app turns `reason` (and `decline`) into its own error response. */
+var PlanChangeError = class extends Error {
+	reason;
+	decline;
+	paymentMethodType;
+	constructor(reason, message, extra = {}) {
+		super(message);
+		this.name = "PlanChangeError";
+		this.reason = reason;
+		this.decline = extra.decline ?? null;
+		this.paymentMethodType = extra.paymentMethodType ?? null;
+	}
+};
+const DEFAULT_TIMING = {
+	upgrade: "immediate",
+	downgrade: "period_end",
+	longer: "period_end",
+	shorter: "period_end"
+};
+/** stripe-node's error classes, matched by their `type` so this module needs no runtime import. */
+function stripeErrorType(error) {
+	if (typeof error !== "object" || error === null || !("type" in error)) return null;
+	return typeof error.type === "string" ? error.type : null;
+}
+const now = () => (/* @__PURE__ */ new Date()).toISOString();
+function createPlanChange(options) {
+	const { stripe, config, sync } = options;
+	const timing = {
+		...DEFAULT_TIMING,
+		...options.timing
+	};
+	async function planSummary(productId) {
+		const price = await stripe.prices.retrieve(config.getPriceId(productId));
+		if (price.unit_amount === null) throw new PlanChangeError("MISCONFIGURED", `Price ${price.id} has no amount`);
+		return {
+			productId,
+			plan: config.getPlan(productId),
+			billingPeriod: config.getBillingPeriod(productId),
+			price: require_stripe_mapper.money(price.unit_amount, price.currency),
+			credits: config.getCreditAmount(productId)
+		};
+	}
+	/**
+	* Whether a pending update moves the subscription to `productId`: its one item carries the price
+	* an immediate change sets for that product. Anything else counts as a different target.
+	*/
+	function pendingUpdateTargets(pending, productId) {
+		const items = pending.subscription_items ?? [];
+		return (items.length === 1 ? items[0] : void 0)?.price.id === config.getPriceId(productId);
+	}
+	/**
+	* The payment method an invoice on this subscription is charged to: its own default when it has
+	* one (Checkout pins the card it collected), else the customer's invoice default. Retrieved whole
+	* because an immediate change needs its `type`.
+	*/
+	async function chargedPaymentMethod(sub) {
+		const own = sub.default_payment_method;
+		if (own) return typeof own === "string" ? stripe.paymentMethods.retrieve(own) : own;
+		const customer = await stripe.customers.retrieve(require_stripe_expandable.idOf(sub.customer), { expand: ["invoice_settings.default_payment_method"] });
+		if (customer.deleted) return null;
+		const preferred = customer.invoice_settings.default_payment_method;
+		if (!preferred) return null;
+		return typeof preferred === "string" ? stripe.paymentMethods.retrieve(preferred) : preferred;
+	}
+	/** The subscription plus the checks every change starts with. */
+	async function subscriptionForChange(stripeSubscriptionId, productId) {
+		if (!config.isSubscription(productId)) throw new PlanChangeError("NOT_A_SUBSCRIPTION", `Not a subscription product: ${productId}`);
+		const sub = await stripe.subscriptions.retrieve(stripeSubscriptionId, { expand: ["schedule"] });
+		if (sub.status === "canceled") throw new PlanChangeError("ALREADY_CANCELED", "Subscription already canceled");
+		if (sub.status !== "active") throw new PlanChangeError("NOT_SWITCHABLE", `Subscription is ${sub.status}`);
+		if (sub.cancel_at_period_end || sub.cancel_at !== null) throw new PlanChangeError("CANCEL_SCHEDULED", "Subscription is scheduled to cancel");
+		const resumesPendingUpdate = sub.pending_update ? pendingUpdateTargets(sub.pending_update, productId) : false;
+		if (sub.pending_update && !resumesPendingUpdate) throw new PlanChangeError("CHANGE_PENDING", `Subscription has a pending update until ${require_stripe_mapper.mapTime(sub.pending_update.expires_at)}`);
+		const currentProductId = sub.metadata[require_stripe_metadata.METADATA_KEYS.PRODUCT_ID];
+		if (!currentProductId || !config.isSubscription(currentProductId)) throw new PlanChangeError("MISCONFIGURED", `Subscription ${sub.id} names no known product`);
+		const comparison = config.comparePlans(currentProductId, productId);
+		if (comparison === "same") throw new PlanChangeError("UNCHANGED", "Already on this plan");
+		const item = sub.items.data.at(0);
+		if (!item) throw new PlanChangeError("MISCONFIGURED", `Subscription ${sub.id} has no items`);
+		const immediate = timing[comparison] === "immediate";
+		const base = {
+			sub,
+			item,
+			currentProductId,
+			comparison,
+			immediate,
+			resumesPendingUpdate
+		};
+		if (!immediate) return {
+			...base,
+			paymentMethodId: null
+		};
+		const paymentMethod = await chargedPaymentMethod(sub);
+		if (paymentMethod && require_stripe_payment_method.hasDelayedNotification(paymentMethod.type)) throw new PlanChangeError("REQUIRES_INSTANT_METHOD", `Immediate plan change cannot be paid by ${paymentMethod.type}`, { paymentMethodType: paymentMethod.type });
+		return {
+			...base,
+			paymentMethodId: paymentMethod?.id ?? null
+		};
+	}
+	/**
+	* The parameters of an immediate change, shared by the preview and the real update: the new plan
+	* is charged in full today, the unused rest of the current period is credited on the same
+	* invoice, and the billing cycle restarts now (Apple's upgrade, Play's `CHARGE_FULL_PRICE`), so
+	* "due today" is the new price minus that credit whatever the intervals involved.
+	*/
+	function immediateChangeParams(item, productId) {
+		return {
+			items: [{
+				id: item.id,
+				price: config.getPriceId(productId)
+			}],
+			proration_behavior: "always_invoice",
+			billing_cycle_anchor: { type: "now" }
+		};
+	}
+	async function settleParkedUpdate(sub) {
+		const invoiceId = require_stripe_expandable.idOf(sub.latest_invoice);
+		if (!invoiceId) throw new PlanChangeError("MISCONFIGURED", `Pending update on ${sub.id} has no invoice`);
+		const invoice = await stripe.invoices.retrieve(invoiceId, { expand: ["payments.data.payment.payment_intent"] });
+		const intent = invoice.payments?.data.at(0)?.payment.payment_intent;
+		if (!intent || typeof intent === "string" || !intent.client_secret) throw new PlanChangeError("MISCONFIGURED", `Pending invoice ${invoiceId} has no payment intent`);
+		switch (intent.status) {
+			case "requires_action": return {
+				state: "challenge",
+				result: {
+					effect: "requires_action",
+					effectiveAt: now(),
+					clientSecret: intent.client_secret
+				}
+			};
+			case "succeeded": return { state: "paid" };
+			case "requires_payment_method":
+				if (invoice.status !== "void") await stripe.invoices.voidInvoice(invoiceId);
+				return {
+					state: "declined",
+					failure: intent.last_payment_error
+				};
+			default: throw new PlanChangeError("MISCONFIGURED", `Pending invoice ${invoiceId} has its payment in state ${intent.status}`);
+		}
+	}
+	function declined(failure) {
+		const decline = require_stripe_decline.mapDecline(failure);
+		return new PlanChangeError("DECLINED", decline.message ?? "Payment declined", { decline });
+	}
+	/**
+	* Mirror the subscription after an attempt that already failed. The original error is what the
+	* caller needs (a decline, a conflict); a sync failure on top of it is only logged, and the next
+	* webhook or sync puts the row right.
+	*/
+	async function syncAfterFailure(stripeSubscriptionId) {
+		try {
+			await sync(stripeSubscriptionId);
+		} catch (error) {
+			console.error(`Sync of ${stripeSubscriptionId} after a failed plan change failed:`, error);
+		}
+	}
+	const applied = () => ({
+		effect: "immediate",
+		effectiveAt: now(),
+		clientSecret: null
+	});
+	async function readScheduled(sub) {
+		const pending = pendingPhase(sub);
+		if (!pending) return null;
+		const { schedule, next, productId } = pending;
+		if (!config.isSubscription(productId)) {
+			console.error(`Schedule ${schedule.id} next phase names unknown product ${productId}`);
+			return null;
+		}
+		const priceId = require_stripe_expandable.idOf(next.items.at(0)?.price);
+		if (!priceId) {
+			console.error(`Schedule ${schedule.id} next phase has no price`);
+			return null;
+		}
+		const price = await stripe.prices.retrieve(priceId);
+		if (price.unit_amount === null) {
+			console.error(`Schedule ${schedule.id} next phase price ${priceId} has no unit amount`);
+			return null;
+		}
+		return {
+			productId,
+			plan: config.getPlan(productId),
+			billingPeriod: config.getBillingPeriod(productId),
+			price: require_stripe_mapper.money(price.unit_amount, price.currency),
+			effectiveAt: require_stripe_mapper.mapTime(next.start_date)
+		};
+	}
+	async function preview(stripeSubscriptionId, productId) {
+		const { sub, item, currentProductId, comparison, immediate } = await subscriptionForChange(stripeSubscriptionId, productId);
+		const [current, target] = await Promise.all([planSummary(currentProductId), planSummary(productId)]);
+		if (!immediate) return {
+			comparison,
+			effect: "scheduled",
+			current,
+			target,
+			effectiveAt: require_stripe_mapper.mapTime(item.current_period_end),
+			charge: null
+		};
+		const invoice = await stripe.invoices.createPreview({
+			subscription: sub.id,
+			subscription_details: immediateChangeParams(item, productId)
+		});
+		let creditBack = 0;
+		let newPlan = 0;
+		let nextBillingAt = invoice.period_end;
+		for (const line of invoice.lines.data) if (line.parent?.subscription_item_details?.proration) creditBack -= line.amount;
+		else {
+			newPlan += line.amount;
+			nextBillingAt = Math.max(nextBillingAt, line.period.end);
+		}
+		const units = require_stripe_mapper.minorUnits(invoice.currency);
+		const balanceApplied = Math.min(Math.max(0, -invoice.starting_balance), Math.max(0, newPlan - creditBack));
+		return {
+			comparison,
+			effect: "immediate",
+			current,
+			target,
+			effectiveAt: now(),
+			charge: {
+				newPlan: newPlan / units,
+				creditBack: creditBack / units,
+				dueToday: invoice.amount_due / units,
+				balanceApplied: balanceApplied / units,
+				accountCredit: Math.max(0, creditBack - newPlan) / units,
+				currency: invoice.currency,
+				nextBillingAt: require_stripe_mapper.mapTime(nextBillingAt)
+			}
+		};
+	}
+	async function applyNow(sub, item, currentProductId, productId, paymentMethodId) {
+		const scheduleId = require_stripe_expandable.idOf(sub.schedule);
+		if (scheduleId) await stripe.subscriptionSchedules.release(scheduleId, {}, { idempotencyKey: `release:${scheduleId}` });
+		const idempotencyKey = [
+			"plan",
+			sub.id,
+			currentProductId,
+			productId,
+			item.current_period_start,
+			require_stripe_expandable.idOf(sub.latest_invoice) ?? "none",
+			paymentMethodId ?? "none"
+		].join(":");
+		let updated;
+		try {
+			updated = await stripe.subscriptions.update(sub.id, {
+				...immediateChangeParams(item, productId),
+				metadata: {
+					...sub.metadata,
+					[require_stripe_metadata.METADATA_KEYS.PRODUCT_ID]: productId
+				},
+				payment_behavior: "pending_if_incomplete"
+			}, { idempotencyKey });
+		} catch (error) {
+			await syncAfterFailure(sub.id);
+			if (stripeErrorType(error) === "StripeCardError") throw declined(error);
+			if (stripeErrorType(error) === "StripeIdempotencyError") throw new PlanChangeError("CONFLICT", "Plan change conflicts with a concurrent one");
+			throw error;
+		}
+		await sync(sub.id);
+		if (!updated.pending_update) return applied();
+		const parked = await settleParkedUpdate(updated);
+		if (parked.state === "challenge") return parked.result;
+		if (parked.state === "paid") {
+			await sync(sub.id);
+			return applied();
+		}
+		await syncAfterFailure(sub.id);
+		throw declined(parked.failure);
+	}
+	async function applyAtPeriodEnd(sub, item, productId) {
+		const targetPrice = await stripe.prices.retrieve(config.getPriceId(productId));
+		if (!targetPrice.recurring) throw new PlanChangeError("MISCONFIGURED", `Price ${targetPrice.id} is not recurring`);
+		const schedule = sub.schedule && typeof sub.schedule !== "string" ? sub.schedule : await stripe.subscriptionSchedules.create({ from_subscription: sub.id });
+		const current = schedule.current_phase;
+		const phase = schedule.phases.find((p) => p.start_date === current?.start_date);
+		if (!current || !phase) throw new PlanChangeError("MISCONFIGURED", `Schedule ${schedule.id} has no current phase`);
+		const discounts = sub.discounts.map((d) => ({ discount: require_stripe_expandable.idOf(d) }));
+		await stripe.subscriptionSchedules.update(schedule.id, {
+			end_behavior: "release",
+			phases: [{
+				start_date: current.start_date,
+				end_date: item.current_period_end,
+				items: [{
+					price: item.price.id,
+					quantity: item.quantity
+				}],
+				metadata: sub.metadata,
+				discounts,
+				proration_behavior: "none"
+			}, {
+				items: [{
+					price: targetPrice.id,
+					quantity: item.quantity
+				}],
+				duration: {
+					interval: targetPrice.recurring.interval,
+					interval_count: targetPrice.recurring.interval_count
+				},
+				metadata: {
+					...sub.metadata,
+					[require_stripe_metadata.METADATA_KEYS.PRODUCT_ID]: productId
+				},
+				discounts,
+				proration_behavior: "none"
+			}]
+		});
+		await sync(sub.id);
+		return {
+			effect: "scheduled",
+			effectiveAt: require_stripe_mapper.mapTime(item.current_period_end),
+			clientSecret: null
+		};
+	}
+	async function apply(stripeSubscriptionId, productId) {
+		const { sub, item, currentProductId, immediate, resumesPendingUpdate, paymentMethodId } = await subscriptionForChange(stripeSubscriptionId, productId);
+		if (resumesPendingUpdate) {
+			const parked = await settleParkedUpdate(sub);
+			if (parked.state === "challenge") return parked.result;
+			if (parked.state === "paid") {
+				await sync(sub.id);
+				return applied();
+			}
+		}
+		if (immediate) return applyNow(sub, item, currentProductId, productId, paymentMethodId);
+		return applyAtPeriodEnd(sub, item, productId);
+	}
+	/**
+	* The schedule's next phase when it switches the subscription to another product, whatever that
+	* product is: also one the config no longer knows, or a price the dashboard set without a flat
+	* amount, which `readScheduled` does not show but "keep current plan" must still be able to drop.
+	*/
+	function pendingPhase(sub) {
+		const schedule = require_stripe_expandable.expanded(sub.schedule, `Schedule of subscription ${sub.id}`);
+		if (!schedule) return null;
+		if (schedule.status !== "active" && schedule.status !== "not_started") return null;
+		const current = schedule.current_phase;
+		if (!current) return null;
+		const next = schedule.phases.find((phase) => phase.start_date >= current.end_date);
+		const productId = next?.metadata?.[require_stripe_metadata.METADATA_KEYS.PRODUCT_ID];
+		if (!next || !productId || productId === sub.metadata[require_stripe_metadata.METADATA_KEYS.PRODUCT_ID]) return null;
+		return {
+			schedule,
+			next,
+			productId
+		};
+	}
+	async function cancelScheduled(stripeSubscriptionId) {
+		const sub = await stripe.subscriptions.retrieve(stripeSubscriptionId, { expand: ["schedule"] });
+		const pending = pendingPhase(sub);
+		if (pending) await stripe.subscriptionSchedules.release(pending.schedule.id);
+		await sync(sub.id);
+	}
+	return {
+		preview,
+		apply,
+		cancelScheduled,
+		readScheduled
+	};
+}
+//#endregion
+exports.PLAN_CHANGE_ERROR_REASONS = PLAN_CHANGE_ERROR_REASONS;
+exports.PlanChangeError = PlanChangeError;
+exports.createPlanChange = createPlanChange;
+
+//# sourceMappingURL=plan-change.cjs.map