@basaltkit/subscriptions 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,476 @@
+import * as _basaltkit_core from '@basaltkit/core';
+import { DurationInput, BasaltError, HookBus } from '@basaltkit/core';
+import { BasaltRoute } from '@basaltkit/fastify';
+
+declare class UnknownPlanError extends BasaltError {
+    constructor(plan: string);
+}
+/** Metered feature: the limit resets every billing month. */
+interface Meter {
+    readonly meter: true;
+    readonly limit: number;
+}
+/** `'api.requests': meter(100_000)` — consumed monthly. */
+declare function meter(limit: number): Meter;
+/**
+ * boolean → on/off flag · number → consumable balance (lifetime)
+ * meter(n) → monthly-reset quota · Infinity → unlimited
+ */
+type FeatureValue = boolean | number | Meter;
+type BillingPeriod = 'monthly' | 'yearly';
+interface PlanDefinition {
+    /** 0 = free · number = same price both periods · object = per period · 'custom' = sales-led */
+    price: number | {
+        monthly: number;
+        yearly: number;
+    } | 'custom';
+    trial?: DurationInput;
+    features: Record<string, FeatureValue>;
+}
+type Plans = Record<string, PlanDefinition>;
+declare function definePlans<T extends Plans>(plans: T): T;
+declare function planPrice(plan: PlanDefinition, period: BillingPeriod): number | 'custom';
+/** Normalized limit of a feature: false→0, true→Infinity. */
+declare function featureLimit(value: FeatureValue | undefined): number;
+declare function isMeter(value: FeatureValue | undefined): value is Meter;
+
+type SubscriptionStatus = 'active' | 'trialing' | 'past_due' | 'canceled' | 'incomplete';
+interface SubscriptionRecord {
+    /** The billable entity — the tenant id by convention. */
+    billableId: string;
+    plan: string;
+    period: BillingPeriod;
+    status: SubscriptionStatus;
+    trialEndsAt?: number;
+    cancelAtPeriodEnd?: boolean;
+    canceledAt?: number;
+    /** Reference in the payment gateway (e.g. Stripe subscription id). */
+    gatewayRef?: string;
+}
+interface SubscriptionStore {
+    get(billableId: string): Promise<SubscriptionRecord | null>;
+    save(record: SubscriptionRecord): Promise<void>;
+    all(): Promise<SubscriptionRecord[]>;
+}
+declare class MemorySubscriptionStore implements SubscriptionStore {
+    private readonly records;
+    get(billableId: string): Promise<SubscriptionRecord | null>;
+    save(record: SubscriptionRecord): Promise<void>;
+    all(): Promise<SubscriptionRecord[]>;
+}
+/**
+ * Deduplicates webhook processing across restarts and instances. `markProcessed`
+ * claims an event id (true = new, process it; false = already seen, skip);
+ * `release` frees the claim so a failed apply can be retried by the gateway.
+ */
+interface WebhookStore {
+    markProcessed(id: string): Promise<boolean>;
+    release(id: string): Promise<void>;
+}
+declare class MemoryWebhookStore implements WebhookStore {
+    private readonly seen;
+    markProcessed(id: string): Promise<boolean>;
+    release(id: string): Promise<void>;
+}
+interface UsageConsumeResult {
+    /** Whether the increment was applied (false when it would exceed the limit). */
+    applied: boolean;
+    /** Usage after the operation (unchanged when not applied). */
+    used: number;
+}
+/** Usage counters: `periodKey` is 'lifetime' or 'YYYY-MM' for meters. */
+interface UsageStore {
+    get(billableId: string, feature: string, periodKey: string): Promise<number>;
+    /** Unconditional increment — used for unlimited features. Returns the new total. */
+    increment(billableId: string, feature: string, periodKey: string, amount: number): Promise<number>;
+    /**
+     * Atomically increments by `amount` only if the result stays within `limit`.
+     * Must be atomic under concurrency so a quota is never overshot.
+     */
+    consume(billableId: string, feature: string, periodKey: string, amount: number, limit: number): Promise<UsageConsumeResult>;
+}
+declare class MemoryUsageStore implements UsageStore {
+    private readonly counters;
+    private key;
+    get(billableId: string, feature: string, periodKey: string): Promise<number>;
+    increment(billableId: string, feature: string, periodKey: string, amount: number): Promise<number>;
+    consume(billableId: string, feature: string, periodKey: string, amount: number, limit: number): Promise<UsageConsumeResult>;
+}
+
+/** Minimal ioredis-compatible surface — inject your client, no hard dependency. */
+interface RedisLike {
+    get(key: string): Promise<string | null>;
+    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+}
+interface RedisUsageStoreOptions {
+    /** Key prefix. Default: 'basalt:usage'. */
+    prefix?: string;
+    /**
+     * TTL in seconds for periodic (monthly) counters, so old buckets are
+     * reclaimed. Lifetime counters never expire. Default: 60 days.
+     */
+    ttlSeconds?: number;
+}
+declare class RedisUsageStore implements UsageStore {
+    private readonly redis;
+    private readonly prefix;
+    private readonly ttlSeconds;
+    constructor(redis: RedisLike, options?: RedisUsageStoreOptions);
+    private key;
+    private ttlFor;
+    get(billableId: string, feature: string, periodKey: string): Promise<number>;
+    increment(billableId: string, feature: string, periodKey: string, amount: number): Promise<number>;
+    consume(billableId: string, feature: string, periodKey: string, amount: number, limit: number): Promise<UsageConsumeResult>;
+}
+
+/** Minimal ioredis-compatible surface for webhook dedupe. */
+interface RedisWebhookClient {
+    set(key: string, value: string, ex: 'EX', seconds: number, nx: 'NX'): Promise<'OK' | null>;
+    del(key: string): Promise<number>;
+}
+interface RedisWebhookStoreOptions {
+    /** Key prefix. Default: 'basalt:webhook'. */
+    prefix?: string;
+    /**
+     * How long a processed id stays deduplicated, in seconds. Cover the
+     * gateway's retry window with margin. Default: 7 days.
+     */
+    ttlSeconds?: number;
+}
+/**
+ * Durable webhook dedupe via Redis `SET key value NX EX` — the atomic claim
+ * returns 'OK' only for the first caller, so idempotency holds across process
+ * restarts and multiple instances.
+ */
+declare class RedisWebhookStore implements WebhookStore {
+    private readonly redis;
+    private readonly prefix;
+    private readonly ttlSeconds;
+    constructor(redis: RedisWebhookClient, options?: RedisWebhookStoreOptions);
+    private key;
+    markProcessed(id: string): Promise<boolean>;
+    release(id: string): Promise<void>;
+}
+
+declare class WebhookInvalidError extends BasaltError {
+    readonly status = 400;
+    constructor();
+}
+/** Gateway-agnostic webhook event, already translated to domain terms. */
+interface WebhookEvent {
+    /** Unique id at the gateway — used for idempotent processing. */
+    id: string;
+    type: 'subscription.canceled' | 'payment.failed' | 'payment.succeeded';
+    billableId: string;
+    /** Gateway subscription id, when the event carries one (e.g. after Checkout). */
+    gatewayRef?: string;
+}
+interface CreateSubscriptionInput {
+    billableId: string;
+    plan: string;
+    period: BillingPeriod;
+    price: number;
+    /**
+     * Trial length in days. When set, the gateway runs the trial and charges at
+     * its end, driving the trial→active/past_due transition via webhook.
+     */
+    trialDays?: number;
+}
+/** Input for a hosted Checkout session (the customer enters payment there). */
+interface CheckoutInput {
+    billableId: string;
+    plan: string;
+    period: BillingPeriod;
+    successUrl: string;
+    cancelUrl: string;
+    trialDays?: number;
+}
+/** Input for a Customer Portal session (self-service card/cancel management). */
+interface PortalInput {
+    billableId: string;
+    returnUrl: string;
+}
+/** Input for changing a subscription's plan mid-cycle with proration. */
+interface SwapInput {
+    plan: string;
+    period: BillingPeriod;
+    /** How the gateway settles the mid-cycle difference. Default create_prorations. */
+    prorationBehavior?: 'create_prorations' | 'none' | 'always_invoice';
+}
+/**
+ * Payment gateway driver contract. The app talks to Basalt; only drivers
+ * talk to Stripe/Paddle/Lemon Squeezy. A driver translates raw webhook
+ * payloads into WebhookEvent — app code never sees gateway payloads.
+ */
+interface BillingGateway {
+    readonly name: string;
+    createSubscription(input: CreateSubscriptionInput): Promise<{
+        gatewayRef: string;
+    }>;
+    cancelSubscription(gatewayRef: string, options: {
+        atPeriodEnd: boolean;
+    }): Promise<void>;
+    /**
+     * Verifies the signature and translates the payload. Throws
+     * WebhookInvalidError on a bad signature. Returns null for a verified event
+     * the gateway doesn't map to a domain event (gateways emit many event types
+     * we don't act on).
+     */
+    verifyWebhook(rawBody: string, signature: string | undefined): WebhookEvent | null;
+    /** Hosted Checkout session — returns a URL to redirect the customer to. */
+    createCheckoutSession?(input: CheckoutInput): Promise<{
+        url: string;
+        id: string;
+    }>;
+    /** Customer Portal session — returns a URL for self-service billing. */
+    createPortalSession?(input: PortalInput): Promise<{
+        url: string;
+    }>;
+    /** Changes the plan on an existing subscription, applying proration. */
+    swapSubscription?(gatewayRef: string, input: SwapInput): Promise<void>;
+}
+/** Controllable in-process gateway — the test/dev driver. */
+declare class FakeBillingGateway implements BillingGateway {
+    readonly name = "fake";
+    readonly created: CreateSubscriptionInput[];
+    readonly canceled: {
+        gatewayRef: string;
+        atPeriodEnd: boolean;
+    }[];
+    readonly checkouts: CheckoutInput[];
+    readonly portals: PortalInput[];
+    readonly swaps: {
+        gatewayRef: string;
+        input: SwapInput;
+    }[];
+    private counter;
+    createSubscription(input: CreateSubscriptionInput): Promise<{
+        gatewayRef: string;
+    }>;
+    cancelSubscription(gatewayRef: string, options: {
+        atPeriodEnd: boolean;
+    }): Promise<void>;
+    createCheckoutSession(input: CheckoutInput): Promise<{
+        url: string;
+        id: string;
+    }>;
+    createPortalSession(input: PortalInput): Promise<{
+        url: string;
+    }>;
+    swapSubscription(gatewayRef: string, input: SwapInput): Promise<void>;
+    verifyWebhook(rawBody: string, signature: string | undefined): WebhookEvent;
+}
+
+declare class StripeRequestError extends BasaltError {
+    readonly httpStatus: number;
+    constructor(httpStatus: number, message: string);
+}
+interface StripeGatewayOptions {
+    secretKey: string;
+    /** The endpoint signing secret (`whsec_...`) used to verify webhooks. */
+    webhookSecret: string;
+    /** Resolves the Stripe Price ID for a plan + billing period. */
+    priceId: (plan: string, period: BillingPeriod) => string;
+    /** Resolves (or ensures) the Stripe Customer ID for a billable entity. */
+    customerId: (billableId: string) => string | Promise<string>;
+    /**
+     * Extracts the billable id from a verified event. Default: reads
+     * `data.object.metadata.billableId` — which createSubscription sets on the
+     * subscription. Override for events whose object carries it elsewhere.
+     */
+    resolveBillableId?: (event: unknown) => string | undefined;
+    /** Webhook timestamp tolerance in seconds. Default: 300 (5 minutes). */
+    tolerance?: number;
+    /** Injected fetch (tests). Default: global fetch. */
+    fetch?: typeof fetch;
+    /** Clock in ms (tests). Default: Date.now. */
+    now?: () => number;
+    /** API base, for tests/mocks. Default: https://api.stripe.com */
+    apiBase?: string;
+}
+/**
+ * Stripe billing gateway targeting the Stripe REST API directly — no `stripe`
+ * SDK dependency. HTTP goes through an injectable fetch; webhook signatures are
+ * verified with node:crypto using Stripe's documented scheme.
+ */
+declare class StripeBillingGateway implements BillingGateway {
+    private readonly options;
+    readonly name = "stripe";
+    private readonly fetch;
+    private readonly now;
+    private readonly tolerance;
+    private readonly apiBase;
+    private readonly resolveBillableId;
+    constructor(options: StripeGatewayOptions);
+    createSubscription(input: CreateSubscriptionInput): Promise<{
+        gatewayRef: string;
+    }>;
+    cancelSubscription(gatewayRef: string, options: {
+        atPeriodEnd: boolean;
+    }): Promise<void>;
+    createCheckoutSession(input: CheckoutInput): Promise<{
+        url: string;
+        id: string;
+    }>;
+    createPortalSession(input: PortalInput): Promise<{
+        url: string;
+    }>;
+    swapSubscription(gatewayRef: string, input: SwapInput): Promise<void>;
+    verifyWebhook(rawBody: string, signature: string | undefined): WebhookEvent | null;
+    private request;
+}
+
+declare class NotSubscribedError extends BasaltError {
+    readonly status = 402;
+    constructor();
+}
+declare class FeatureUnavailableError extends BasaltError {
+    readonly status = 403;
+    constructor(feature: string);
+}
+declare class QuotaExceededError extends BasaltError {
+    readonly status = 402;
+    constructor(feature: string, remaining: number);
+}
+/** A billing action needs a gateway (or gateway capability) that isn't configured. */
+declare class GatewayUnsupportedError extends BasaltError {
+    readonly status = 501;
+    constructor(capability: string);
+}
+interface SubscriptionsOptions {
+    plans: Plans;
+    store?: SubscriptionStore;
+    usage?: UsageStore;
+    gateway?: BillingGateway;
+    /** Webhook dedupe store. Default: in-memory (per-process). */
+    webhooks?: WebhookStore;
+    /** Plan applied to billables without a subscription (e.g. 'free'). */
+    fallbackPlan?: string;
+    hooks?: HookBus;
+}
+declare class Subscriptions {
+    private readonly plans;
+    private readonly store;
+    private readonly usage;
+    private readonly gateway;
+    private readonly fallbackPlan;
+    private readonly hooks;
+    private readonly webhooks;
+    constructor(options: SubscriptionsOptions);
+    plan(name: string): PlanDefinition;
+    subscribe(billableId: string, planName: string, options?: {
+        period?: BillingPeriod;
+    }): Promise<SubscriptionRecord>;
+    /**
+     * Starts a hosted Checkout flow for a paid plan. Records the intended
+     * subscription locally as `incomplete` — it becomes `active` when the
+     * gateway confirms payment via webhook (`payment.succeeded`). Returns the
+     * URL to redirect the customer to.
+     */
+    checkout(billableId: string, planName: string, options: {
+        period?: BillingPeriod;
+        successUrl: string;
+        cancelUrl: string;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * Opens a Customer Portal session for self-service billing (update card,
+     * change plan, cancel). Returns the URL to redirect the customer to.
+     */
+    portal(billableId: string, options: {
+        returnUrl: string;
+    }): Promise<{
+        url: string;
+    }>;
+    get(billableId: string): Promise<SubscriptionRecord | null>;
+    /** Active = status active, or trialing with the trial still running. */
+    subscribed(billableId: string, plan?: string): Promise<boolean>;
+    onTrial(billableId: string): Promise<boolean>;
+    /**
+     * Changes the plan on an active subscription. When the subscription is
+     * gateway-backed, the change is pushed to the gateway with proration so the
+     * customer is credited/charged the mid-cycle difference (pass
+     * `{ prorate: false }` to switch at the next renewal with no immediate
+     * settlement).
+     */
+    swap(billableId: string, planName: string, options?: {
+        prorate?: boolean;
+    }): Promise<SubscriptionRecord>;
+    cancel(billableId: string, options?: {
+        atPeriodEnd?: boolean;
+    }): Promise<SubscriptionRecord>;
+    resume(billableId: string): Promise<SubscriptionRecord>;
+    /** Feature checks and consumption, Soulbscription-style. */
+    features(billableId: string): {
+        can: (feature: string) => Promise<boolean>;
+        limit: (feature: string) => Promise<number>;
+        usage: (feature: string) => Promise<number>;
+        remaining: (feature: string) => Promise<number>;
+        consume: (feature: string, amount?: number) => Promise<number>;
+    };
+    /**
+     * Applies a gateway webhook: idempotent by event id, updates local state
+     * and emits domain hooks. Local state is the read model — feature checks
+     * never call the gateway.
+     */
+    handleWebhook(event: WebhookEvent): Promise<boolean>;
+    /**
+     * Maintenance (run from the scheduler): settles expired local trials.
+     * Gateway-backed trials are settled by the gateway's webhook, not here.
+     */
+    expireTrials(): Promise<SubscriptionRecord[]>;
+    private isActive;
+}
+
+declare module '@basaltkit/core' {
+    interface BasaltHooks {
+        'billing:subscribed': {
+            subscription: SubscriptionRecord;
+        };
+        'billing:swapped': {
+            subscription: SubscriptionRecord;
+            from: string;
+        };
+        'billing:canceled': {
+            subscription: SubscriptionRecord;
+        };
+        'billing:trial_expired': {
+            subscription: SubscriptionRecord;
+        };
+        'billing:webhook': {
+            event: WebhookEvent;
+        };
+        'billing:checkout_started': {
+            billableId: string;
+            plan: string;
+            url: string;
+        };
+    }
+}
+declare const SUBSCRIPTIONS: _basaltkit_core.Token<Subscriptions>;
+type SubscriptionsPluginOptions = Omit<SubscriptionsOptions, 'hooks'>;
+declare function subscriptionsPlugin(options: SubscriptionsPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+interface BillingRoutesOptions {
+    /** Where Stripe returns the customer after Checkout. */
+    successUrl: string;
+    cancelUrl: string;
+    /** Where the Customer Portal returns the customer. Default: successUrl. */
+    portalReturnUrl?: string;
+}
+/**
+ * Hosted billing routes for the current tenant: `POST /billing/checkout`
+ * (subscribe via the gateway's hosted page) and `POST /billing/portal`
+ * (self-service management). Both return `{ url }` to redirect to. The
+ * success/cancel/return URLs are configured here; the request body may
+ * override them per call.
+ */
+declare function billingRoutes(options: BillingRoutesOptions): BasaltRoute[];
+/**
+ * Webhook endpoint: POST /billing/webhook — signature verified by the
+ * gateway driver, processing idempotent by event id. Returns 200 with
+ * { received, duplicate } so gateways stop retrying.
+ */
+declare function billingWebhookRoute(gateway: BillingGateway): BasaltRoute;
+
+export { type BillingGateway, type BillingPeriod, type BillingRoutesOptions, type CheckoutInput, type CreateSubscriptionInput, FakeBillingGateway, FeatureUnavailableError, type FeatureValue, GatewayUnsupportedError, MemorySubscriptionStore, MemoryUsageStore, MemoryWebhookStore, type Meter, NotSubscribedError, type PlanDefinition, type Plans, type PortalInput, QuotaExceededError, type RedisLike, RedisUsageStore, type RedisUsageStoreOptions, type RedisWebhookClient, RedisWebhookStore, type RedisWebhookStoreOptions, SUBSCRIPTIONS, StripeBillingGateway, type StripeGatewayOptions, StripeRequestError, type SubscriptionRecord, type SubscriptionStatus, type SubscriptionStore, Subscriptions, type SubscriptionsOptions, type SubscriptionsPluginOptions, type SwapInput, UnknownPlanError, type UsageConsumeResult, type UsageStore, type WebhookEvent, WebhookInvalidError, type WebhookStore, billingRoutes, billingWebhookRoute, definePlans, featureLimit, isMeter, meter, planPrice, subscriptionsPlugin };