@fonderie/billing 1.1.0 → 1.1.2

package/brain/outcomes.md

@@ -0,0 +1,91 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/billing — outcomes
+
+What this package does to a running app: tables its migrations create,
+rows it seeds, routes it registers. Generated from the migration SQL and
+route tables in source — trust this file instead of reading `dist/` or
+downloading tarballs.
+
+## Database tables (after all migrations)
+
+### `fonderie_billing_notifications`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+subscriber_type          TEXT NOT NULL
+subscriber_id            UUID NOT NULL
+policy_key               TEXT NOT NULL
+notification             TEXT NOT NULL
+window_key               TEXT NOT NULL
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+-- CONSTRAINT fonderie_billing_notifications_unique UNIQUE (subscriber_type, subscriber_id, policy_key, notification, window_key)
+```
+
+### `fonderie_plans`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+name                     TEXT NOT NULL UNIQUE
+seats                    INT
+trial_days               INT NOT NULL DEFAULT 0
+monthly_amount           INT
+monthly_price_id         TEXT
+yearly_amount            INT
+yearly_price_id          TEXT
+active                   BOOLEAN NOT NULL DEFAULT true
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+description              TEXT
+tier                     INT NOT NULL DEFAULT 0
+features                 JSONB NOT NULL DEFAULT '[]'
+metadata                 JSONB NOT NULL DEFAULT '{}'
+```
+
+### `fonderie_subscriptions`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+plan                     TEXT NOT NULL
+interval                 TEXT NOT NULL DEFAULT 'month'
+status                   TEXT NOT NULL DEFAULT 'incomplete'
+provider_customer_id     TEXT
+provider_subscription_id TEXT
+current_period_start     TIMESTAMPTZ
+current_period_end       TIMESTAMPTZ
+cancel_at_period_end     BOOLEAN NOT NULL DEFAULT false
+trial_ends_at            TIMESTAMPTZ
+created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+subscriber_type          TEXT NOT NULL
+subscriber_id            UUID NOT NULL
+CONSTRAINT               fonderie_subscriptions_subscriber_unique UNIQUE (subscriber_type, subscriber_id)
+```
+
+### `fonderie_usage_records`
+
+```sql
+id                       UUID PRIMARY KEY DEFAULT gen_random_uuid()
+metric                   TEXT NOT NULL
+quantity                 INT NOT NULL DEFAULT 1
+recorded_at              TIMESTAMPTZ NOT NULL DEFAULT now()
+subscriber_type          TEXT NOT NULL
+subscriber_id            UUID NOT NULL
+CONSTRAINT               fonderie_usage_records_subscriber_type_check CHECK (subscriber_type IN ('user', 'workspace'))
+```
+
+Raw SQL ships in `node_modules/@fonderie/billing/dist/migrations/sql/` — read it there if you must; never download tarballs.
+
+## HTTP routes registered
+
+| Method | Path | Middleware chain (auth / validation / handler) |
+|---|---|---|
+| POST | `/billing/checkout` | `requireAuth → validate(checkoutSchema) → checkout.createSession` |
+| POST | `/billing/portal` | `requireAuth → checkout.createPortal` |
+| GET | `/billing/subscription` | `requireAuth → subscription.get` |
+| POST | `/billing/usage` | `requireAuth → validate(recordUsageSchema) → usage.record` |
+| GET | `/billing/usage/:metric` | `requireAuth → usage.get` |
+| POST | `/billing/webhook` | `webhook.handle` |
+| GET | `/plans` | `plan.list` |
+| POST | `/plans` | `validate(createPlanSchema) → plan.create` |
+| DELETE | `/plans/:planId` | `plan.delete` |
+| GET | `/plans/:planId` | `plan.get` |
+| PUT | `/plans/:planId` | `validate(updatePlanSchema) → plan.update` |

package/brain/signatures.md

@@ -0,0 +1,268 @@
+<!-- GENERATED — do not edit. Regenerate with: npm run docs:signatures -->
+
+# @fonderie/billing — signatures
+
+## @fonderie/billing
+
+Subpath exports: `@fonderie/billing/types`, `@fonderie/billing/middleware`, `@fonderie/billing/migrations`
+
+```ts
+new BillingModule(store: IStoreAdapter, config: IBillingConfig): BillingModule
+  .name: "@fonderie/billing"
+  .deps: string[]
+  .install(app: IFonderieApp): Promise<void>
+
+new StripeProvider(secretKey: string, webhookSecret?: string | undefined): StripeProvider
+  .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; }>
+  .createPortalSession(opts: { customerId: string; returnUrl: string; }): Promise<{ url: string; }>
+  .constructEvent(opts: { payload: string; signature: string; secret: string; }): Promise<IBillingEvent>
+
+function requirePlan(plans: string | string[], store: IStoreAdapter): Middleware
+
+function withBilling(store: IStoreAdapter, config: IBillingConfig, backend: ICounterBackend): Middleware
+
+function hasFeature(ctx: IFonderieContext, key: string): boolean
+
+function getPlanLimit(ctx: IFonderieContext, key: string): number | null
+
+function getLimitStatus(ctx: IFonderieContext, key: string): IPolicyStatus | null
+
+function requireFeature(key: string): Middleware
+
+const MESSAGE_KEYS: { readonly limitWarning: "billing.limit-warning"; readonly limitReached: "billing.limit-reached"; readonly limitBlocked: "billing.limit-blocked"; }
+
+interface IBillingConfig {
+    provider: IBillingProvider;
+    plans: IBillingPlan[];
+    successUrl: string;
+    cancelUrl: string;
+    webhookSecret?: string;
+    rateLimit?: {
+        backend?: RateLimitBackendConfig;
+    };
+    notifications?: IBillingNotificationsConfig;
+}
+
+interface IBillingPlan {
+    name: string;
+    description?: string;
+    tier?: number;
+    trialDays?: number;
+    monthly?: IBillingPlanPrice;
+    yearly?: IBillingPlanPrice;
+    defaults?: IBillingPlanDefaults;
+    policy?: Record<string, PolicyEntry>;
+    metadata?: Record<string, unknown>;
+}
+
+interface IBillingPlanDefaults {
+    warnAt?: number;
+    buffer?: number;
+}
+
+type RateLimitBackendConfig = 'memory' | 'db' | ICounterBackend;
+
+interface IBillingNotificationsConfig {
+    warnAt?: boolean;
+    softHit?: boolean;
+}
+
+type BillingMessageKey = (typeof MESSAGE_KEYS)[keyof typeof MESSAGE_KEYS];
+
+new MemoryCounterBackend(): MemoryCounterBackend
+  .increment(key: string, windowMs: number | null, quantity?: number): Promise<number>
+  .get(key: string, windowMs: number | null): Promise<number>
+
+new DBCounterBackend(store: IStoreAdapter): DBCounterBackend
+  .increment(key: string, windowMs: number | null, quantity?: number): Promise<number>
+  .get(key: string, windowMs: number | null): Promise<number>
+
+interface ICounterBackend {
+    increment(key: string, windowMs: number | null, quantity?: number): Promise<number>;
+    get(key: string, windowMs: number | null): Promise<number>;
+}
+
+interface IBillingProvider {
+    name: string;
+    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;
+    }>;
+    createPortalSession(opts: {
+        customerId: string;
+        returnUrl: string;
+    }): Promise<{
+        url: string;
+    }>;
+    constructEvent(opts: {
+        payload: string;
+        signature: string;
+        secret: string;
+    }): Promise<IBillingEvent>;
+}
+
+interface IBillingEvent {
+    type: string;
+    subscription: INormalizedSubscription | null;
+}
+
+interface IPlan {
+    id: string;
+    name: string;
+    seats: number | null;
+    trialDays: number;
+    monthlyAmount: number | null;
+    monthlyPriceId: string | null;
+    yearlyAmount: number | null;
+    yearlyPriceId: string | null;
+    description: string | null;
+    tier: number;
+    features: IPlanFeature[];
+    metadata: Record<string, unknown>;
+}
+
+interface ISubscription {
+    id: string;
+    subscriberType: SubscriberType;
+    subscriberId: string;
+    plan: string;
+    interval: 'month' | 'year';
+    status: SubscriptionStatus;
+    providerCustomerId: string | null;
+    providerSubscriptionId: string | null;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    cancelAtPeriodEnd: boolean;
+    trialEndsAt: string | null;
+    createdAt: string;
+}
+
+interface IUsageRecord {
+    id: string;
+    subscriberType: SubscriberType;
+    subscriberId: string;
+    metric: string;
+    quantity: number;
+    recordedAt: string;
+}
+
+type SubscriptionStatus = 'trialing' | 'active' | 'past_due' | 'canceled' | 'incomplete' | 'paused';
+
+type PolicyEntry = {
+    enabled: boolean;
+} | {
+    limit: number | null;
+    buffer?: number;
+    warnAt?: number;
+    window?: string;
+    unit?: string;
+};
+
+type LimitStatus = 'ok' | 'warning' | 'over_limit' | 'blocked';
+
+type IPolicyStatus = {
+    type: 'feature';
+    enabled: boolean;
+} | {
+    type: 'counter';
+    limit: number | null;
+    used: number;
+    status: LimitStatus;
+    resetsAt: string | null;
+};
+
+interface IBillingContext {
+    subscriber: {
+        type: SubscriberType;
+        id: string;
+    };
+    plan: string;
+    active: boolean;
+    statuses: Record<string, IPolicyStatus>;
+}
+
+interface IPlanDTO {
+    id: string;
+    planId: string;
+    name: string;
+    description: string;
+    tier: number;
+    seats: number | null;
+    trialDays: number;
+    pricing: {
+        monthly: number;
+        yearly: number;
+        currency: string;
+    };
+    features: IPlanFeature[];
+    metadata: Record<string, unknown>;
+}
+
+interface ISubscriptionDTO {
+    id: string;
+    subscriberType: SubscriberType;
+    subscriberId: string;
+    plan: string;
+    interval: string;
+    status: string;
+    cancelAtPeriodEnd: boolean;
+    currentPeriodStart: string | null;
+    currentPeriodEnd: string | null;
+    trialEndsAt: string | null;
+    createdAt: string;
+}
+
+interface IUsageRecordDTO {
+    id: string;
+    subscriberType: SubscriberType;
+    subscriberId: string;
+    metric: string;
+    quantity: number;
+    recordedAt: string;
+}
+
+function toPlanDTO(plan: IPlan): IPlanDTO
+
+function toSubscriptionDTO(sub: ISubscription): ISubscriptionDTO
+
+function toUsageRecordDTO(record: IUsageRecord): IUsageRecordDTO
+
+function recordUsage(opts: { subscriberType: SubscriberType; subscriberId: string; metric: string; quantity: number; }, store: IStoreAdapter): Promise<void>
+
+function getUsage(subscriberType: SubscriberType, subscriberId: string, metric: string, since: Date, store: IStoreAdapter): Promise<number>
+
+function getPlans(config: IBillingConfig): IBillingPlan[]
+
+function getPlanByName(name: string, config: IBillingConfig): IBillingPlan | null
+
+function getDBPlans(store: IStoreAdapter): Promise<IPlan[]>
+
+function getPlanById(id: string, store: IStoreAdapter): Promise<IPlan | null>
+
+function createPlan(data: { name: string; description?: string | null; tier?: number; seats?: number | null; trialDays?: number; features?: unknown; metadata?: unknown; monthlyAmount?: number | null; monthlyPriceId?: string | null; yearlyAmount?: number | null; yearlyPriceId?: string | null; }, store: IStoreAdapter): Promise<...>
+
+function updatePlan(id: string, data: Partial<Omit<IPlan, "id">>, store: IStoreAdapter): Promise<IPlan | null>
+
+function deletePlan(id: string, store: IStoreAdapter): Promise<boolean>
+
+function getSubscription(subscriberType: SubscriberType, subscriberId: string, store: IStoreAdapter): Promise<ISubscription | null>
+
+namespace schemas — exports: checkoutSchema, createPlanSchema, recordUsageSchema, updatePlanSchema
+```

package/dist/migrations/sql/001_billing.sql

@@ -0,0 +1,38 @@
+CREATE TABLE IF NOT EXISTS fonderie_plans (
+  id               UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  name             TEXT NOT NULL UNIQUE,
+  seats            INT,
+  trial_days       INT NOT NULL DEFAULT 0,
+  monthly_amount   INT,
+  monthly_price_id TEXT,
+  yearly_amount    INT,
+  yearly_price_id  TEXT,
+  active           BOOLEAN NOT NULL DEFAULT true,
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS fonderie_subscriptions (
+  id                       UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id             UUID NOT NULL UNIQUE,
+  plan                     TEXT NOT NULL,
+  interval                 TEXT NOT NULL DEFAULT 'month',
+  status                   TEXT NOT NULL DEFAULT 'incomplete',
+  provider_customer_id     TEXT,
+  provider_subscription_id TEXT,
+  current_period_start     TIMESTAMPTZ,
+  current_period_end       TIMESTAMPTZ,
+  cancel_at_period_end     BOOLEAN NOT NULL DEFAULT false,
+  trial_ends_at            TIMESTAMPTZ,
+  created_at               TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS fonderie_usage_records (
+  id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id UUID NOT NULL,
+  metric       TEXT NOT NULL,
+  quantity     INT NOT NULL DEFAULT 1,
+  recorded_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS fonderie_usage_records_workspace_metric_idx
+  ON fonderie_usage_records (workspace_id, metric, recorded_at);

package/dist/migrations/sql/002_billing_plan_fields.sql

@@ -0,0 +1,5 @@
+ALTER TABLE fonderie_plans
+  ADD COLUMN IF NOT EXISTS description TEXT,
+  ADD COLUMN IF NOT EXISTS tier        INT  NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS features    JSONB NOT NULL DEFAULT '[]',
+  ADD COLUMN IF NOT EXISTS metadata    JSONB NOT NULL DEFAULT '{}';

package/dist/migrations/sql/003_drop_limits.sql

@@ -0,0 +1 @@
+ALTER TABLE fonderie_plans DROP COLUMN IF EXISTS limits;

package/dist/migrations/sql/004_polymorphic_subscribers.sql

@@ -0,0 +1,49 @@
+-- fonderie_subscriptions: replace workspace_id with polymorphic subscriber
+ALTER TABLE fonderie_subscriptions
+  ADD COLUMN subscriber_type TEXT,
+  ADD COLUMN subscriber_id   UUID;
+
+UPDATE fonderie_subscriptions
+  SET subscriber_type = 'workspace',
+      subscriber_id   = workspace_id;
+
+ALTER TABLE fonderie_subscriptions
+  ALTER COLUMN subscriber_type SET NOT NULL,
+  ALTER COLUMN subscriber_id   SET NOT NULL;
+
+ALTER TABLE fonderie_subscriptions
+  DROP CONSTRAINT fonderie_subscriptions_workspace_id_key;
+
+ALTER TABLE fonderie_subscriptions
+  DROP COLUMN workspace_id;
+
+ALTER TABLE fonderie_subscriptions
+  ADD CONSTRAINT fonderie_subscriptions_subscriber_type_check
+    CHECK (subscriber_type IN ('user', 'workspace')),
+  ADD CONSTRAINT fonderie_subscriptions_subscriber_unique
+    UNIQUE (subscriber_type, subscriber_id);
+
+-- fonderie_usage_records: replace workspace_id with polymorphic subscriber
+ALTER TABLE fonderie_usage_records
+  ADD COLUMN subscriber_type TEXT,
+  ADD COLUMN subscriber_id   UUID;
+
+UPDATE fonderie_usage_records
+  SET subscriber_type = 'workspace',
+      subscriber_id   = workspace_id;
+
+ALTER TABLE fonderie_usage_records
+  ALTER COLUMN subscriber_type SET NOT NULL,
+  ALTER COLUMN subscriber_id   SET NOT NULL;
+
+ALTER TABLE fonderie_usage_records
+  DROP COLUMN workspace_id;
+
+ALTER TABLE fonderie_usage_records
+  ADD CONSTRAINT fonderie_usage_records_subscriber_type_check
+    CHECK (subscriber_type IN ('user', 'workspace'));
+
+DROP INDEX IF EXISTS fonderie_usage_records_workspace_metric_idx;
+
+CREATE INDEX fonderie_usage_records_subscriber_metric_idx
+  ON fonderie_usage_records (subscriber_type, subscriber_id, metric, recorded_at);

package/dist/migrations/sql/005_billing_notifications.sql

@@ -0,0 +1,13 @@
+-- Tracks which threshold notifications have been sent per subscriber/key/window.
+-- Prevents duplicate emails when a subscriber hovers around a threshold.
+CREATE TABLE IF NOT EXISTS fonderie_billing_notifications (
+	id              UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+	subscriber_type TEXT        NOT NULL,
+	subscriber_id   UUID        NOT NULL,
+	policy_key      TEXT        NOT NULL,
+	notification    TEXT        NOT NULL,   -- 'warning' | 'reached' | 'blocked'
+	window_key      TEXT        NOT NULL,   -- e.g. '2026-05-13' for a 1-day window
+	created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+	CONSTRAINT fonderie_billing_notifications_unique
+		UNIQUE (subscriber_type, subscriber_id, policy_key, notification, window_key)
+);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fonderie/billing",
-	"version": "1.1.0",
+	"version": "1.1.2",
 	"description": "SaaS billing in one module — config-driven plan catalogue, Stripe subscriptions, polymorphic user and workspace billing surfaces, usage metering, and webhook handling.",
 	"keywords": [
 		"fonderie-js",
@@ -71,17 +71,18 @@
 	},
 	"files": [
 		"dist",
+		"brain",
 		"LICENSE",
 		"README.md"
 	],
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/fonderie-js/sdk.git",
+		"url": "git+https://github.com/fonderiejs/sdk.git",
 		"directory": "packages/billing"
 	},
-	"homepage": "https://github.com/fonderie-js/sdk/tree/main/packages/billing#readme",
+	"homepage": "https://github.com/fonderiejs/sdk/tree/main/packages/billing#readme",
 	"bugs": {
-		"url": "https://github.com/fonderie-js/sdk/issues"
+		"url": "https://github.com/fonderiejs/sdk/issues"
 	},
 	"dependencies": {
 		"zod": "^4.4.3"