@startsimpli/billing 0.4.19 → 0.4.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.19",
+  "version": "0.4.20",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -8,6 +8,7 @@
     ".": "./src/index.ts",
     "./client": "./src/index.ts",
     "./server": "./src/server/index.ts",
+    "./plan": "./src/utils/plan.ts",
     "./types": "./src/types/index.ts",
     "./mock": "./src/mock/index.ts"
   },

package/src/index.ts

@@ -57,4 +57,5 @@ export type {
 export { BillingApiClient } from "./utils/api";
 
 // Pure helpers
-export { isPaidSubscription } from "./utils/plan";
+export { isPaidSubscription, getFeatureLimit, resolvePlanEntitlement, resolveUsageWindow } from "./utils/plan";
+export type { PlanEntitlement, ResolvePlanEntitlementOptions, UsageWindow } from "./utils/plan";

package/src/utils/plan.test.ts

@@ -85,3 +85,230 @@ describe('isPaidSubscription', () => {
     expect(isPaidSubscription(sub)).toBe(false)
   })
 })
+
+// ---------------------------------------------------------------------------
+// Entitlement resolution (startsim-ol36d.9 / .12)
+//
+// `isPaidSubscription` answers "is this a paid plan". Gating needs three more
+// things it cannot express:
+//   1. what to do when billing is LOADING or ERRORED — the old crochet gate
+//      treated "unknown" as paid and opened Pro features to everyone;
+//   2. how big the allowance is — read from the offer's own feature list, not
+//      hardcoded in each app;
+//   3. which window to count usage in — a free subscription's
+//      current_period_start is frozen at signup and never rolls.
+// ---------------------------------------------------------------------------
+
+import { getFeatureLimit, resolvePlanEntitlement, resolveUsageWindow } from './plan'
+
+const freeOffer = makeOffer({
+  slug: 'crochet-free',
+  isFree: true,
+  unitPrice: '0.00',
+  features: [
+    { key: 'patterns_per_month', name: 'Patterns per month', value: 3, limit: 3 },
+    { key: 'save_patterns', name: 'Save patterns', value: true, limit: null },
+  ],
+})
+
+const proOffer = makeOffer({
+  slug: 'crochet-pro',
+  isFree: false,
+  unitPrice: '9.00',
+  trialDays: 7,
+  features: [
+    { key: 'patterns_per_month', name: 'Patterns per month', value: -1, limit: null },
+    { key: 'pdf_export', name: 'PDF export', value: true, limit: null },
+  ],
+})
+
+describe('getFeatureLimit', () => {
+  it('reads the numeric allowance from the offer', () => {
+    expect(getFeatureLimit(freeOffer, ['patterns_per_month'])).toBe(3)
+  })
+
+  it('maps -1 to Infinity (unlimited)', () => {
+    expect(getFeatureLimit(proOffer, ['patterns_per_month'])).toBe(Infinity)
+  })
+
+  it('maps the string "unlimited" to Infinity', () => {
+    const offer = makeOffer({
+      features: [{ key: 'patterns_per_month', name: 'x', value: 'unlimited', limit: null }],
+    })
+    expect(getFeatureLimit(offer, ['patterns_per_month'])).toBe(Infinity)
+  })
+
+  it('prefers `limit` over `value` when both are set', () => {
+    const offer = makeOffer({
+      features: [{ key: 'patterns_per_month', name: 'x', value: 99, limit: 3 }],
+    })
+    expect(getFeatureLimit(offer, ['patterns_per_month'])).toBe(3)
+  })
+
+  it('accepts an alias key', () => {
+    const offer = makeOffer({
+      features: [{ key: 'monthly_generations', name: 'x', value: 7, limit: null }],
+    })
+    expect(getFeatureLimit(offer, ['patterns_per_month', 'monthly_generations'])).toBe(7)
+  })
+
+  it('returns null when the offer declares no such feature', () => {
+    expect(getFeatureLimit(makeOffer(), ['patterns_per_month'])).toBeNull()
+  })
+
+  it('returns null for a missing offer rather than throwing', () => {
+    expect(getFeatureLimit(null, ['patterns_per_month'])).toBeNull()
+  })
+})
+
+describe('resolvePlanEntitlement', () => {
+  const opts = { featureKeys: ['patterns_per_month'], freeFallbackLimit: 3 }
+
+  it('treats an active FREE offer as free and uses the offer allowance', () => {
+    const e = resolvePlanEntitlement(makeSub({ status: 'active', offer: freeOffer }), opts)
+    expect(e.isFree).toBe(true)
+    expect(e.isPaid).toBe(false)
+    expect(e.limit).toBe(3)
+    expect(e.isUnlimited).toBe(false)
+    expect(e.unknown).toBe(false)
+  })
+
+  it('does NOT depend on the offer slug being the literal "free"', () => {
+    // The real slug is `crochet-free`. A slug === 'free' test silently
+    // misclassified all 120 real free holders as paid.
+    const e = resolvePlanEntitlement(makeSub({ status: 'active', offer: freeOffer }), opts)
+    expect(e.isFree).toBe(true)
+  })
+
+  it('treats an active PAID offer as paid and unlimited', () => {
+    const e = resolvePlanEntitlement(makeSub({ status: 'active', offer: proOffer }), opts)
+    expect(e.isPaid).toBe(true)
+    expect(e.isFree).toBe(false)
+    expect(e.isUnlimited).toBe(true)
+    expect(e.limit).toBe(Infinity)
+  })
+
+  it('treats a TRIALING paid plan as paid, not free', () => {
+    // A 7-day Pro trial is a paying customer mid-trial; the old gate gave them
+    // free limits because it tested `status === 'active'`.
+    const e = resolvePlanEntitlement(makeSub({ status: 'trialing', offer: proOffer }), opts)
+    expect(e.isPaid).toBe(true)
+    expect(e.isFree).toBe(false)
+    expect(e.isUnlimited).toBe(true)
+  })
+
+  it('fails CLOSED while billing is loading', () => {
+    const e = resolvePlanEntitlement(null, { ...opts, loading: true })
+    expect(e.isFree).toBe(true)
+    expect(e.isPaid).toBe(false)
+    expect(e.unknown).toBe(true)
+    expect(e.limit).toBe(3)
+  })
+
+  it('fails CLOSED when the billing call errored', () => {
+    // The old gate did `!subscriptionError && (...)`, so an error made
+    // isFreeUser false — i.e. an outage handed everyone Pro.
+    const e = resolvePlanEntitlement(null, { ...opts, error: new Error('boom') })
+    expect(e.isFree).toBe(true)
+    expect(e.isPaid).toBe(false)
+    expect(e.unknown).toBe(true)
+  })
+
+  it('treats no subscription at all as free', () => {
+    const e = resolvePlanEntitlement(null, opts)
+    expect(e.isFree).toBe(true)
+    expect(e.unknown).toBe(false)
+    expect(e.limit).toBe(3)
+  })
+
+  it('treats a subscription with no offer as free', () => {
+    const sub = { ...makeSub(), offer: null as unknown as ProductOffer }
+    expect(resolvePlanEntitlement(sub, opts).isFree).toBe(true)
+  })
+
+  const deadStatuses = ['past_due', 'cancelled', 'unpaid', 'trial_expired'] as const
+  for (const status of deadStatuses) {
+    it(`treats status=${status} on a paid offer as NOT paid`, () => {
+      const e = resolvePlanEntitlement(makeSub({ status, offer: proOffer }), opts)
+      expect(e.isPaid).toBe(false)
+      expect(e.isFree).toBe(true)
+      expect(e.limit).toBe(3)
+    })
+  }
+
+  it('falls back to freeFallbackLimit when a free offer declares no allowance', () => {
+    const bare = makeOffer({ isFree: true, features: [] })
+    expect(resolvePlanEntitlement(makeSub({ offer: bare }), opts).limit).toBe(3)
+  })
+
+  it('reads the allowance from the offer rather than the fallback when both exist', () => {
+    const e = resolvePlanEntitlement(makeSub({ offer: freeOffer }), {
+      ...opts,
+      freeFallbackLimit: 5,
+    })
+    expect(e.limit).toBe(3)
+  })
+
+  it('has a hasFeature() that gates a named Pro capability', () => {
+    const pro = resolvePlanEntitlement(makeSub({ offer: proOffer }), opts)
+    const free = resolvePlanEntitlement(makeSub({ offer: freeOffer }), opts)
+    expect(pro.hasFeature('pdf_export')).toBe(true)
+    expect(free.hasFeature('pdf_export')).toBe(false)
+  })
+
+  it('hasFeature() is false while unknown (fail closed)', () => {
+    const e = resolvePlanEntitlement(null, { ...opts, error: new Error('boom') })
+    expect(e.hasFeature('pdf_export')).toBe(false)
+  })
+})
+
+describe('resolveUsageWindow', () => {
+  const now = new Date('2026-09-18T12:00:00.000Z')
+
+  it('uses the calendar month when the subscription has no period bounds', () => {
+    const w = resolveUsageWindow(null, now)
+    expect(w.start.toISOString()).toBe('2026-09-01T00:00:00.000Z')
+    expect(w.end.toISOString()).toBe('2026-10-01T00:00:00.000Z')
+  })
+
+  it('IGNORES a frozen free-subscription period that never rolls', () => {
+    // SubscribeFreeViewSet writes current_period_start=now, end=None at signup
+    // and never updates it. Counting from that start is "count patterns ever"
+    // wearing a different hat — the exact bug startsim-ol36d.12 names.
+    const frozen = makeSub({
+      currentPeriodStart: '2026-03-04T09:00:00.000Z',
+      currentPeriodEnd: null,
+    })
+    const w = resolveUsageWindow(frozen, now)
+    expect(w.start.toISOString()).toBe('2026-09-01T00:00:00.000Z')
+  })
+
+  it('ignores a period whose end is already in the past', () => {
+    const stale = makeSub({
+      currentPeriodStart: '2026-07-01T00:00:00.000Z',
+      currentPeriodEnd: '2026-08-01T00:00:00.000Z',
+    })
+    expect(resolveUsageWindow(stale, now).start.toISOString()).toBe('2026-09-01T00:00:00.000Z')
+  })
+
+  it('uses a real, current billing period when both bounds are present', () => {
+    const real = makeSub({
+      currentPeriodStart: '2026-09-04T09:00:00.000Z',
+      currentPeriodEnd: '2026-10-04T09:00:00.000Z',
+    })
+    const w = resolveUsageWindow(real, now)
+    expect(w.start.toISOString()).toBe('2026-09-04T09:00:00.000Z')
+    expect(w.end.toISOString()).toBe('2026-10-04T09:00:00.000Z')
+  })
+
+  it('falls back to the calendar month on an unparseable period start', () => {
+    const bad = makeSub({ currentPeriodStart: 'not-a-date', currentPeriodEnd: 'also-bad' })
+    expect(resolveUsageWindow(bad, now).start.toISOString()).toBe('2026-09-01T00:00:00.000Z')
+  })
+
+  it('rolls into the next calendar month at the boundary', () => {
+    const w = resolveUsageWindow(null, new Date('2026-12-31T23:59:59.000Z'))
+    expect(w.start.toISOString()).toBe('2026-12-01T00:00:00.000Z')
+    expect(w.end.toISOString()).toBe('2027-01-01T00:00:00.000Z')
+  })
+})

