@fonderie/billing 5.3.0 → 5.3.1

package/brain/signatures.md

@@ -16,6 +16,9 @@ new StripeProvider(secretKey: string, webhookSecret?: string | undefined): Strip
   .name: "stripe"
   .createCustomer(opts: { email: string; subscriberType: SubscriberType; subscriberId: string; userId: string; }): Promise<{ customerId: string; }>
   .createCheckoutSession(opts: { customerId: string; priceId: string; subscriberType: SubscriberType; subscriberId: string; trialDays?: number; successUrl: string; cancelUrl: string; }): 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; }): Promise<{ url: string; }>
   .constructEvent(opts: { payload: string; signature: string; secret: string; }): Promise<IBillingEvent>
 
@@ -43,6 +46,7 @@ interface IBillingConfig {
         backend?: RateLimitBackendConfig;
     };
     notifications?: IBillingNotificationsConfig;
+    pricing?: IBillingPricingConfig;
 }
 
 interface IBillingPlan {
@@ -62,6 +66,19 @@ interface IBillingPlanDefaults {
     buffer?: number;
 }
 
+interface IBillingPlanPrice {
+    lookupKey?: string;
+    priceId?: string;
+    amount?: number;
+}
+
+interface IBillingPricingConfig {
+    hydration?: boolean;
+    cacheTtlMs?: number;
+    transferGraceMs?: number;
+    maxStaleMs?: number;
+}
+
 type RateLimitBackendConfig = 'memory' | 'db' | ICounterBackend;
 
 interface IBillingNotificationsConfig {
@@ -84,6 +101,10 @@ interface ICounterBackend {
     get(key: string, windowMs: number | null): Promise<number>;
 }
 
+const BILLING_INTERVAL: { readonly MONTH: "month"; readonly YEAR: "year"; }
+
+type BillingInterval = (typeof BILLING_INTERVAL)[keyof typeof BILLING_INTERVAL];
+
 interface IBillingProvider {
     name: string;
     createCustomer(opts: {
@@ -105,6 +126,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;
@@ -123,6 +154,17 @@ interface IBillingEvent {
     subscription: INormalizedSubscription | null;
 }
 
+interface IResolvedPrice {
+    priceId: string;
+    lookupKey: string | null;
+    unitAmount: number;
+    currency: string;
+    interval: 'month' | 'year';
+    nickname: string | null;
+    productId: string;
+    active: boolean;
+}
+
 interface IPlan {
     id: string;
     name: string;
@@ -211,6 +253,7 @@ interface IPlanDTO {
         yearly: number;
         currency: string;
     };
+    pricingStale?: boolean;
     features: IPlanFeature[];
     metadata: Record<string, unknown>;
 }

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

@@ -88,8 +88,9 @@ interface IBillingPlanPrice {
     /** 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.
+     * Display amount in cents — the seed value written to fonderie_plans and the
+     * fallback shown (flagged pricingStale) when hydration is off or Stripe is
+     * unreachable. When hydration resolves a live price, the live amount wins.
      */
     amount?: number;
 }
@@ -99,7 +100,7 @@ interface IBillingPlanPrice {
  * See packages/billing/docs/pricing-hydration.md.
  */
 interface IBillingPricingConfig {
-    /** Kill-switch. When false (default), use the deprecated hardcoded amount/USD path. */
+    /** Kill-switch. When false (default), serve the configured amount/USD directly. */
     hydration?: boolean;
     /** Fresh-cache TTL. Default 300_000 (5m). */
     cacheTtlMs?: number;

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

@@ -88,8 +88,9 @@ interface IBillingPlanPrice {
     /** 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.
+     * Display amount in cents — the seed value written to fonderie_plans and the
+     * fallback shown (flagged pricingStale) when hydration is off or Stripe is
+     * unreachable. When hydration resolves a live price, the live amount wins.
      */
     amount?: number;
 }
@@ -99,7 +100,7 @@ interface IBillingPlanPrice {
  * See packages/billing/docs/pricing-hydration.md.
  */
 interface IBillingPricingConfig {
-    /** Kill-switch. When false (default), use the deprecated hardcoded amount/USD path. */
+    /** Kill-switch. When false (default), serve the configured amount/USD directly. */
     hydration?: boolean;
     /** Fresh-cache TTL. Default 300_000 (5m). */
     cacheTtlMs?: number;