Quickstart

Install the SDK, write a policy, make your first call. About five minutes.

Limitr is an embedded engine. This means all of the action happens directly within your app, just as if it were your own code.

Install

Execution happens as WebAssembly. Each SDK is a thin wrapper around it.

npm i @formata/limitr

Policy-as-Document

A Limitr Policy is a config document that defines your credit definitions, plan configurations, usage limits, prices, etc.

Here, it's defined as JSON, but YAML, TOML, or Stof also work fine.

note

If you're using Limitr Cloud, policies are fully managed, versioned, and live-editable from the app — you don't need to write them manually, unless you'd like a static/offline fallback or test policy.

"policy": {
    "credits": {
        "seat":  { "price": { "amount": 19.99 } },
        "token": { "price": { "amount": 0.00004 }, "overhead": 0.000003 }
    },
    "plans": {
        "starter": {
            "label": "Starter Plan",
            "entitlements": {
                "seats": {
                    "limit": { "credit": "seat", "value": 3 }
                },
                "ai-chat": {
                    "limit": { "credit": "token", "value": 1000, "mode": "soft", "resets": true, "reset_inc": "1hr" }
                }
            }
        }
    }
}

This policy has one starter plan with two entitlements: seats and ai-chat. Customers on the starter plan are entitled to 3 seats max and 1000 included tokens per hour, then are charged for every token over that at the defined price.

Run it

quickstart

import { Limitr } from '@formata/limitr';

const policy = await Limitr.new(`"policy": { ... }`, 'json');
// For Limitr Cloud: await Limitr.cloud({ token: apiKey }) instead. Nothing below changes.

// A customer object owns state information: meter values, overrides, plan reference, etc.
await policy.createCustomer('acme_corp', 'starter'); 
 
if (await policy.allow('acme_corp', 'seats', 2)) {
    console.log('2 seats — allowed');
}
if (await policy.allow('acme_corp', 'chat_tokens', 10000)) {
    console.log('10,000 tokens — allowed, charged for 9k in overage');
}

if (await policy.allow('acme_corp', 'seats', 2)) {
    throw Error('unexpectedly allowed');
} else {
    console.log('blocked, over the limit');
}

Output

What just happened

We created one customer, acme_corp, on the starter plan — enforcing 3 seats max, 1000 included tokens per hour, and $0.00004 per token for everything over.

The code is written such that we could change, for example, the ai-chat soft limit to hard for some customers/plans and allow for 10k would have returned false.

That change would be a config only change, and your code would remain the way it currently is.

This is a small example, but the same pattern holds for much more involved use cases.

tip

Integrating Limitr into your code, in the vast majority of use-cases, involves just three things: customer ID (user/agent state object), entitlement name, and usage quantity.

Plans are groups of entitlements. An entitlement can map to a feature, a meter for monetization, a monthly or daily limit, etc. and can always be stacked to work together.

One common pattern for example: a hard limit on self-counted tokens to gate AI usage before vendor calls, then soft limit entitlements (value of 0, so everything is overage) for accurately billing AI input & output tokens based on the real counts that the vendor responds with.

An entitlement without a limit is a boolean flag — quantity can be ommitted in that case.