@revstackhq/core 0.0.0-dev-20260215075706

package/LICENSE

@@ -0,0 +1,110 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2026 Revstack Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @revstackhq/core
+
+The shared type system and config authoring toolkit for [Revstack](https://revstack.dev) — Billing as Code for SaaS.
+
+This package provides the type-safe helper functions (`defineConfig`, `defineFeature`, `definePlan`, etc.) used to write `revstack.config.ts`, plus the runtime validation engine that powers the CLI and server-side config processing.
+
+## Installation
+
+```bash
+npm install @revstackhq/core
+```
+
+## Usage
+
+### Writing a Billing Config
+
+Use the identity helpers to get full autocompletion and compile-time validation in your `revstack.config.ts`:
+
+```typescript
+import { defineConfig, defineFeature, definePlan } from "@revstackhq/core";
+
+const features = {
+  seats: defineFeature({
+    name: "Seats",
+    type: "static",
+    unit_type: "count",
+  }),
+  ai_tokens: defineFeature({
+    name: "AI Tokens",
+    type: "metered",
+    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",
+          trial_period_days: 14,
+        },
+      ],
+      features: {
+        seats: { value_limit: 5, is_hard_limit: true },
+        ai_tokens: { value_limit: 1000, reset_period: "monthly" },
+      },
+    }),
+  },
+});
+```
+
+### Type-Safe Feature Keys
+
+When you pass `typeof features` as a generic to `definePlan<typeof features>(...)`, the `features` object is restricted to only the keys defined in your feature dictionary. Typos become compile-time errors:
+
+```typescript
+// ✅ Compiles — "seats" exists in features
+definePlan<typeof features>({ ..., features: { seats: { value_limit: 5 } } });
+
+// ❌ Compile error — "seets" is not a valid key
+definePlan<typeof features>({ ..., features: { seets: { value_limit: 5 } } });
+```
+
+## API Reference
+
+### Config Helpers
+
+| Function           | Description                                                   |
+| ------------------ | ------------------------------------------------------------- |
+| `defineConfig()`   | Wraps the root `revstack.config.ts` export for type inference |
+| `defineFeature()`  | Define a feature (static, metered, or boolean)                |
+| `definePlan()`     | Define a plan with optional compile-time feature key checks   |
+| `defineAddon()`    | Define an add-on (same generic pattern as `definePlan`)       |
+| `defineDiscount()` | Define a discount/coupon                                      |
+
+### Validation Engine
+
+The `validator` module provides runtime validation for billing configs, ensuring structural correctness before they're pushed to Revstack Cloud.
+
+### Types
+
+All shared TypeScript types are exported from the package root — `FeatureDefInput`, `PlanDefInput`, `PlanFeatureValue`, `RevstackConfig`, and more.
+
+## Architecture
+
+`@revstackhq/core` is a **zero-dependency** package designed to be shared across:
+
+- **`@revstackhq/cli`** — Uses the define helpers and validator at config-loading time.
+- **`@revstackhq/node`** — Depends on the shared type system for API contracts.
+- **User projects** — Imported directly in `revstack.config.ts` for type-safe authoring.
+
+## License
+
+FSL-1.1-MIT

package/dist/define.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @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 },
+ *       },
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+import type { FeatureDefInput, PlanDefInput, PlanFeatureValue, AddonDefInput, DiscountDef, RevstackConfig } from "@/types";
+/**
+ * Define a feature with full type inference.
+ * Identity function — returns the input as-is.
+ */
+export 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 } } });
+ * ```
+ */
+export 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.
+ */
+export 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, PlanFeatureValue>> : Record<string, PlanFeatureValue>;
+}): AddonDefInput;
+/**
+ * Define a discount/coupon with full type inference.
+ * Identity function — returns the input as-is.
+ */
+export declare function defineDiscount<T extends DiscountDef>(config: T): T;
+/**
+ * Define the root billing configuration.
+ * Wraps the entire `revstack.config.ts` export for type inference.
+ */
+export declare function defineConfig<T extends RevstackConfig>(config: T): T;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,WAAW,EACX,cAAc,EACf,MAAM,SAAS,CAAC;AAIjB;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,eAAe,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAErE;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CACxB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAE3E,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG;IACvC,QAAQ,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,GAC1C,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACtC,GACA,YAAY,CAEd;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EAE3E,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG;IACxC,QAAQ,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAC/C,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,GAC1C,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CACtC,GACA,aAAa,CAEf;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,WAAW,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAElE;AAID;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,cAAc,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAEnE"}

package/dist/define.js

@@ -0,0 +1,97 @@
+/**
+ * @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 },
+ *       },
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+// ─── Feature ─────────────────────────────────────────────────
+/**
+ * Define a feature with full type inference.
+ * Identity function — returns the input as-is.
+ */
+export function defineFeature(config) {
+    return config;
+}
+// ─── Plan (Typed against feature dictionary) ─────────────────
+/**
+ * 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 } } });
+ * ```
+ */
+export function definePlan(config) {
+    return config;
+}
+// ─── Add-on (Typed against feature dictionary) ───────────────
+/**
+ * Define an Add-on with optional compile-time feature key restriction.
+ * Same generic pattern as `definePlan`.
+ *
+ * @typeParam F - Feature dictionary type for key restriction.
+ */
+export function defineAddon(config) {
+    return config;
+}
+// ─── Discount ────────────────────────────────────────────────
+/**
+ * Define a discount/coupon with full type inference.
+ * Identity function — returns the input as-is.
+ */
+export function defineDiscount(config) {
+    return config;
+}
+// ─── Config Root ─────────────────────────────────────────────
+/**
+ * Define the root billing configuration.
+ * Wraps the entire `revstack.config.ts` export for type inference.
+ */
+export function defineConfig(config) {
+    return config;
+}

