@fonderie/billing 5.0.2 → 5.3.0

package/dist/{index-CKzM1gyJ.d.ts → index-CBhthuMn.d.ts}

@@ -9,7 +9,11 @@ interface IBillingEvent {
 interface INormalizedSubscription {
     subscriberType: SubscriberType;
     subscriberId: string;
+    /** Plan name from the price nickname (legacy fallback; prefer resolving via priceLookupKey/priceId). */
     plan: string;
+    /** The subscription item's price lookup_key + id — for config-based plan attribution (§16.3). */
+    priceLookupKey: string | null;
+    priceId: string | null;
     status: string;
     providerCustomerId: string;
     providerSubscriptionId: string;
@@ -19,6 +23,16 @@ interface INormalizedSubscription {
     trialEndsAt: Date | null;
     interval: 'month' | 'year';
 }
+interface IResolvedPrice {
+    priceId: string;
+    lookupKey: string | null;
+    unitAmount: number;
+    currency: string;
+    interval: 'month' | 'year';
+    nickname: string | null;
+    productId: string;
+    active: boolean;
+}
 interface IBillingProvider {
     name: string;
     createCustomer(opts: {
@@ -40,6 +54,16 @@ interface IBillingProvider {
     }): Promise<{
         url: string;
     }>;
+    resolvePriceById(priceId: string): Promise<IResolvedPrice | null>;
+    resolvePricesByLookupKey(lookupKeys: string[]): Promise<Map<string, IResolvedPrice>>;
+    updateSubscription(opts: {
+        subscriptionId: string;
+        priceId: string;
+    }): Promise<{
+        status: string;
+        currentPeriodStart: Date | null;
+        currentPeriodEnd: Date | null;
+    }>;
     createPortalSession(opts: {
         customerId: string;
         returnUrl: string;
@@ -59,8 +83,30 @@ interface ICounterBackend {
 }
 
 interface IBillingPlanPrice {
-    amount: number;
+    /** Stable Stripe Price lookup_key, e.g. "pro_monthly". Preferred reference. */
+    lookupKey?: string;
+    /** Stripe price id. Used for hydration and as a lookup_key fallback. */
     priceId?: string;
+    /**
+     * @deprecated Display amount in cents. When pricing hydration is on and the
+     * price resolves from Stripe, the live amount wins; this is the fallback only.
+     */
+    amount?: number;
+}
+/**
+ * Read-through pricing: amount/currency come from Stripe (source of truth) rather
+ * than the duplicated `amount` above. Gated by `hydration` (kill-switch, §16.9).
+ * See packages/billing/docs/pricing-hydration.md.
+ */
+interface IBillingPricingConfig {
+    /** Kill-switch. When false (default), use the deprecated hardcoded amount/USD path. */
+    hydration?: boolean;
+    /** Fresh-cache TTL. Default 300_000 (5m). */
+    cacheTtlMs?: number;
+    /** Serve last-cached price on a transient resolution miss (lookup_key transfer). Default 3_600_000 (1h). */
+    transferGraceMs?: number;
+    /** Max age to serve stale price during a Stripe outage before giving up. Default 86_400_000 (24h). */
+    maxStaleMs?: number;
 }
 interface IBillingPlanDefaults {
     warnAt?: number;
@@ -92,6 +138,7 @@ interface IBillingConfig {
         backend?: RateLimitBackendConfig;
     };
     notifications?: IBillingNotificationsConfig;
+    pricing?: IBillingPricingConfig;
 }
 declare const MESSAGE_KEYS: {
     readonly limitWarning: "billing.limit-warning";
@@ -105,4 +152,4 @@ declare function requirePlan(plans: string | string[], store: IStoreAdapter, ctx
 
 declare function withBilling(store: IStoreAdapter, config: IBillingConfig, backend: ICounterBackend): Middleware;
 
-export { type BillingMessageKey as B, type IBillingConfig as I, MESSAGE_KEYS as M, type RateLimitBackendConfig as R, type IBillingProvider as a, type IBillingEvent as b, type ICounterBackend as c, type IBillingPlan as d, type IBillingNotificationsConfig as e, type IBillingPlanDefaults as f, requirePlan as r, withBilling as w };
+export { type BillingMessageKey as B, type IBillingConfig as I, MESSAGE_KEYS as M, type RateLimitBackendConfig as R, type IBillingProvider as a, type IResolvedPrice as b, type IBillingEvent as c, type ICounterBackend as d, type IBillingPlan as e, type IBillingNotificationsConfig as f, type IBillingPlanDefaults as g, type IBillingPlanPrice as h, type IBillingPricingConfig as i, requirePlan as r, withBilling as w };

package/dist/{index-Ce_BMy1V.d.cts → index-CS1QagwE.d.cts}

@@ -9,7 +9,11 @@ interface IBillingEvent {
 interface INormalizedSubscription {
     subscriberType: SubscriberType;
     subscriberId: string;
+    /** Plan name from the price nickname (legacy fallback; prefer resolving via priceLookupKey/priceId). */
     plan: string;
+    /** The subscription item's price lookup_key + id — for config-based plan attribution (§16.3). */
+    priceLookupKey: string | null;
+    priceId: string | null;
     status: string;
     providerCustomerId: string;
     providerSubscriptionId: string;
@@ -19,6 +23,16 @@ interface INormalizedSubscription {
     trialEndsAt: Date | null;
     interval: 'month' | 'year';
 }
+interface IResolvedPrice {
+    priceId: string;
+    lookupKey: string | null;
+    unitAmount: number;
+    currency: string;
+    interval: 'month' | 'year';
+    nickname: string | null;
+    productId: string;
+    active: boolean;
+}
 interface IBillingProvider {
     name: string;
     createCustomer(opts: {
@@ -40,6 +54,16 @@ interface IBillingProvider {
     }): Promise<{
         url: string;
     }>;
+    resolvePriceById(priceId: string): Promise<IResolvedPrice | null>;
+    resolvePricesByLookupKey(lookupKeys: string[]): Promise<Map<string, IResolvedPrice>>;
+    updateSubscription(opts: {
+        subscriptionId: string;
+        priceId: string;
+    }): Promise<{
+        status: string;
+        currentPeriodStart: Date | null;
+        currentPeriodEnd: Date | null;
+    }>;
     createPortalSession(opts: {
         customerId: string;
         returnUrl: string;
@@ -59,8 +83,30 @@ interface ICounterBackend {
 }
 
 interface IBillingPlanPrice {
-    amount: number;
+    /** Stable Stripe Price lookup_key, e.g. "pro_monthly". Preferred reference. */
+    lookupKey?: string;
+    /** Stripe price id. Used for hydration and as a lookup_key fallback. */
     priceId?: string;
+    /**
+     * @deprecated Display amount in cents. When pricing hydration is on and the
+     * price resolves from Stripe, the live amount wins; this is the fallback only.
+     */
+    amount?: number;
+}
+/**
+ * Read-through pricing: amount/currency come from Stripe (source of truth) rather
+ * than the duplicated `amount` above. Gated by `hydration` (kill-switch, §16.9).
+ * See packages/billing/docs/pricing-hydration.md.
+ */
+interface IBillingPricingConfig {
+    /** Kill-switch. When false (default), use the deprecated hardcoded amount/USD path. */
+    hydration?: boolean;
+    /** Fresh-cache TTL. Default 300_000 (5m). */
+    cacheTtlMs?: number;
+    /** Serve last-cached price on a transient resolution miss (lookup_key transfer). Default 3_600_000 (1h). */
+    transferGraceMs?: number;
+    /** Max age to serve stale price during a Stripe outage before giving up. Default 86_400_000 (24h). */
+    maxStaleMs?: number;
 }
 interface IBillingPlanDefaults {
     warnAt?: number;
@@ -92,6 +138,7 @@ interface IBillingConfig {
         backend?: RateLimitBackendConfig;
     };
     notifications?: IBillingNotificationsConfig;
+    pricing?: IBillingPricingConfig;
 }
 declare const MESSAGE_KEYS: {
     readonly limitWarning: "billing.limit-warning";
@@ -105,4 +152,4 @@ declare function requirePlan(plans: string | string[], store: IStoreAdapter, ctx
 
 declare function withBilling(store: IStoreAdapter, config: IBillingConfig, backend: ICounterBackend): Middleware;
 
-export { type BillingMessageKey as B, type IBillingConfig as I, MESSAGE_KEYS as M, type RateLimitBackendConfig as R, type IBillingProvider as a, type IBillingEvent as b, type ICounterBackend as c, type IBillingPlan as d, type IBillingNotificationsConfig as e, type IBillingPlanDefaults as f, requirePlan as r, withBilling as w };
+export { type BillingMessageKey as B, type IBillingConfig as I, MESSAGE_KEYS as M, type RateLimitBackendConfig as R, type IBillingProvider as a, type IResolvedPrice as b, type IBillingEvent as c, type ICounterBackend as d, type IBillingPlan as e, type IBillingNotificationsConfig as f, type IBillingPlanDefaults as g, type IBillingPlanPrice as h, type IBillingPricingConfig as i, requirePlan as r, withBilling as w };

package/dist/index.cjs

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  BILLING_INTERVAL: () => BILLING_INTERVAL,
   BillingModule: () => BillingModule,
   DBCounterBackend: () => DBCounterBackend,
   MESSAGE_KEYS: () => MESSAGE_KEYS,
@@ -86,6 +87,54 @@ var recordUsageSchema = import_zod.z.object({
   quantity: import_zod.z.number().min(0).optional()
 });
 
+// src/services/price-cache.ts
+var PriceCache = class {
+  ttl;
+  grace;
+  maxStale;
+  byId = /* @__PURE__ */ new Map();
+  inflight = /* @__PURE__ */ new Map();
+  constructor(opts = {}) {
+    this.ttl = opts.ttlMs ?? 3e5;
+    this.grace = opts.graceMs ?? 36e5;
+    this.maxStale = opts.maxStaleMs ?? 864e5;
+  }
+  async byPriceId(priceId, provider) {
+    const now = Date.now();
+    const hit = this.byId.get(priceId);
+    if (hit && now - hit.at < this.ttl) return { price: hit.price, stale: false };
+    let fresh;
+    try {
+      fresh = await this.single(priceId, () => provider.resolvePriceById(priceId));
+    } catch {
+      if (hit && now - hit.at < this.maxStale) return { price: hit.price, stale: true };
+      return { price: null, stale: true };
+    }
+    if (fresh) {
+      this.byId.set(priceId, { price: fresh, at: now });
+      return { price: fresh, stale: false };
+    }
+    if (hit && now - hit.at < this.grace) return { price: hit.price, stale: true };
+    return { price: null, stale: true };
+  }
+  invalidate(priceId) {
+    if (priceId) this.byId.delete(priceId);
+    else this.byId.clear();
+  }
+  /** Warm the cache with prices already resolved elsewhere (e.g. boot guard). */
+  prime(prices) {
+    const now = Date.now();
+    for (const p of prices) this.byId.set(p.priceId, { price: p, at: now });
+  }
+  single(key, run) {
+    const existing = this.inflight.get(key);
+    if (existing) return existing;
+    const p = run().finally(() => this.inflight.delete(key));
+    this.inflight.set(key, p);
+    return p;
+  }
+};
+
 // src/controllers/plan.controller.ts
 var import_core = require("@fonderie/core");
 
@@ -96,6 +145,18 @@ function getPlans(config) {
 function getPlanByName(name, config) {
   return config.plans.find((p) => p.name.toLowerCase() === name.toLowerCase()) ?? null;
 }
+function resolvePlanNameByPrice(price, plans) {
+  const find = (pred) => plans.find((pl) => pred(pl.monthly) || pred(pl.yearly))?.name ?? null;
+  if (price.lookupKey) {
+    const m = find((p) => p?.lookupKey === price.lookupKey);
+    if (m) return m;
+  }
+  if (price.priceId) {
+    const m = find((p) => p?.priceId === price.priceId);
+    if (m) return m;
+  }
+  return null;
+}
 async function syncPlansToDB(config, store) {
   const plans = config.plans;
   if (plans.length === 0) return;
@@ -314,12 +375,41 @@ function toUsageRecordDTO(record) {
 }
 
 // src/controllers/plan.controller.ts
-function planController(store) {
+async function hydratePricing(dto, plan, config, cache) {
+  try {
+    let stale = false;
+    const resolve = async (priceId) => {
+      if (!priceId) return null;
+      const r = await cache.byPriceId(priceId, config.provider);
+      if (r.stale) stale = true;
+      return r.price;
+    };
+    const [m, y] = await Promise.all([resolve(plan.monthlyPriceId), resolve(plan.yearlyPriceId)]);
+    if (m && y && m.currency !== y.currency) {
+      throw new Error(
+        `[billing] plan "${plan.name}": monthly/yearly currency mismatch (${m.currency} vs ${y.currency})`
+      );
+    }
+    if (m) dto.pricing.monthly = m.unitAmount;
+    if (y) dto.pricing.yearly = y.unitAmount;
+    const currency = m?.currency ?? y?.currency;
+    if (currency) dto.pricing.currency = currency.toUpperCase();
+    if (stale) dto.pricingStale = true;
+  } catch (err) {
+    console.error(`[billing] pricing hydration failed for "${plan.name}":`, err.message);
+    dto.pricingStale = true;
+  }
+}
+function planController(store, config, cache) {
   const plans = new PlanModel(store);
+  const hydrate = config.pricing?.hydration === true;
   return {
     async list(_ctx) {
       const list = await plans.list();
       const dtos = list.map(toPlanDTO);
+      if (hydrate) {
+        await Promise.all(dtos.map((dto, i) => hydratePricing(dto, list[i], config, cache)));
+      }
       return (0, import_core.setApiResponse)(import_core.HTTP.OK, "PLAN_LIST", `Retrieved ${list.length} workspace plans`, {
         plans: dtos
       });
@@ -330,8 +420,10 @@ function planController(store) {
       if (!id) return (0, import_core.setApiResponse)(import_core.HTTP.BAD_REQUEST, "INVALID_PARAMETER", "Plan ID required");
       const plan = await plans.findById(id);
       if (!plan) return (0, import_core.setApiResponse)(import_core.HTTP.NOT_FOUND, "NOT_FOUND", "Plan not found");
+      const dto = toPlanDTO(plan);
+      if (hydrate) await hydratePricing(dto, plan, config, cache);
       return (0, import_core.setApiResponse)(import_core.HTTP.OK, "PLAN_FETCHED", "Plan retrieved successfully.", {
-        plan: toPlanDTO(plan)
+        plan: dto
       });
     },
     async create(ctx) {
@@ -588,6 +680,43 @@ function checkoutController(store, config) {
           `Plan ${planName} does not support ${interval} billing`
         );
       }
+      const current = await subscriptions.get(subscriber.type, subscriber.id);
+      const ACTIVE = ["active", "trialing", "past_due"];
+      if (current && ACTIVE.includes(current.status)) {
+        const currentTier = plans.findByNameInConfig(current.plan, config)?.tier ?? -1;
+        const targetTier = plan.tier ?? -1;
+        if (targetTier <= currentTier) {
+          return (0, import_core3.setApiResponse)(
+            import_core3.HTTP.UNPROCESSABLE,
+            "DOWNGRADE_NOT_ALLOWED",
+            `Cannot switch from ${current.plan} to a same-or-lower tier (${planName}) mid-cycle. Upgrades only.`
+          );
+        }
+        if (current.providerSubscriptionId) {
+          const res = await config.provider.updateSubscription({
+            subscriptionId: current.providerSubscriptionId,
+            priceId: pricing.priceId
+          });
+          const upsert = {
+            subscriberType: subscriber.type,
+            subscriberId: subscriber.id,
+            plan: planName,
+            interval,
+            status: res.status,
+            providerSubscriptionId: current.providerSubscriptionId
+          };
+          if (current.providerCustomerId) upsert.providerCustomerId = current.providerCustomerId;
+          if (res.currentPeriodStart) upsert.currentPeriodStart = res.currentPeriodStart;
+          if (res.currentPeriodEnd) upsert.currentPeriodEnd = res.currentPeriodEnd;
+          await subscriptions.upsert(upsert);
+          return (0, import_core3.setApiResponse)(
+            import_core3.HTTP.OK,
+            "SUBSCRIPTION_UPGRADED",
+            "Subscription upgraded; the prorated difference was charged.",
+            { upgraded: true, plan: planName }
+          );
+        }
+      }
       const { customerId } = await config.provider.createCustomer({
         email: ctx.user.email ?? "",
         subscriberType: subscriber.type,
@@ -727,7 +856,7 @@ function usageController(store) {
 
 // src/controllers/webhook.controller.ts
 var import_core5 = require("@fonderie/core");
-function webhookController(store, config) {
+function webhookController(store, config, priceCache) {
   const subscriptions = new SubscriptionModel(store);
   return {
     async handle(ctx) {
@@ -749,11 +878,15 @@ function webhookController(store, config) {
       } catch {
         return (0, import_core5.setApiResponse)(import_core5.HTTP.BAD_REQUEST, "INVALID_REQUEST", "Invalid webhook signature");
       }
+      if (priceCache && (event.type.startsWith("price.") || event.type.startsWith("product."))) {
+        priceCache.invalidate();
+      }
       if (event.subscription) {
+        const plan = event.type === "customer.subscription.deleted" ? event.subscription.plan : resolvePlanNameByPrice(event.subscription, config.plans) ?? event.subscription.plan;
         await subscriptions.upsert({
           subscriberType: event.subscription.subscriberType,
           subscriberId: event.subscription.subscriberId,
-          plan: event.subscription.plan,
+          plan,
           interval: event.subscription.interval,
           status: event.subscription.status,
           providerCustomerId: event.subscription.providerCustomerId,
@@ -771,11 +904,16 @@ function webhookController(store, config) {
 
 // src/routes.ts
 function buildBillingRoutes(store, config) {
-  const plan = planController(store);
+  const priceCache = new PriceCache({
+    ttlMs: config.pricing?.cacheTtlMs,
+    graceMs: config.pricing?.transferGraceMs,
+    maxStaleMs: config.pricing?.maxStaleMs
+  });
+  const plan = planController(store, config, priceCache);
   const subscription = subscriptionController(store);
   const checkout = checkoutController(store, config);
   const usage = usageController(store);
-  const webhook = webhookController(store, config);
+  const webhook = webhookController(store, config, priceCache);
   return [
     // Plans — public read-only
     ["GET", "/plans", plan.list],
@@ -998,6 +1136,9 @@ var BillingModule = class {
   }
 };
 
+// src/types.ts
+var BILLING_INTERVAL = { MONTH: "month", YEAR: "year" };
+
 // src/providers/stripe.ts
 var _client = null;
 async function getClient(secretKey) {
@@ -1018,6 +1159,8 @@ function normalizeSubscription(sub) {
     subscriberType: sub.metadata?.["subscriberType"] ?? "workspace",
     subscriberId: sub.metadata?.["subscriberId"] ?? "",
     plan: item?.price.nickname ?? "unknown",
+    priceLookupKey: item?.price.lookup_key ?? null,
+    priceId: item?.price.id ?? null,
     status: sub.status,
     providerCustomerId: sub.customer,
     providerSubscriptionId: sub.id,
@@ -1025,7 +1168,19 @@ function normalizeSubscription(sub) {
     currentPeriodEnd: periodEnd ? new Date(periodEnd * 1e3) : /* @__PURE__ */ new Date(),
     cancelAtPeriodEnd: sub.cancel_at_period_end,
     trialEndsAt: sub.trial_end ? new Date(sub.trial_end * 1e3) : null,
-    interval: item?.price.recurring?.interval === "year" ? "year" : "month"
+    interval: item?.price.recurring?.interval === BILLING_INTERVAL.YEAR ? BILLING_INTERVAL.YEAR : BILLING_INTERVAL.MONTH
+  };
+}
+function toResolvedPrice(p) {
+  return {
+    priceId: p.id,
+    lookupKey: p.lookup_key ?? null,
+    unitAmount: p.unit_amount ?? 0,
+    currency: p.currency,
+    interval: p.recurring?.interval === BILLING_INTERVAL.YEAR ? BILLING_INTERVAL.YEAR : BILLING_INTERVAL.MONTH,
+    nickname: p.nickname ?? null,
+    productId: typeof p.product === "string" ? p.product : p.product?.id ?? "",
+    active: p.active ?? true
   };
 }
 var StripeProvider = class {
@@ -1069,6 +1224,48 @@ var StripeProvider = class {
     });
     return { url: session.url ?? "" };
   }
+  async resolvePriceById(priceId) {
+    const stripe = await this.client();
+    try {
+      const p = await stripe.prices.retrieve(priceId, { expand: ["product"] });
+      return toResolvedPrice(p);
+    } catch {
+      return null;
+    }
+  }
+  async resolvePricesByLookupKey(lookupKeys) {
+    const out = /* @__PURE__ */ new Map();
+    if (lookupKeys.length === 0) return out;
+    const stripe = await this.client();
+    const res = await stripe.prices.list({
+      lookup_keys: lookupKeys,
+      active: true,
+      expand: ["data.product"],
+      limit: 100
+    });
+    for (const p of res.data) {
+      if (p.lookup_key) out.set(p.lookup_key, toResolvedPrice(p));
+    }
+    return out;
+  }
+  async updateSubscription(opts) {
+    const stripe = await this.client();
+    const sub = await stripe.subscriptions.retrieve(opts.subscriptionId);
+    const itemId = sub.items.data[0]?.id;
+    const updated = await stripe.subscriptions.update(opts.subscriptionId, {
+      items: [{ id: itemId, price: opts.priceId }],
+      proration_behavior: "always_invoice",
+      payment_behavior: "error_if_incomplete"
+    });
+    const item = updated.items?.data?.[0];
+    const cps = item?.current_period_start ?? updated.current_period_start;
+    const cpe = item?.current_period_end ?? updated.current_period_end;
+    return {
+      status: updated.status,
+      currentPeriodStart: cps ? new Date(cps * 1e3) : null,
+      currentPeriodEnd: cpe ? new Date(cpe * 1e3) : null
+    };
+  }
   async createPortalSession(opts) {
     const stripe = await this.client();
     const session = await stripe.billingPortal.sessions.create({
@@ -1183,6 +1380,7 @@ function requireFeature(key) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BILLING_INTERVAL,
   BillingModule,
   DBCounterBackend,
   MESSAGE_KEYS,