@formata/limitr 0.5.13

package/README.md

@@ -0,0 +1,145 @@
+# Limitr: Open-Source Monetization Policy
+**Limitr is an embedded, open-source policy engine for enforcing plans, limits, and usage in your application.**
+
+It is designed for AI products, developer tools, and open-source software where monetization logic must be:
+- inspectable
+- portable
+- deterministic
+- and not hard-coded into application logic
+
+> Limitr answers the question:
+> **"What is this customer allowed to consume, right now, and what happens if it exceeds the limit?"**
+
+- 👉 Jump to the [Quick Example](#example-seat-based-plan-enforcement-typescript)
+- Additional [info and examples](https://docs.stof.dev/applications/limitr)
+- [Limitr Cloud](https://limitr.dev)
+
+## What Limitr Gives You
+- Define plans, entitlements, and limits in a policy document — not application code
+- Enforce limits locally and offline, embedded directly in your app
+- Change limits without redeploying
+- Stripe-agnostic and billing-system-agnostic
+- Inspectable and auditable by developers and customers
+- Event-driven enforcement (usage changes, overages, denials)
+- Policy evolves independently from product code
+- Built on [Stof](https://docs.stof.dev), an open-source data + logic runtime
+
+## What Limitr Is Not
+- Not a billing system
+- Not a payment processor
+- Not a hosted SaaS requirement
+- Not a feature-flag system (outside of entitlements)
+
+Limitr enforces **truth** about usage and limits.
+Billing and payments can subscribe to Limitr’s events.
+
+Limitr is designed to integrate cleanly with existing systems, not replace them.
+
+## Why
+Most applications implement monetization logic in files like `limits.ts`:
+- seat limits
+- usage caps
+- plan checks
+- special cases and overrides
+
+Over time, this logic:
+- becomes tightly coupled to the app
+- requires redeploys to change pricing
+- is hard to audit or explain
+- breaks down with usage-based or AI pricing
+
+Payments systems (like Stripe) handle money, but not **enforcement**.
+
+Limitr separates **monetization policy** from application logic, so limits are:
+- explicit
+- portable
+- testable
+- and easy to evolve
+
+## Who Limitr Is For
+Limitr is a good fit if you are:
+- Building an AI or usage-based product
+- Implementing seat-based or credit-based pricing
+- Shipping developer tools or infrastructure
+- Supporting self-hosted or open-source deployments
+- Tired of hardcoding pricing logic in application code
+
+## Example: Seat-Based Plan Enforcement (TypeScript [JSR](https://jsr.io/@formata/limitr))
+```typescript
+import { Limitr } from 'jsr:@formata/limitr';
+
+// Load a Limitr policy from a DB, string, file, API, etc.
+// Stof is the default format, but can also be yaml, json, etc.
+const policy = await Limitr.new(`
+policy:
+  credits:
+    seat:
+      description: 'A single seat credit that can be tracked per customer.'
+  plans:
+    free:
+      entitlements:
+        seats:
+          description: 'Each customer (user, org, etc.) with this plan can have up to this many seats.'
+          limit:
+            credit: 'seat'
+            value: 1
+            increment: 1
+    paid:
+      entitlements:
+        seats:
+          description: 'Each customer (user, org, etc.) with this plan can have up to this many seats.'
+          limit:
+            credit: 'seat'
+            value: 3
+            increment: 1
+`, 'yaml');
+
+// Entitlements define features + limits (gated behaviors) on plans.
+// Meters are state stored per customer per entitlement.
+
+// Create/save/load customers (database, Stripe, etc.)
+await policy.addCustomer('cus_free_customer', 'free');
+await policy.addCustomer('cus_paid_customer', 'paid');
+
+// Perform entitlement checks, meter usage, etc.
+await policy.increment('cus_free_customer', 'seats'); // adds one seat
+await policy.increment('cus_paid_customer', 'seats'); // adds one seat
+
+// Add callbacks to the document directly or as a library function
+policy.doc.lib('App', 'meter_limit', (json: string) => {
+    const record = JSON.parse(json);
+    if (record.customer.plan === 'free' && record.entitlement === 'seats') {
+        console.log('FREE PLAN SEAT LIMIT HIT, current: ', record.customer.meters.seats.value, ' requested: ', record.invalid_value);
+    }
+});
+
+// Will return false and emit an meter-limit event in the doc (if App.meter_limit exists, it will also be called)
+if (await policy.increment('cus_free_customer', 'seats')) throw Error("will not get here");
+if (await policy.allow('cus_free_customer', 'seats', 2)) throw Error("cannot request 2 additional seats..");
+if (await policy.increment('cus_paid_customer', 'seats')) {
+    // paid customer can add a second seat
+} else {
+    throw Error("will not get here");
+}
+```
+```bash
+> deno run --allow-all typescript/examples/seats.ts
+FREE PLAN SEAT LIMIT HIT, current:  1  requested:  2
+FREE PLAN SEAT LIMIT HIT, current:  1  requested:  3
+```
+
+### What's happening here?
+- Plans define which entitlements a customer has
+- Entitlements define how a meter is allowed to change with limits
+- Meters are stored on each customer as state
+- Limitr enforces limits and emits events when limits are hit
+- The application decides how to respond (deny, warn, bill, notify)
+
+## License
+Apache 2.0. See LICENSE for details.
+
+## Contributing
+- Open issues or discussions on [GitHub](https://github.com/dev-formata-io/limitr)
+- Chat with us on [Discord](https://discord.gg/Up5kxdeXZt)
+
+> Reach out to info@stof.dev to contact us directly

package/dist/gate.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Internally ensure there's no overlap between policy calls.
+ * Supports both tail-append and head-prepend execution.
+ * WASM-safe promise gating.
+ */
+export declare class LimitrGate {
+    private head;
+    private tail;
+    /**
+     * Run at the back of this scheduler (non-priority).
+     */
+    run<T>(fn: () => Promise<T> | T): Promise<T>;
+    /**
+     * Run at the front of this scheduler.
+     */
+    runFront<T>(fn: () => Promise<T> | T): Promise<T>;
+}
+/**
+ * Helper function for waiting for the WebSocket to open.
+ */
+export declare function waitOnOpen(ws: WebSocket): Promise<void>;
+//# sourceMappingURL=gate.d.ts.map

package/dist/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../gate.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,qBAAa,UAAU;IAEnB,OAAO,CAAC,IAAI,CAAuC;IAGnD,OAAO,CAAC,IAAI,CAA+B;IAG3C;;OAEG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAO5C;;OAEG;IACH,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAepD;AAGD;;GAEG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBvD"}

package/dist/gate.js

@@ -0,0 +1,79 @@
+//
+// Copyright 2026 Formata, Inc. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+/**
+ * Internally ensure there's no overlap between policy calls.
+ * Supports both tail-append and head-prepend execution.
+ * WASM-safe promise gating.
+ */
+export class LimitrGate {
+    constructor() {
+        // Earliest scheduled work
+        this.head = Promise.resolve();
+        // Latest scheduled work
+        this.tail = this.head;
+    }
+    /**
+     * Run at the back of this scheduler (non-priority).
+     */
+    run(fn) {
+        const next = this.tail.then(fn);
+        this.tail = next.catch(() => { });
+        return next;
+    }
+    /**
+     * Run at the front of this scheduler.
+     */
+    runFront(fn) {
+        let release;
+        const blocker = new Promise(resolve => {
+            release = resolve;
+        });
+        const prevTail = this.tail;
+        this.tail = blocker;
+        const next = Promise.resolve()
+            .then(fn)
+            .finally(() => {
+            this.tail = prevTail;
+            release();
+        });
+        return next;
+    }
+}
+/**
+ * Helper function for waiting for the WebSocket to open.
+ */
+export function waitOnOpen(ws) {
+    if (ws.readyState === WebSocket.OPEN) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const onOpen = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(err);
+        };
+        const cleanup = () => {
+            ws.removeEventListener("open", onOpen);
+            ws.removeEventListener("error", onError);
+        };
+        ws.addEventListener("open", onOpen);
+        ws.addEventListener("error", onError);
+    });
+}
+//# sourceMappingURL=gate.js.map

package/dist/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../gate.ts"],"names":[],"mappings":"AAAA,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,gDAAgD;AAChD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,EAAE;AAGF;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAAvB;QACI,0BAA0B;QAClB,SAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;QAEnD,wBAAwB;QAChB,SAAI,GAAqB,IAAI,CAAC,IAAI,CAAC;IA+B/C,CAAC;IA5BG;;OAEG;IACH,GAAG,CAAI,EAAwB;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC;IAChB,CAAC;IAGD;;OAEG;IACH,QAAQ,CAAI,EAAwB;QAChC,IAAI,OAAoB,CAAC;QACzB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;YACxC,OAAO,GAAG,OAAO,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC;QACpB,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE;aACzB,IAAI,CAAC,EAAE,CAAC;aACR,OAAO,CAAC,GAAG,EAAE;YACV,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC;YACrB,OAAO,EAAE,CAAC;QACd,CAAC,CAAC,CAAC;QACP,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ;AAGD;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,EAAa;IACpC,IAAI,EAAE,CAAC,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;IACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACnC,MAAM,MAAM,GAAG,GAAG,EAAE;YAChB,OAAO,EAAE,CAAC;YACV,OAAO,EAAE,CAAC;QACd,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,CAAC,GAAU,EAAE,EAAE;YAC3B,OAAO,EAAE,CAAC;YACV,MAAM,CAAC,GAAG,CAAC,CAAC;QAChB,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,GAAG,EAAE;YACjB,EAAE,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACvC,EAAE,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC,CAAC;QACF,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpC,EAAE,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/limitr.d.ts

@@ -0,0 +1,2 @@
+export declare const limitrApi: Uint8Array<ArrayBuffer>;
+//# sourceMappingURL=limitr.d.ts.map

package/dist/limitr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limitr.d.ts","sourceRoot":"","sources":["../limitr.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS,yBAAyppkB,CAAC"}