package/dist/engine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @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 });
+ * ```
+ */
+import type { CheckResult, PlanDef, AddonDef, SubscriptionStatus } from "@/types";
+/**
+ * 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.
+ */
+export 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>;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EAEP,QAAQ,EACR,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAuBjB;;;;;;;;;;;;GAYG;AACH,qBAAa,iBAAiB;IAO1B,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,kBAAkB;IAR5B;;;;OAIG;gBAEO,IAAI,EAAE,OAAO,EACb,MAAM,GAAE,QAAQ,EAAO,EACvB,kBAAkB,GAAE,kBAA6B;IAG3D;;;;;;;;;OASG;IACI,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,GAAE,MAAU,GAAG,WAAW;IAsFtE;;;;;OAKG;IACI,UAAU,CACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC;CAS/B"}

package/dist/engine.js

@@ -0,0 +1,163 @@
+/**
+ * @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 });
+ * ```
+ */
+// ─── Constants ───────────────────────────────────────────────
+/**
+ * Subscription statuses that block all feature access.
+ * Customers in these states must resolve their billing before
+ * the engine grants any entitlements.
+ */
+const BLOCKED_STATUSES = new Set([
+    "past_due",
+    "canceled",
+]);
+/** Immutable result returned for all checks when the subscription is blocked. */
+const BLOCKED_RESULT = Object.freeze({
+    allowed: false,
+    reason: "past_due",
+    remaining: 0,
+});
+// ─── Engine ──────────────────────────────────────────────────
+/**
+ * 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.
+ */
+export class EntitlementEngine {
+    plan;
+    addons;
+    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, addons = [], subscriptionStatus = "active") {
+        this.plan = plan;
+        this.addons = addons;
+        this.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, currentUsage = 0) {
+        // ── Gate: subscription status ────────────────────────────
+        if (BLOCKED_STATUSES.has(this.subscriptionStatus)) {
+            return BLOCKED_RESULT;
+        }
+        // ── 1. Gather entitlements from all sources ──────────────
+        const planEntitlement = this.plan.features[featureId];
+        const addonEntitlements = this.addons
+            .map((addon) => ({ slug: addon.slug, value: addon.features[featureId] }))
+            .filter((item) => item.value !== undefined);
+        // If neither plan nor add-ons have this feature
+        if (planEntitlement === undefined && addonEntitlements.length === 0) {
+            return { allowed: false, reason: "feature_missing" };
+        }
+        // ── 2. Aggregate values across all sources ───────────────
+        let totalLimit = 0;
+        let isInfinite = false;
+        let hasAccess = false;
+        let hardLimit = true;
+        let granted_by = this.plan.slug;
+        const processValue = (val, sourceSlug) => {
+            // Boolean feature
+            if (val.value_bool === true) {
+                hasAccess = true;
+                isInfinite = true;
+                granted_by = sourceSlug;
+                return;
+            }
+            // Numeric limit feature (static or metered)
+            if (val.value_limit !== undefined) {
+                hasAccess = true;
+                totalLimit += val.value_limit;
+                granted_by = sourceSlug;
+            }
+            // Hard/soft limit flag
+            if (val.is_hard_limit === false) {
+                hardLimit = false;
+            }
+        };
+        // Process base plan first
+        if (planEntitlement)
+            processValue(planEntitlement, this.plan.slug);
+        // Process add-ons (summation logic — limits stack)
+        for (const item of addonEntitlements) {
+            if (item.value === undefined)
+                continue;
+            processValue(item.value, item.slug);
+        }
+        // ── 3. Evaluate access ───────────────────────────────────
+        if (!hasAccess) {
+            return { allowed: false, reason: "feature_missing" };
+        }
+        if (isInfinite) {
+            return { allowed: true, remaining: Infinity, granted_by };
+        }
+        // ── 4. Evaluate limits ───────────────────────────────────
+        if (currentUsage < totalLimit) {
+            return {
+                allowed: true,
+                reason: "included",
+                remaining: totalLimit - currentUsage,
+                granted_by,
+            };
+        }
+        // Limit reached — check if overage is allowed
+        if (!hardLimit) {
+            return {
+                allowed: true,
+                reason: "overage_allowed",
+                remaining: 0,
+            };
+        }
+        return { allowed: false, reason: "limit_reached", remaining: 0 };
+    }
+    /**
+     * Evaluate multiple features in a single pass.
+     *
+     * @param usages - Map of `featureSlug → currentUsage` to evaluate.
+     * @returns Map of `featureSlug → CheckResult`.
+     */
+    checkBatch(usages) {
+        const results = {};
+        for (const [featureId, usage] of Object.entries(usages)) {
+            results[featureId] = this.check(featureId, usage);
+        }
+        return results;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "@/types";
+export * from "@/define";
+export * from "@/engine";
+export * from "@/validator";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "@/types";
+export * from "@/define";
+export * from "@/engine";
+export * from "@/validator";

package/dist/test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=test.d.ts.map

package/dist/test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../src/test.ts"],"names":[],"mappings":""}

package/dist/test.js

@@ -0,0 +1,14 @@
+import { EntitlementEngine } from "@/engine";
+const planPro = {
+    name: "Pro",
+    id: "pro",
+    price: 2900,
+    currency: "USD",
+    interval: "month",
+    features: {
+        sso: true,
+        ai_tokens: { limit: 50_000, unitPrice: 0.01, included: true },
+    },
+};
+const engine = new EntitlementEngine(planPro);
+console.log(engine.check("ai_tokens", 60_000));

package/dist/types.d.ts

@@ -0,0 +1,220 @@
+/**
+ * @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).
+ */
+export type FeatureType = "boolean" | "static" | "metered";
+/**
+ * The unit of measurement for a feature.
+ * Used for display, analytics, and billing calculations.
+ */
+export type UnitType = "count" | "bytes" | "seconds" | "tokens" | "requests" | "custom";
+/**
+ * How often a feature's usage counter resets.
+ */
+export type ResetPeriod = "monthly" | "yearly" | "never";
+/**
+ * Billing interval for a plan's price.
+ */
+export 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.
+ */
+export 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.
+ */
+export type PlanStatus = "draft" | "active" | "archived";
+/**
+ * The lifecycle state of a customer's subscription.
+ * Used by the EntitlementEngine to gate access based on payment status.
+ */
+export 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`.
+ */
+export 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.
+ */
+export 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`.
+ */
+export 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;
+}
+/**
+ * Defines the pricing for a plan.
+ * Maps to the `prices` table in the database.
+ */
+export 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`.
+ */
+export 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>;
+}
+/**
+ * Input type for `definePlan()`.
+ * - `slug` is omitted (inferred from dictionary key).
+ * - `status` is optional (defaults to `'active'`).
+ */
+export type PlanDefInput = Omit<PlanDef, "slug" | "status" | "features"> & {
+    status?: PlanStatus;
+    features: Record<string, PlanFeatureValue>;
+};
+/**
+ * An add-on is a product purchased on top of a subscription.
+ * Maps to the `addons` table in the database.
+ */
+export 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. */
+    price: PriceDef;
+    /** Feature entitlements this add-on grants. */
+    features: Record<string, PlanFeatureValue>;
+}
+/**
+ * Input type for `defineAddon()`.
+ * The `slug` is omitted (inferred from dictionary key).
+ */
+export type AddonDefInput = Omit<AddonDef, "slug">;
+export type DiscountType = "percent" | "amount";
+export type DiscountDuration = "once" | "forever" | "repeating";
+export 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?"
+ */
+export 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 source granted access (plan or addon slug). */
+    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.
+ */
+export 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[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * @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".
+ */
+export {};

package/dist/validator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @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
+ * ```
+ */
+import type { RevstackConfig } from "@/types";
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function validateConfig(config: RevstackConfig): void;
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAoB,MAAM,SAAS,CAAC;AAIhE;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,qDAAqD;IACrD,SAAgB,MAAM,EAAE,MAAM,EAAE,CAAC;gBAErB,MAAM,EAAE,MAAM,EAAE;CAU7B;AAqGD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAuC3D"}

