SDK Quick Reference

Index of every method on the Limitr class, and where to find more information.

A complete index of every method on the Limitr class. Each entry links to the page where the method is fully documented with parameters, return types, and examples.

The SDK surface maps directly to policy concepts — if you know what you're trying to do, the concept page is usually the right place to start. This page is for when you know the method name and want to find it fast.

Initialization

Method	Description
`Limitr.new(policy, format, validate?)`	Async constructor. Loads a policy from a string, object, or binary. Validates by default. → Policy Reference
`Limitr.cloud(options)`	Connect to Limitr Cloud. Returns a fully initialized `Limitr` instance backed by the Cloud WebSocket. → Cloud Quick Start
`policy.valid()`	Returns `[boolean, string]` — whether the policy is valid and the current error if not. → Policy Reference
`policy.version()`	Returns the Limitr engine version string.
`policy.close()`	Flush pending state and close the Cloud WebSocket connection. → Cloud Quick Start
`policy.doc`	The underlying `StofDoc`. Use for direct serialization: `policy.doc.stringify('yaml')`, `policy.doc.record()`. → Policy Reference

Enforcement

The methods your application calls on every request. These are on the hot path.

Method	Description
`policy.allow(customer, entitlement, value?, event?)`	Enforce and meter in one operation. Returns `false` if the limit blocks the request. Fires `meter-limit` or `meter-overage` events. → Enforcement
`policy.check(customer, entitlement, value?)`	Read-only pre-authorization. Returns whether `allow()` would succeed without consuming quota. → Enforcement
`policy.increment(customer, entitlement, event?)`	Consume one `limit.increment` unit. Use for countable resources: seats, API calls, documents. → Enforcement
`policy.decrement(customer, entitlement, event?)`	Release one `limit.increment` unit. Use when a resource is returned: seat removed, file deleted. → Enforcement
`policy.set(customer, entitlement, value, event?)`	Set the meter to an absolute value. Use for state-based resources where you know the total, not the delta. → Enforcement
`policy.checkIncrement(customer, entitlement)`	Read-only. Whether `increment()` would succeed.
`policy.checkDecrement(customer, entitlement)`	Read-only. Whether `decrement()` would succeed.

Reading state

Method	Description
`policy.value(customer, entitlement, percent?, grants?)`	Current meter value. Pass `percent: true` for a 0–100 percentage of the limit. → Enforcement
`policy.remaining(customer, entitlement, percent?, grants?)`	Remaining balance (`limit - value`). Includes grant balances by default. → Enforcement
`policy.limit(customer, entitlement, grants?)`	The enforced limit value, including any customer override. → Enforcement
`policy.cost(id, entitlement)`	The rune cost of one `increment()` on this entitlement. → Enforcement

Events

Method	Description
`policy.addHandler(name, handler)`	Register a named event handler. Receives all `meter-changed`, `meter-limit`, and `meter-overage` events, plus any custom notification events. → Enforcement
`policy.removeHandler(name)`	Remove a handler by name. → Enforcement
`policy.clearHandlers()`	Remove all registered handlers. → Enforcement

Customers

Method	Description
`policy.createCustomer(id, plan?, type?, label?, refs?, alts?, metadata?)`	Create a new customer. Fires `customer-set`. → Customers
`policy.ensureCustomer(id, plan?, type?, label?, refs?, alts?, metadata?)`	Create a customer only if they don't already exist. Returns `true` if created. → Customers
`policy.customer(id)`	Full customer object: plan, meters, grants, overrides, metadata. Accepts primary ID or any alt ID. → Customers
`policy.customers()`	All customers as a single record. The complete state snapshot for persistence. → Customers
`policy.customerMetadata(id)`	The metadata object for a customer. → Customers
`policy.customerRefs(id)`	The list of referenced customer IDs. → Customers
`policy.setCustomerPlan(id, planId, overwrite_meters?)`	Change a customer's plan. Resets meters by default. → Customers
`policy.setCustomer(customer, event?)`	Set a customer by record object or JSON string. → Customers
`policy.removeCustomer(id)`	Remove a customer from the local policy. Fires `customer-removed`. → Customers
`policy.addAltID(existing, alt, event?)`	Add an alternative ID to an existing customer. → Customers
`policy.removeAltID(alt, event?)`	Remove an alternative ID. → Customers
`policy.loadCustomers(customers)`	Load many customer records at once. For restoring persisted state. → Customers
`policy.ensureCustomerPlanQuantity(id)`	Increment the plan subscription entitlement if the meter is below 1. Use to trigger subscription billing. → Customers

Entitlements & overrides

Method	Description
`policy.entitlement(id, entitlement)`	The entitlement record for a plan or customer, with the resolved limit applied. → Entitlements
`policy.createCustomerOverride(id, entitlement, value?, expires_on?, credit?, mode?, increment?, resets?, reset_inc?)`	Replace a customer's limit for a specific entitlement. Returns override node ID. → Entitlements
`policy.removeCustomerOverride(id, entitlement)`	Remove a customer override. Customer reverts to plan limit. → Entitlements

Credits

Method	Description
`policy.credit(id)`	The credit record for a given credit ID. → Credits
`policy.creditFor(id, entitlement)`	The credit backing a specific entitlement, resolved from a plan or customer ID. → Credits
`policy.creditExchange(inCredit, outCredit, value?)`	Convert a value from one credit to another via the exchange table. Returns `null` if no path exists. → Exchange
`policy.remainingCredit(customerId, credit)`	Total remaining balance of a credit across all of a customer's grants, after exchange conversion. → Credits

Plans

Method	Description
`policy.plan(id, def?)`	Plan record for a plan ID or customer ID. Falls back to the default plan if `def` is `true`. → Plans
`policy.defaultPlan()`	The plan marked `default: true`, if any. → Plans
`policy.setPlan(id, planStof)`	Add or replace a plan by ID. Fires `plan-set`. → Plans
`policy.deletePlan(id)`	Remove a plan by ID. Fires `plan-removed`. → Plans
`policy.planPeriod(id)`	Period string for a plan: `'monthly'`, `'yearly'`, `'weekly'`, `'daily'`. → Plans
`policy.planTrialPeriod(id)`	Trial period in milliseconds, or `null`. → Plans
`policy.planSubEntitlementName(id)`	The subscription entitlement name for a plan. → Plans

Topups & grants

Method	Description
`policy.applyCustomerTopup(customerId, topupId)`	Apply a plan topup to a customer, creating a grant. → Topups & Grants
`policy.ensureCustomerIncludedTopups(id, event?)`	Sync included topup grants with the customer's current plan. Call after plan changes. → Topups & Grants

Margin

Method	Description
`policy.customerMarginSnapshot(customerId)`	Live margin breakdown for a customer: revenue, cost, and margin per entitlement. → Margin
`policy.marginSnapshot(planId, entitlements)`	Project margin for a plan given hypothetical entitlement values. For pricing decisions and plan design. → Margin

Notifications

Method	Description
`policy.setNotifications(contents, format?)`	Load notification definitions into the policy at runtime. → Notifications

Cloud

Method	Description
`policy.addVoucher(voucher, handler?)`	Authenticate a Limitr voucher (proxy customer) for Limitr Network. → Cloud Quick Start
`policy.docCall(path, ...args)`	Call a Stof function in the policy document directly. For advanced use cases.

Initialization​

Enforcement​

Reading state​

Events​

Customers​

Entitlements & overrides​

Credits​

Plans​

Topups & grants​

Margin​

Notifications​

Cloud​