@byo-oss/entitlementsv0.2.0

Entitlements

May this organization do it, and how much is left?

Plans, features, limits and usage for your organizations, kept in your own database. Declare the catalog once, and stop scattering plan names and limits across the API, the web app and the pricing page.

npm i @byo-oss/entitlements
Read the docsGitHub ↗What it covers
requests today640 / 1,000
features
API keysallowed
Audit lognot in plan
SSOnot in plan
limits
seats3
agents2
hasFeature → audit log · not in plan · upgrade to Pro or Team

Illustration. Pick a plan to see what it allows.

Relies on

peerDependencies · @byo-oss/entitlements 0.2.0
better-authrequired
peer · ^1.7.7

Organizations, sessions and your database adapter. Usage counters use its guarded incrementOne.

@better-auth/corerequired
peer · ^1.7.7

The after-commit hooks behind events. Install it at the same version as better-auth.

better-callrequired
peer · ^1.4.0

The endpoint layer under better-auth, which already depends on it.

zodrequired
peer · ^4.0.0

Validation uses your app's copy. An app still on zod 3 has to move to zod 4 first.

organizationrequired
better-auth plugin

Entitlements belong to organizations, and your staff are an organization's members.

@better-auth/stripeoptional
peer · ^1.7.7

The ./stripe billing source reads its subscriptions and reuses its webhook.

@byo-oss/notificationsoptional
BYO package

Tell an organization's owners when it reaches a limit.

reactoptional
peer · >=18

The ./react hook, <EntitlementGate /> and <UsageMeter />.

vitestoptional
peer · >=3

Only for ./testing, the contract suite for billing sources you write.

[01] what it covers

The whole domain, at a young product's depth.

Built to the BYO conventions from day one: your identity, your permissions, your database.

01

One typed catalog

Features, limits and plans declared once. The API, the web app and a static pricing page import the same file, and a typo is a type error.

02

Billing stays where it is

Stripe, through @better-auth/stripe, knows which plan an organization bought. Entitlements keeps a snapshot of it and decides what the plan allows.

03

Atomic usage counters

consumeUsage is one guarded increment: no read-then-write race, and a refused call never counts against the limit.

04

Never a 500 for a refusal

Every check returns allowed, a reason and the plans that would unlock it, so the app can show the upgrade instead of an error.

05

Staff overrides

Comp a feature, raise a limit or move an organization to another plan, with a reason, an optional expiry and an audit trail.

06

Headless first

A hook owns the state and the calls. A gate and a usage meter on shadcn variables sit on top, every string overridable.

[02] part of byo

Better with the others.

Packages share one identity, one permission model and one notification path, so each one you add makes the others more useful.

  • @byo-oss/entitlementslimit-reached noticesnotificationsshipped
  • @byo-oss/entitlementsplan state@better-auth/stripeyour app
  • @byo-oss/entitlementsresync + cleanupcore · sweepAllshipped
  • @byo-oss/entitlementsplan + override eventsonEvent · after commitshipped
[03] outgrowing this

A way out, planned from the start.

When you bill by usage, sell credits or add-ons, or need non-engineers to edit plans, you move to a dedicated entitlements service. Entitlements ships with exportEntitlementsData, a documented schema, a field mapping to Stripe Entitlements and Autumn, and a clean uninstall.

Stripe Entitlementsfield mapping in the docs
Autumnfield mapping in the docs
Schematicnamed in the docs
Stiggnamed in the docs
↑↓ move↵ openesc closeall byo docs