package/dist/validator.js

@@ -0,0 +1,134 @@
+/**
+ * @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
+ * ```
+ */
+// ─── Error Class ─────────────────────────────────────────────
+/**
+ * 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.
+ */
+export class RevstackValidationError extends Error {
+    /** All validation violations found in the config. */
+    errors;
+    constructor(errors) {
+        const summary = errors.length === 1
+            ? `Revstack config validation failed: ${errors[0]}`
+            : `Revstack config validation failed with ${errors.length} errors:\n  - ${errors.join("\n  - ")}`;
+        super(summary);
+        this.name = "RevstackValidationError";
+        this.errors = errors;
+    }
+}
+// ─── Feature Reference Validation ────────────────────────────
+/**
+ * Collects errors for feature keys in a product that don't exist
+ * in the root feature dictionary.
+ */
+function validateFeatureReferences(productType, productSlug, features, knownFeatureSlugs, errors) {
+    for (const featureSlug of Object.keys(features)) {
+        if (!knownFeatureSlugs.has(featureSlug)) {
+            errors.push(`${productType} "${productSlug}" references undefined feature "${featureSlug}".`);
+        }
+    }
+}
+// ─── Pricing Validation ──────────────────────────────────────
+/**
+ * Validates that prices within a plan are non-negative.
+ */
+function validatePlanPricing(planSlug, prices, features, errors) {
+    if (prices) {
+        for (const price of prices) {
+            if (price.amount < 0) {
+                errors.push(`Plan "${planSlug}" has a negative price amount (${price.amount}).`);
+            }
+        }
+    }
+    for (const [featureSlug, value] of Object.entries(features)) {
+        if (value.value_limit !== undefined && value.value_limit < 0) {
+            errors.push(`Plan "${planSlug}" → feature "${featureSlug}" has a negative value_limit (${value.value_limit}).`);
+        }
+    }
+}
+// ─── Default Plan Validation ─────────────────────────────────
+/**
+ * Ensures exactly one plan has `is_default: true`.
+ */
+function validateDefaultPlan(config, errors) {
+    const defaultPlans = Object.entries(config.plans).filter(([, plan]) => plan.is_default);
+    if (defaultPlans.length === 0) {
+        errors.push("No default plan found. Every project must have exactly one plan with is_default: true.");
+    }
+    else if (defaultPlans.length > 1) {
+        const slugs = defaultPlans.map(([slug]) => slug).join(", ");
+        errors.push(`Multiple default plans found (${slugs}). Only one plan can have is_default: true.`);
+    }
+}
+// ─── Discount Validation ─────────────────────────────────────
+/**
+ * Validates discount-specific business rules.
+ */
+function validateDiscounts(config, errors) {
+    if (!config.coupons)
+        return;
+    for (const coupon of config.coupons) {
+        if (coupon.type === "percent" && (coupon.value < 0 || coupon.value > 100)) {
+            errors.push(`Discount "${coupon.code}" has an invalid percentage value (${coupon.value}). Must be 0–100.`);
+        }
+        if (coupon.type === "amount" && coupon.value < 0) {
+            errors.push(`Discount "${coupon.code}" has a negative amount value (${coupon.value}).`);
+        }
+    }
+}
+// ─── Main Validator ──────────────────────────────────────────
+/**
+ * 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.
+ */
+export function validateConfig(config) {
+    const errors = [];
+    const knownFeatureSlugs = new Set(Object.keys(config.features));
+    // ── Default Plan ───────────────────────────────────────────
+    validateDefaultPlan(config, errors);
+    // ── Plans ──────────────────────────────────────────────────
+    for (const [slug, plan] of Object.entries(config.plans)) {
+        validateFeatureReferences("Plan", slug, plan.features, knownFeatureSlugs, errors);
+        validatePlanPricing(slug, plan.prices, plan.features, errors);
+    }
+    // ── Add-ons ────────────────────────────────────────────────
+    if (config.addons) {
+        for (const [slug, addon] of Object.entries(config.addons)) {
+            validateFeatureReferences("Addon", slug, addon.features, knownFeatureSlugs, errors);
+        }
+    }
+    // ── Discounts ──────────────────────────────────────────────
+    validateDiscounts(config, errors);
+    // ── Throw if any violations were collected ─────────────────
+    if (errors.length > 0) {
+        throw new RevstackValidationError(errors);
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@revstackhq/core",
+  "version": "0.0.0-dev-20260215075706",
+  "private": false,
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/node": "^20.11.30",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.1",
+    "eslint-plugin-turbo": "^2.7.1",
+    "typescript": "5.9.2",
+    "typescript-eslint": "^8.50.0",
+    "vitest": "^4.0.18",
+    "@revstackhq/eslint-config": "0.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint \"src/**/*.{ts,tsx}\"",
+    "test": "vitest run"
+  }
+}