---
title: "@playstack/entitlements"
description: "Source-projected boolean capabilities and numeric limits with explicit subject enforcement."
tags: ["package","identity","entitlements","authorization","limits","pro"]
---

{/* package-access:start */}

> **Pro.** Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/entitlements` projects grants from billing, licensing, registration, staff, or another authority into stable capabilities and limits. It does not own plans, prices, authentication, feature flags, or provider side effects.

```ts
const registry = defineEntitlements({
  'packages.pro': { kind: 'boolean' },
  'tokens.maximum': { kind: 'number' },
})

const entitlements = createEntitlements({
  registry,
  persistence,
  events,
  clock,
  ids,
})

await entitlements.replaceSource({
  subject: { type: 'account', id: accountId },
  source: { type: 'stripe', id: subscriptionId },
  grants: [{ entitlement: 'packages.pro', value: true }],
})

const decisions = await entitlements.resolveMany(
  { type: 'account', id: accountId },
  ['packages.pro', 'tokens.maximum'],
)
const snapshot = await entitlements.snapshot({
  type: 'account',
  id: accountId,
})
```

Boolean grants combine with OR and numeric grants by maximum. Replacing one source affects only that projection; replacing it with no grants revokes it. The package emits transactional `entitlements.grants.replaced` events and publishes an ejectable Prisma fragment plus `@playstack/entitlements/prisma`.

Both bulk reads use one persistence lookup rather than querying once per
entitlement. `replaceSourceInTransaction()` lets Billing or another
same-database authority update grants on an existing transaction. It verifies
the transaction kind and emits the ordinary grants-replaced event on that unit
of work; separate stores use the normal idempotent source replacement path.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

```sh
npm install --save-exact @playstack/entitlements@0.1.0-beta.1
```

Check the peer requirements below before choosing a runtime or provider.

{/* package-install:end */}

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/entitlements@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/entitlements` | `./dist/index.d.ts` |
| `@playstack/entitlements/errors` | `./dist/errors.d.ts` |
| `@playstack/entitlements/prisma` | `./dist/prisma.d.ts` |
| `@playstack/entitlements/testing` | `./dist/testing.d.ts` |
| `@playstack/entitlements/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}