package/src/utils/plan.ts

@@ -7,7 +7,7 @@
  * they don't.
  */
 
-import type { SubscriptionInfo } from "../types";
+import type { OfferFeature, ProductOffer, SubscriptionInfo } from "../types";
 
 const PAID_STATUSES: ReadonlyArray<SubscriptionInfo["status"]> = ["active", "trialing"];
 
@@ -28,3 +28,176 @@ export function isPaidSubscription(
   if (sub.offer.isFree) return false;
   return PAID_STATUSES.includes(sub.status);
 }
+
+/**
+ * Read a numeric allowance out of an offer's declared features.
+ *
+ * `keys` is tried in order so an app can accept an alias
+ * (e.g. `patterns_per_month` or `monthly_generations`).
+ *
+ * Returns `Infinity` for an explicit unlimited marker (`-1` or `"unlimited"`),
+ * and `null` when the offer declares no such allowance — which is NOT the same
+ * as zero, and callers must decide what an undeclared allowance means for them.
+ *
+ * `limit` wins over `value`: the backend puts the enforceable number in
+ * `limit` and uses `value` for display, and they can disagree.
+ */
+export function getFeatureLimit(
+  offer: ProductOffer | null | undefined,
+  keys: readonly string[]
+): number | null {
+  if (!offer) return null;
+  const features: OfferFeature[] = offer.features ?? [];
+  for (const key of keys) {
+    const feature = features.find((f) => f?.key === key);
+    if (!feature) continue;
+    const raw = feature.limit ?? feature.value;
+    if (raw === -1 || raw === "unlimited") return Infinity;
+    if (typeof raw === "number" && Number.isFinite(raw) && raw >= 0) return raw;
+  }
+  return null;
+}
+
+export interface PlanEntitlement {
+  /**
+   * True when the user is on a free plan — or when we could not prove they
+   * are not. Gates read this, so it fails CLOSED: the worst case is showing
+   * an upgrade prompt to someone who has already paid, which is recoverable.
+   * The opposite mistake hands Pro away during a billing outage.
+   */
+  isFree: boolean;
+  /** True only when an active or trialing PAID subscription is proven. */
+  isPaid: boolean;
+  /** The allowance for the metered feature. `Infinity` when unlimited. */
+  limit: number;
+  isUnlimited: boolean;
+  /**
+   * True when billing could not be resolved (still loading, or the call
+   * failed), so `isFree` is a fail-closed assumption rather than a fact.
+   * Use it to soften the copy ("checking your plan…"), never to open a gate.
+   */
+  unknown: boolean;
+  /**
+   * True when the plan's offer explicitly declares the named capability.
+   * Always false while `unknown`.
+   */
+  hasFeature: (key: string) => boolean;
+}
+
+export interface ResolvePlanEntitlementOptions {
+  /** Feature keys to read the metered allowance from, in priority order. */
+  featureKeys?: readonly string[];
+  /**
+   * Allowance to assume for a free user whose offer declares none — e.g. a
+   * user with no subscription row at all, who therefore has no offer to read.
+   */
+  freeFallbackLimit?: number;
+  /** Billing is still in flight. */
+  loading?: boolean;
+  /** The billing call failed. */
+  error?: unknown;
+}
+
+/**
+ * Derive what a subscription actually entitles someone to.
+ *
+ * This exists because the same three-line derivation was copied into every
+ * gate, and each copy got it wrong in a different way: testing
+ * `offer.slug === 'free'` when the real slug is `crochet-free`, testing
+ * `status === 'active'` so a paid trial counted as free, and treating a
+ * billing error as proof of a paid plan.
+ */
+export function resolvePlanEntitlement(
+  sub: SubscriptionInfo | null | undefined,
+  options: ResolvePlanEntitlementOptions = {}
+): PlanEntitlement {
+  const {
+    featureKeys = [],
+    freeFallbackLimit = Infinity,
+    loading = false,
+    error = null,
+  } = options;
+
+  // Unresolved billing is not evidence of a paid plan.
+  if (loading || error) {
+    return {
+      isFree: true,
+      isPaid: false,
+      limit: freeFallbackLimit,
+      isUnlimited: freeFallbackLimit === Infinity,
+      unknown: true,
+      hasFeature: () => false,
+    };
+  }
+
+  const offer = sub?.offer ?? null;
+  const paid = isPaidSubscription(sub);
+  const declared = getFeatureLimit(offer, featureKeys);
+
+  // An offer's allowance only counts while that offer is actually in force.
+  // A paid plan with no declared ceiling is unlimited; a free plan falls back
+  // to what the caller says free means. A LAPSED paid plan (cancelled,
+  // past_due, unpaid, expired trial) must not keep spending its old ceiling —
+  // it drops to the free allowance like anyone else.
+  let limit: number;
+  if (paid) {
+    limit = declared ?? Infinity;
+  } else if (offer?.isFree) {
+    limit = declared ?? freeFallbackLimit;
+  } else {
+    limit = freeFallbackLimit;
+  }
+
+  return {
+    isFree: !paid,
+    isPaid: paid,
+    limit,
+    isUnlimited: limit === Infinity,
+    unknown: false,
+    hasFeature: (key: string) =>
+      (offer?.features ?? []).some((f) => f?.key === key && f.value !== false),
+  };
+}
+
+export interface UsageWindow {
+  start: Date;
+  end: Date;
+}
+
+function startOfUtcMonth(d: Date): Date {
+  return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1));
+}
+
+function parse(value: string | null | undefined): Date | null {
+  if (!value) return null;
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * The window a per-period allowance should be counted over.
+ *
+ * Prefers the subscription's real billing period, but only when BOTH bounds
+ * are present and the period has not already ended. Free subscriptions are
+ * created with `current_period_start = now` and `current_period_end = NULL`
+ * and are never rolled forward, so trusting that start would count every
+ * pattern the user has ever made — which is the bug this replaces, not a fix
+ * for it. Everything else falls back to the calendar month.
+ */
+export function resolveUsageWindow(
+  sub: SubscriptionInfo | null | undefined,
+  now: Date = new Date()
+): UsageWindow {
+  const start = parse(sub?.currentPeriodStart);
+  const end = parse(sub?.currentPeriodEnd);
+
+  if (start && end && end.getTime() > now.getTime() && start.getTime() <= now.getTime()) {
+    return { start, end };
+  }
+
+  const monthStart = startOfUtcMonth(now);
+  const monthEnd = new Date(
+    Date.UTC(monthStart.getUTCFullYear(), monthStart.getUTCMonth() + 1, 1)
+  );
+  return { start: monthStart, end: monthEnd };
+}