@revstackhq/core 0.0.0-dev-20260226062415 → 0.0.0-dev-20260227093823

package/dist/index.d.ts

@@ -1,5 +1,437 @@
-export * from "./types";
-export * from "./define";
-export * from "./engine";
-export * from "./validator";
-//# sourceMappingURL=index.d.ts.map
+/**
+ * @file types.ts
+ * @description Core type definitions for Revstack's Billing Engine.
+ * These types map directly to the PostgreSQL database schema and
+ * serve as the contract for "Billing as Code".
+ */
+/**
+ * The type of a feature/entitlement.
+ * - 'boolean': On/Off flag (e.g., SSO Access).
+ * - 'static': Fixed numeric limit included in the plan (e.g., 5 Seats).
+ * - 'metered': Usage-based, tracked over time (e.g., AI Tokens).
+ */
+type FeatureType = "boolean" | "static" | "metered";
+/**
+ * The unit of measurement for a feature.
+ * Used for display, analytics, and billing calculations.
+ */
+type UnitType = "count" | "bytes" | "seconds" | "tokens" | "requests" | "custom";
+/**
+ * How often a feature's usage counter resets.
+ */
+type ResetPeriod = "monthly" | "yearly" | "never";
+/**
+ * Billing interval for a plan's price.
+ */
+type BillingInterval = "monthly" | "quarterly" | "yearly" | "one_time";
+/**
+ * The commercial classification of a plan.
+ * - 'free': No payment required (e.g., Default Guest Plan, Starter).
+ * - 'paid': Requires active payment method.
+ * - 'custom': Enterprise / negotiated pricing.
+ */
+type PlanType = "paid" | "free" | "custom";
+/**
+ * The lifecycle status of a plan.
+ * - 'draft': Not yet visible or purchasable.
+ * - 'active': Live and available for subscription.
+ * - 'archived': No longer available for new subscriptions, existing ones honored.
+ */
+type PlanStatus = "draft" | "active" | "archived";
+/**
+ * The lifecycle state of a customer's subscription.
+ * Used by the EntitlementEngine to gate access based on payment status.
+ */
+type SubscriptionStatus = "active" | "trialing" | "past_due" | "canceled" | "paused";
+/**
+ * Definition of a Feature available in the system.
+ * Maps to the `entitlements` table in the database.
+ *
+ * The `slug` field is the primary identifier and matches the dictionary
+ * key in `RevstackConfig.features`.
+ */
+interface FeatureDef {
+    /** Unique slug/identifier (matches dictionary key in config). */
+    slug: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Optional description for documentation and dashboard. */
+    description?: string;
+    /** The data type of the feature. */
+    type: FeatureType;
+    /** The unit of measurement. */
+    unit_type: UnitType;
+}
+/**
+ * Input type for `defineFeature()`.
+ * The `slug` is omitted because it is inferred from the dictionary key.
+ */
+type FeatureDefInput = Omit<FeatureDef, "slug">;
+/**
+ * Configures how a feature behaves inside a specific Plan.
+ * Maps to the `plan_entitlements` table in the database.
+ *
+ * Each field is optional — only set the fields relevant to the feature type:
+ * - Boolean features: use `value_bool`.
+ * - Static features: use `value_limit` + `is_hard_limit`.
+ * - Metered features: use `value_limit` + `reset_period`.
+ */
+interface PlanFeatureValue {
+    /** Numeric limit (e.g., 5 seats, 10000 API calls). */
+    value_limit?: number;
+    /** Boolean toggle (e.g., SSO enabled/disabled). */
+    value_bool?: boolean;
+    /** Text value for display or metadata. */
+    value_text?: string;
+    /** If true, usage is blocked when limit is reached. */
+    is_hard_limit?: boolean;
+    /** How often usage resets. */
+    reset_period?: ResetPeriod;
+}
+/**
+ * Configures how a feature behaves inside a specific Addon.
+ * An addon can either incrementally increase a plan's limit, set an absolute new limit,
+ * or grant boolean access.
+ */
+interface AddonFeatureValue {
+    /** Numeric limit to add or set. */
+    value_limit?: number;
+    /** How the limit is applied. 'increment' adds to the base plan, 'set' overrides it. */
+    type?: "increment" | "set";
+    /** Boolean toggle (e.g. granting access). */
+    has_access?: boolean;
+    /** If false, allows overage (relaxes the limit to a soft limit). */
+    is_hard_limit?: boolean;
+}
+/**
+ * Defines the pricing for a plan.
+ * Maps to the `prices` table in the database.
+ */
+interface PriceDef {
+    /** Price amount in the smallest currency unit (e.g., cents). */
+    amount: number;
+    /** ISO 4217 currency code (e.g., "USD", "EUR"). */
+    currency: string;
+    /** How often the customer is billed. */
+    billing_interval: BillingInterval;
+    /** Number of days for a free trial before billing starts. */
+    trial_period_days?: number;
+    /** Whether this price is currently active. */
+    is_active?: boolean;
+}
+/**
+ * Full plan definition. Maps to the `plans` table in the database.
+ *
+ * The `slug` is the primary identifier and matches the dictionary
+ * key in `RevstackConfig.plans`.
+ */
+interface PlanDef {
+    /** Unique slug/identifier (matches dictionary key in config). */
+    slug: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Optional description. */
+    description?: string;
+    /** Whether this is the default guest plan. */
+    is_default: boolean;
+    /** Whether this plan is visible on the pricing page. */
+    is_public: boolean;
+    /** Commercial classification. */
+    type: PlanType;
+    /** Lifecycle status. */
+    status: PlanStatus;
+    /** Optional pricing tiers (1:N). Free/default plans have no prices. */
+    prices?: PriceDef[];
+    /** Feature entitlements included in this plan. */
+    features: Record<string, PlanFeatureValue>;
+    /** Slugs of addons that can be attached to this plan. */
+    available_addons?: string[];
+}
+/**
+ * Input type for `definePlan()`.
+ * - `slug` is omitted (inferred from dictionary key).
+ * - `status` is optional (defaults to `'active'`).
+ */
+type PlanDefInput = Omit<PlanDef, "slug" | "status" | "features"> & {
+    status?: PlanStatus;
+    features: Record<string, PlanFeatureValue>;
+    available_addons?: string[];
+};
+/**
+ * An add-on is a product purchased on top of a subscription.
+ * Maps to the `addons` table in the database.
+ */
+interface AddonDef {
+    /** Unique slug/identifier. */
+    slug: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Optional description. */
+    description?: string;
+    /** Billing type. */
+    type: "recurring" | "one_time";
+    /** Add-on pricing configurations (1:N). */
+    prices?: PriceDef[];
+    /** Feature entitlements this add-on modifies or grants. */
+    features: Record<string, AddonFeatureValue>;
+}
+/**
+ * Input type for `defineAddon()`.
+ * The `slug` is omitted (inferred from dictionary key).
+ */
+type AddonDefInput = Omit<AddonDef, "slug">;
+type DiscountType = "percent" | "amount";
+type DiscountDuration = "once" | "forever" | "repeating";
+interface DiscountDef {
+    /** The code the user enters at checkout (e.g., 'BLACKFRIDAY_24'). */
+    code: string;
+    /** Friendly name for invoices. */
+    name?: string;
+    /** 'percent' (0–100) or 'amount' (smallest currency unit). */
+    type: DiscountType;
+    /** The discount value. */
+    value: number;
+    /** How long the discount lasts. */
+    duration: DiscountDuration;
+    /** If duration is 'repeating', how many months. */
+    duration_in_months?: number;
+    /** Restrict to specific plan slugs. Empty = all. */
+    applies_to_plans?: string[];
+    /** Maximum number of redemptions globally. */
+    max_redemptions?: number;
+    /** Expiration date (ISO 8601). */
+    expires_at?: string;
+}
+/**
+ * The output of the Entitlement Engine.
+ * Answers: "Can the user do this?"
+ */
+interface CheckResult {
+    /** Is the action allowed? */
+    allowed: boolean;
+    /** Why was it allowed or denied? */
+    reason?: "feature_missing" | "limit_reached" | "past_due" | "included" | "overage_allowed";
+    /** How many units remain before hitting the limit. Infinity if unlimited. */
+    remaining?: number;
+    /** Estimated overage cost in the smallest currency unit. */
+    cost_estimate?: number;
+    /** Which sources granted access (plan and/or addon slugs). */
+    granted_by?: string[];
+}
+/**
+ * The structure of the `revstack.config.ts` file.
+ *
+ * Features and plans are dictionaries keyed by slug.
+ * The define helpers (`defineFeature`, `definePlan`) return input types
+ * without `slug` — it is inferred from the dictionary key.
+ */
+interface RevstackConfig {
+    /** Dictionary of all available features, keyed by slug. */
+    features: Record<string, FeatureDefInput>;
+    /** Dictionary of all plans, keyed by slug. */
+    plans: Record<string, PlanDefInput>;
+    /** Dictionary of available add-ons, keyed by slug. */
+    addons?: Record<string, AddonDefInput>;
+    /** Array of available coupons/discounts. */
+    coupons?: DiscountDef[];
+}
+
+/**
+ * @file define.ts
+ * @description Identity helpers for "Billing as Code" config authoring.
+ *
+ * These functions return their input unchanged — their sole purpose is to
+ * provide autocompletion, type narrowing, and compile-time validation
+ * when developers write their `revstack.config.ts`.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig, defineFeature, definePlan } from "@revstackhq/core";
+ *
+ * const features = {
+ *   seats: defineFeature({ name: "Seats", type: "static", unit_type: "count" }),
+ *   sso:   defineFeature({ name: "SSO",   type: "boolean", unit_type: "count" }),
+ * };
+ *
+ * export default defineConfig({
+ *   features,
+ *   plans: {
+ *     default: definePlan<typeof features>({
+ *       name: "Default",
+ *       is_default: true,
+ *       is_public: false,
+ *       type: "free",
+ *       features: {},
+ *     }),
+ *     pro: definePlan<typeof features>({
+ *       name: "Pro",
+ *       is_default: false,
+ *       is_public: true,
+ *       type: "paid",
+ *       prices: [{ amount: 2900, currency: "USD", billing_interval: "monthly" }],
+ *       features: {
+ *         seats: { value_limit: 5, is_hard_limit: true },
+ *         sso:   { value_bool: true },
+ *       },
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Define a feature with full type inference.
+ * Identity function — returns the input as-is.
+ */
+declare function defineFeature<T extends FeatureDefInput>(config: T): T;
+/**
+ * Define a Plan with optional compile-time feature key restriction.
+ *
+ * When called with a generic `F` (your feature dictionary type),
+ * the `features` object only accepts keys that exist in `F`.
+ *
+ * @typeParam F - Feature dictionary type. Pass `typeof yourFeatures` for strict keys.
+ *
+ * @example
+ * ```typescript
+ * // Strict mode — typos cause compile errors:
+ * definePlan<typeof features>({ ..., features: { seats: { value_limit: 5 } } });
+ *
+ * // Loose mode — any string key accepted (backwards compatible):
+ * definePlan({ ..., features: { anything: { value_bool: true } } });
+ * ```
+ */
+declare function definePlan<F extends Record<string, FeatureDefInput> = Record<string, FeatureDefInput>>(config: Omit<PlanDefInput, "features"> & {
+    features: F extends Record<string, FeatureDefInput> ? Partial<Record<keyof F, PlanFeatureValue>> : Record<string, PlanFeatureValue>;
+}): PlanDefInput;
+/**
+ * Define an Add-on with optional compile-time feature key restriction.
+ * Same generic pattern as `definePlan`.
+ *
+ * @typeParam F - Feature dictionary type for key restriction.
+ */
+declare function defineAddon<F extends Record<string, FeatureDefInput> = Record<string, FeatureDefInput>>(config: Omit<AddonDefInput, "features"> & {
+    features: F extends Record<string, FeatureDefInput> ? Partial<Record<keyof F, AddonFeatureValue>> : Record<string, AddonFeatureValue>;
+}): AddonDefInput;
+/**
+ * Define a discount/coupon with full type inference.
+ * Identity function — returns the input as-is.
+ */
+declare function defineDiscount<T extends DiscountDef>(config: T): T;
+/**
+ * Define the root billing configuration.
+ * Wraps the entire `revstack.config.ts` export for type inference.
+ */
+declare function defineConfig<T extends RevstackConfig>(config: T): T;
+
+/**
+ * @file engine.ts
+ * @description The Entitlement Engine — the logic core of Revstack.
+ *
+ * Determines if a user can access a feature based on their active Plan,
+ * purchased Add-ons, and subscription payment status. All decisions are
+ * pure, stateless computations with no side effects.
+ *
+ * @example
+ * ```typescript
+ * import { EntitlementEngine } from "@revstackhq/core";
+ *
+ * const engine = new EntitlementEngine(plan, addons, "active");
+ *
+ * // Single check
+ * const result = engine.check("seats", 4);
+ *
+ * // Batch check
+ * const results = engine.checkBatch({ seats: 4, ai_tokens: 12000 });
+ * ```
+ */
+
+/**
+ * The Entitlement Engine — evaluates feature access for a single customer.
+ *
+ * Instantiate with the customer's active plan, purchased add-ons, and
+ * current subscription status. Then call `check()` or `checkBatch()`
+ * to evaluate access.
+ *
+ * **Design decisions:**
+ * - Stateless: no mutation, no side effects. Safe to call from any context.
+ * - Add-on limits are *summed* with the base plan (e.g., plan gives 5 seats +
+ *   addon gives 3 = 8 total).
+ * - If ANY source sets `is_hard_limit: false`, the entire feature becomes soft-limited.
+ */
+declare class EntitlementEngine {
+    private plan;
+    private addons;
+    private subscriptionStatus;
+    /**
+     * @param plan - The customer's active base plan.
+     * @param addons - Active add-ons the customer has purchased.
+     * @param subscriptionStatus - Current payment/lifecycle state of the subscription.
+     */
+    constructor(plan: PlanDef, addons?: AddonDef[], subscriptionStatus?: SubscriptionStatus);
+    /**
+     * Verify if the customer has access to a specific feature.
+     *
+     * Aggregates limits from the base plan AND any active add-ons,
+     * then evaluates the customer's current usage against those limits.
+     *
+     * @param featureId - The feature slug to check (e.g., `"seats"`).
+     * @param currentUsage - Current consumption count (default: 0).
+     * @returns A `CheckResult` with the access decision and metadata.
+     */
+    check(featureId: string, currentUsage?: number): CheckResult;
+    /**
+     * Evaluate multiple features in a single pass.
+     *
+     * @param usages - Map of `featureSlug → currentUsage` to evaluate.
+     * @returns Map of `featureSlug → CheckResult`.
+     */
+    checkBatch(usages: Record<string, number>): Record<string, CheckResult>;
+}
+
+/**
+ * @file validator.ts
+ * @description Runtime validation for Revstack billing configurations.
+ *
+ * Validates the business logic invariants of a `RevstackConfig` object
+ * before it is synced to the backend. Catches misconfigurations early
+ * that TypeScript's type system cannot enforce (e.g., referencing
+ * undefined features, negative prices, duplicate slugs).
+ *
+ * @example
+ * ```typescript
+ * import { validateConfig, defineConfig } from "@revstackhq/core";
+ *
+ * const config = defineConfig({ features: {}, plans: {} });
+ * validateConfig(config); // throws RevstackValidationError if invalid
+ * ```
+ */
+
+/**
+ * Thrown when `validateConfig()` detects one or more invalid business
+ * logic rules in a billing configuration.
+ *
+ * The `errors` array contains all violations found — the validator
+ * collects every issue before throwing, so developers can fix them
+ * all at once instead of playing whack-a-mole.
+ */
+declare class RevstackValidationError extends Error {
+    /** All validation violations found in the config. */
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/**
+ * Validates a complete Revstack billing configuration.
+ *
+ * Checks the following invariants:
+ * 1. **Default plan** — Exactly one plan has `is_default: true`.
+ * 2. **Feature references** — Plans/addons only reference features defined in `config.features`.
+ * 3. **Non-negative pricing** — All price amounts and limits are ≥ 0.
+ * 4. **Discount bounds** — Percentage discounts have values in [0, 100].
+ *
+ * @param config - The billing configuration to validate.
+ * @throws {RevstackValidationError} If any violations are found.
+ */
+declare function validateConfig(config: RevstackConfig): void;
+
+export { type AddonDef, type AddonDefInput, type AddonFeatureValue, type BillingInterval, type CheckResult, type DiscountDef, type DiscountDuration, type DiscountType, EntitlementEngine, type FeatureDef, type FeatureDefInput, type FeatureType, type PlanDef, type PlanDefInput, type PlanFeatureValue, type PlanStatus, type PlanType, type PriceDef, type ResetPeriod, type RevstackConfig, RevstackValidationError, type SubscriptionStatus, type UnitType, defineAddon, defineConfig, defineDiscount, defineFeature, definePlan, validateConfig };