@fonderie/billing 1.0.0 → 1.1.1

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/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   recordUsage: () => recordUsage,
   requireFeature: () => requireFeature,
   requirePlan: () => requirePlan,
+  schemas: () => schemas_exports,
   toPlanDTO: () => toPlanDTO,
   toSubscriptionDTO: () => toSubscriptionDTO,
   toUsageRecordDTO: () => toUsageRecordDTO,
@@ -50,6 +51,41 @@ module.exports = __toCommonJS(index_exports);
 // src/routes.ts
 var import_middlewares = require("@fonderie/core/middlewares");
 
+// src/schemas.ts
+var schemas_exports = {};
+__export(schemas_exports, {
+  checkoutSchema: () => checkoutSchema,
+  createPlanSchema: () => createPlanSchema,
+  recordUsageSchema: () => recordUsageSchema,
+  updatePlanSchema: () => updatePlanSchema
+});
+var import_zod = require("zod");
+var planFields = {
+  description: import_zod.z.string().max(2e3).nullable().optional(),
+  tier: import_zod.z.number().int().min(0).optional(),
+  seats: import_zod.z.number().int().min(0).nullable().optional(),
+  trialDays: import_zod.z.number().int().min(0).optional(),
+  monthlyAmount: import_zod.z.number().min(0).nullable().optional(),
+  monthlyPriceId: import_zod.z.string().max(200).nullable().optional(),
+  yearlyAmount: import_zod.z.number().min(0).nullable().optional(),
+  yearlyPriceId: import_zod.z.string().max(200).nullable().optional(),
+  features: import_zod.z.unknown().optional(),
+  metadata: import_zod.z.unknown().optional()
+};
+var createPlanSchema = import_zod.z.object({
+  name: import_zod.z.string().trim().min(1, "name is required").max(200),
+  ...planFields
+});
+var updatePlanSchema = import_zod.z.object({ name: import_zod.z.string().trim().min(1).max(200).optional(), ...planFields }).refine((o) => Object.values(o).some((v) => v !== void 0), "Provide at least one field");
+var checkoutSchema = import_zod.z.object({
+  plan: import_zod.z.string().min(1, "plan is required"),
+  interval: import_zod.z.enum(["month", "year"]).optional()
+});
+var recordUsageSchema = import_zod.z.object({
+  metric: import_zod.z.string().min(1, "metric is required").max(100),
+  quantity: import_zod.z.number().min(0).optional()
+});
+
 // src/controllers/plan.controller.ts
 var import_core = require("@fonderie/core");
 
@@ -744,15 +780,15 @@ function buildBillingRoutes(store, config) {
     ["GET", "/plans", plan.list],
     ["GET", "/plans/:planId", plan.get],
     // Plans — admin write (caller is responsible for authorization)
-    ["POST", "/plans", plan.create],
-    ["PUT", "/plans/:planId", plan.update],
+    ["POST", "/plans", (0, import_middlewares.validate)(createPlanSchema), plan.create],
+    ["PUT", "/plans/:planId", (0, import_middlewares.validate)(updatePlanSchema), plan.update],
     ["DELETE", "/plans/:planId", plan.delete],
     // Billing — subscriber resolved from X-Workspace-ID header (workspace) or session (user)
     // Workspace membership is verified automatically by the withBilling global middleware
     ["GET", "/billing/subscription", import_middlewares.requireAuth, subscription.get],
-    ["POST", "/billing/checkout", import_middlewares.requireAuth, checkout.createSession],
+    ["POST", "/billing/checkout", import_middlewares.requireAuth, (0, import_middlewares.validate)(checkoutSchema), checkout.createSession],
     ["POST", "/billing/portal", import_middlewares.requireAuth, checkout.createPortal],
-    ["POST", "/billing/usage", import_middlewares.requireAuth, usage.record],
+    ["POST", "/billing/usage", import_middlewares.requireAuth, (0, import_middlewares.validate)(recordUsageSchema), usage.record],
     ["GET", "/billing/usage/:metric", import_middlewares.requireAuth, usage.get],
     // Webhook — signature verified inside the handler
     ["POST", "/billing/webhook", webhook.handle]
@@ -1161,6 +1197,7 @@ function requireFeature(key) {
   recordUsage,
   requireFeature,
   requirePlan,
+  schemas,
   toPlanDTO,
   toSubscriptionDTO,
   toUsageRecordDTO,