@prsm/entitle 1.0.0

package/README.md

@@ -0,0 +1,183 @@
+<p align="center">
+  <img src="logo.svg" width="80" height="80" alt="entitle logo">
+</p>
+
+<h1 align="center">@prsm/entitle</h1>
+
+<p align="center">
+  <a href="https://github.com/prsmjs/entitle/actions/workflows/test.yml"><img src="https://github.com/prsmjs/entitle/actions/workflows/test.yml/badge.svg" alt="test"></a>
+  <a href="https://www.npmjs.com/package/@prsm/entitle"><img src="https://img.shields.io/npm/v/@prsm/entitle" alt="npm"></a>
+</p>
+
+Plan-based entitlements and feature gating, backed by postgres. Declare your pricing tiers once, assign subjects to plans, and ask at runtime what a subject is allowed to do. Entitlements resolve live on every call, so an upgrade, a negotiated override, or a crossed usage threshold takes effect immediately rather than at the next restart.
+
+It pairs with [@prsm/meter](https://www.npmjs.com/package/@prsm/meter): meter answers how much a subject has used, entitle answers what their plan allows and where the ceiling is. Hand entitle a meter and `check()` reads usage live and compares it to the resolved limit.
+
+## Installation
+
+```bash
+npm install @prsm/entitle pg
+```
+
+## Quick start
+
+```js
+import { createEntitlements, postgresDriver } from "@prsm/entitle"
+import pg from "pg"
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
+
+const entitlements = createEntitlements({
+  driver: postgresDriver({ pool }),
+  defaultPlan: "free",
+  plans: {
+    free: {
+      features: { api_access: true, export_csv: false, sso: false },
+      limits: { tokens: 100_000, seats: 1 },
+    },
+    pro: {
+      features: { api_access: true, export_csv: true, sso: false },
+      limits: { tokens: 5_000_000, seats: 10 },
+    },
+    enterprise: {
+      features: { api_access: true, export_csv: true, sso: true },
+      limits: { tokens: null, seats: null }, // null means unlimited
+    },
+  },
+})
+
+await entitlements.setup() // create tables if they do not exist; idempotent
+```
+
+Gating a feature and a quota on a request:
+
+```js
+async function exportReport(account) {
+  if (!(await entitlements.can(account.id, "export_csv"))) {
+    throw new Error("CSV export is not available on your plan")
+  }
+  // ...
+}
+```
+
+Assigning plans and per-subject overrides as customers upgrade or negotiate:
+
+```js
+await entitlements.assign(account.id, "pro")              // takes effect immediately
+await entitlements.override(account.id, { limits: { seats: 50 } }) // the enterprise customer who negotiated more seats
+await entitlements.override(account.id, { features: { sso: true } })
+```
+
+## Composing with the meter
+
+`check()` is the seam between the two packages. Entitle resolves the limit; meter supplies live usage. Pass a `@prsm/meter` instance and check a limit key that is also a meter metric:
+
+```js
+import { createMeter, postgresDriver as meterPostgres } from "@prsm/meter"
+
+const meter = createMeter({
+  driver: meterPostgres({ pool }),
+  metrics: { tokens: { unit: "tokens", aggregate: "sum" } },
+})
+
+const entitlements = createEntitlements({
+  driver: postgresDriver({ pool }),
+  defaultPlan: "free",
+  plans: { /* ... */ },
+  meter,
+})
+
+const quota = await entitlements.check(account.id, "tokens")
+// { allowed: true, used: 84210, remaining: 4915790, limit: 5000000, unit: "tokens", feature: "tokens" }
+
+if (!quota.allowed) throw new Error("monthly token limit reached")
+```
+
+Because the limit is resolved from the plan and the usage is read from the meter on every call, the same code path enforces a tightened plan, a granted override, and a depleting quota without any of it being baked in at startup.
+
+## Plans, assignments, and overrides
+
+The **plan catalog** is declared once at construction, the way you declare your pricing tiers in code. A plan grants:
+
+- **features** - a map of capability flags (`{ sso: true, export_csv: false }`), read with `can()`.
+- **limits** - a map of numeric ceilings keyed by name (`{ tokens: 5_000_000, seats: 10 }`), read with `limit()` and enforced with `check()`. A `null` limit means unlimited.
+
+**Assignments** (which plan a subject is on) and **overrides** (per-subject adjustments) live in postgres and are mutable at runtime. An override shallow-merges over the plan, so you specify only what differs. A subject with no assignment gets `defaultPlan`.
+
+Resolved entitlements are cached per subject for a short, configurable window (`cacheTtl`, default `"10s"`) and the cache is invalidated immediately on `assign`, `override`, and `clearOverride`, so the instance making a change sees it at once and other instances converge within the TTL. Set `cacheTtl: 0` to read postgres on every call.
+
+## API
+
+### `createEntitlements({ driver, plans, defaultPlan, meter?, cacheTtl?, tracer? })`
+
+Creates a resolver. `driver` is `postgresDriver({ pool })` or `memoryDriver()`. `plans` is the catalog; `defaultPlan` must be one of its keys. `meter` is an optional `@prsm/meter` instance, required only for `check()`. `cacheTtl` accepts ms or a string like `"10s"`. `tracer` is an optional `@prsm/trace` tracer.
+
+### `entitlements.setup()`
+
+Creates the backing tables if they do not exist. Idempotent.
+
+### `entitlements.assign(subject, plan)`
+
+Assigns a subject to a plan. Takes effect immediately.
+
+### `entitlements.override(subject, { features?, limits? })`
+
+Layers a per-subject override on top of the plan. Shallow-merges; pass only what differs.
+
+### `entitlements.clearOverride(subject)`
+
+Removes the subject's override.
+
+### `entitlements.can(subject, feature)`
+
+Returns whether a capability flag is granted (`false` for an ungranted or unknown feature).
+
+### `entitlements.limit(subject, key)`
+
+Returns the numeric ceiling for a limit key after overrides, or `null` for an unlimited or undeclared limit. Does not read usage.
+
+### `entitlements.check(subject, key, usageQuery?)`
+
+Resolves the limit and reads live usage from the meter, returning `{ allowed, used, remaining, limit, unit, feature }`. `usageQuery` is forwarded to `meter.usage` (for example `{ period: "day" }`). Requires a `meter`.
+
+### `entitlements.plan(subject)`
+
+Returns the subject's effective plan name.
+
+### `entitlements.describe(subject)`
+
+Returns the full effective snapshot `{ plan, features, limits }`, for a settings or billing page.
+
+### `entitlements.close()`
+
+Releases driver resources.
+
+## Storage
+
+Two postgres tables, prefixed `entitle_` by default (pass `prefix` to `postgresDriver` to run several resolvers in one database):
+
+- `entitle_assignments` maps a subject to a plan.
+- `entitle_overrides` holds each subject's override as JSON.
+
+The plan catalog itself is code, not data, so it is not stored.
+
+## Testing
+
+The `memoryDriver` mirrors the postgres driver and needs no infrastructure:
+
+```js
+import { createEntitlements, memoryDriver } from "@prsm/entitle"
+
+const entitlements = createEntitlements({
+  driver: memoryDriver(),
+  defaultPlan: "free",
+  plans: { free: { features: { api_access: true }, limits: { seats: 1 } } },
+})
+await entitlements.setup()
+```
+
+It is not durable; use it for tests, not production.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@prsm/entitle",
+  "version": "1.0.0",
+  "description": "Plan-based entitlements and feature gating, resolved at runtime, backed by postgres",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./postgres": {
+      "types": "./types/postgresDriver.d.ts",
+      "default": "./src/postgresDriver.js"
+    },
+    "./memory": {
+      "types": "./types/memoryDriver.d.ts",
+      "default": "./src/memoryDriver.js"
+    }
+  },
+  "types": "./types/index.d.ts",
+  "files": [
+    "src",
+    "types"
+  ],
+  "scripts": {
+    "test": "vitest --reporter=verbose --run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npx tsc --declaration --allowJs --emitDeclarationOnly --skipLibCheck --target es2020 --module nodenext --moduleResolution nodenext --strict false --esModuleInterop true --outDir ./types src/index.js src/postgresDriver.js src/memoryDriver.js"
+  },
+  "keywords": [
+    "entitlements",
+    "feature-flags",
+    "feature-gating",
+    "plans",
+    "quota",
+    "postgres"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prsmjs/entitle.git"
+  },
+  "homepage": "https://github.com/prsmjs/entitle#readme",
+  "bugs": {
+    "url": "https://github.com/prsmjs/entitle/issues"
+  },
+  "dependencies": {
+    "@prsm/ms": "^2.0.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "pg": "^8.16.3",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/entitlements.js

@@ -0,0 +1,260 @@
+import ms from "@prsm/ms"
+
+/**
+ * @typedef {Object} Plan
+ * @property {Record<string, boolean>} [features] - capability flags this plan grants (`{ sso: true, export_csv: false }`)
+ * @property {Record<string, number|null>} [limits] - numeric ceilings keyed by metric name; `null` means unlimited (`{ tokens: 1000000, seats: 5 }`)
+ */
+
+/**
+ * @typedef {Object} Override
+ * A per-subject override layered on top of the subject's plan. Shallow-merges
+ * over the plan, so you only specify what differs (the enterprise customer who
+ * negotiated more seats, or got one feature switched on).
+ * @property {Record<string, boolean>} [features]
+ * @property {Record<string, number|null>} [limits]
+ */
+
+/**
+ * @typedef {Object} EntitlementsOptions
+ * @property {Object} driver - storage backend: `postgresDriver({ pool })` for production, `memoryDriver()` for tests
+ * @property {Record<string, Plan>} plans - the plan catalog, declared once at construction (your pricing tiers)
+ * @property {string} defaultPlan - plan applied to a subject with no assignment; must be a key of `plans`
+ * @property {{ usage: Function }} [meter] - optional `@prsm/meter` instance; required only for `check()`, which reads live usage from it
+ * @property {number|string} [cacheTtl] - how long resolved plan/override state is cached per subject, ms or a string like `"10s"` (default `"10s"`, `0` disables). Kept short and invalidated on writes so entitlements stay runtime-evaluated, never startup-frozen
+ * @property {{ startSpan: Function }} [tracer] - optional `@prsm/trace` tracer
+ */
+
+/**
+ * @typedef {Object} Effective
+ * @property {string} plan - the effective plan name
+ * @property {Record<string, boolean>} features
+ * @property {Record<string, number|null>} limits
+ */
+
+/**
+ * @typedef {Object} CheckResult
+ * @property {boolean} allowed - whether current usage is below the limit (always true when the limit is unlimited)
+ * @property {number} used - current usage, read live from the meter
+ * @property {number|null} remaining - `max(0, limit - used)`, or `null` when unlimited
+ * @property {number|null} limit - the resolved ceiling, or `null` when unlimited
+ * @property {string} [unit] - the meter unit for this metric
+ * @property {string} feature - the limit key that was checked
+ */
+
+function validatePlans(plans, defaultPlan) {
+  if (!plans || typeof plans !== "object" || Object.keys(plans).length === 0) {
+    throw new Error("createEntitlements requires a non-empty `plans` catalog")
+  }
+  for (const [name, plan] of Object.entries(plans)) {
+    if (plan.features && typeof plan.features !== "object") throw new Error(`plan "${name}" features must be an object`)
+    if (plan.limits && typeof plan.limits !== "object") throw new Error(`plan "${name}" limits must be an object`)
+  }
+  if (!defaultPlan || !plans[defaultPlan]) {
+    throw new Error(`createEntitlements requires \`defaultPlan\` to be one of the declared plans: ${Object.keys(plans).join(", ")}`)
+  }
+}
+
+function validateOverride(data) {
+  if (!data || typeof data !== "object") throw new Error("override data must be an object with `features` and/or `limits`")
+  for (const [k, v] of Object.entries(data.features ?? {})) {
+    if (typeof v !== "boolean") throw new Error(`override feature "${k}" must be a boolean`)
+  }
+  for (const [k, v] of Object.entries(data.limits ?? {})) {
+    if (v !== null && (typeof v !== "number" || !Number.isFinite(v))) throw new Error(`override limit "${k}" must be a finite number or null`)
+  }
+}
+
+function createCache(ttl) {
+  const store = new Map()
+  return {
+    get(subject) {
+      if (ttl <= 0) return undefined
+      const hit = store.get(subject)
+      if (!hit) return undefined
+      if (hit.expires <= Date.now()) {
+        store.delete(subject)
+        return undefined
+      }
+      return hit.value
+    },
+    set(subject, value) {
+      if (ttl <= 0) return
+      store.set(subject, { value, expires: Date.now() + ttl })
+    },
+    invalidate(subject) {
+      store.delete(subject)
+    },
+  }
+}
+
+async function traced(tracer, name, attrs, fn) {
+  const span = tracer?.startSpan(name, attrs)
+  try {
+    return await fn()
+  } catch (err) {
+    span?.setError(err)
+    throw err
+  } finally {
+    span?.end()
+  }
+}
+
+/**
+ * Create an entitlements resolver: given a subject, decide what their plan
+ * allows right now. Plans are declared up front; assignments and overrides live
+ * in the driver and are resolved live on every call, so a plan change or a
+ * crossed usage threshold takes effect immediately, not at the next restart.
+ *
+ * @param {EntitlementsOptions} options
+ */
+export function createEntitlements(options = {}) {
+  const { driver, plans, defaultPlan, meter = null, tracer = null } = options
+  if (!driver) throw new Error("createEntitlements requires a `driver` (postgresDriver or memoryDriver)")
+  validatePlans(plans, defaultPlan)
+
+  const catalog = { ...plans }
+  const cache = createCache(ms(options.cacheTtl ?? "10s"))
+
+  async function resolve(subject) {
+    if (!subject) throw new Error("a `subject` is required")
+    const cached = cache.get(subject)
+    if (cached) return cached
+
+    const state = await driver.getState(subject)
+    const planName = state?.plan ?? defaultPlan
+    const planDef = catalog[planName]
+    if (!planDef) {
+      throw new Error(`subject "${subject}" is assigned to unknown plan "${planName}"`)
+    }
+    const override = state?.override ?? {}
+    const effective = {
+      plan: planName,
+      features: { ...(planDef.features ?? {}), ...(override.features ?? {}) },
+      limits: { ...(planDef.limits ?? {}), ...(override.limits ?? {}) },
+    }
+    cache.set(subject, effective)
+    return effective
+  }
+
+  return {
+    /** Create the backing tables if they do not exist. Idempotent. */
+    setup() {
+      return driver.setup()
+    },
+
+    /**
+     * Assign a subject to a plan. Takes effect immediately.
+     * @param {string} subject
+     * @param {string} plan - a key of the plan catalog
+     */
+    async assign(subject, plan) {
+      if (!subject) throw new Error("assign requires a `subject`")
+      if (!catalog[plan]) throw new Error(`unknown plan "${plan}". declared plans: ${Object.keys(catalog).join(", ")}`)
+      await driver.assign(subject, plan)
+      cache.invalidate(subject)
+    },
+
+    /**
+     * Layer a per-subject override on top of the subject's plan. Shallow-merges,
+     * so pass only what differs. Takes effect immediately.
+     * @param {string} subject
+     * @param {Override} data
+     */
+    async override(subject, data) {
+      if (!subject) throw new Error("override requires a `subject`")
+      validateOverride(data)
+      await driver.setOverride(subject, { features: data.features ?? {}, limits: data.limits ?? {} })
+      cache.invalidate(subject)
+    },
+
+    /**
+     * Remove a subject's override, falling back to plain plan entitlements.
+     * @param {string} subject
+     */
+    async clearOverride(subject) {
+      if (!subject) throw new Error("clearOverride requires a `subject`")
+      await driver.clearOverride(subject)
+      cache.invalidate(subject)
+    },
+
+    /**
+     * The subject's effective plan name (the default plan if unassigned).
+     * @param {string} subject
+     * @returns {Promise<string>}
+     */
+    async plan(subject) {
+      return (await resolve(subject)).plan
+    },
+
+    /**
+     * Whether a capability flag is granted to the subject.
+     * @param {string} subject
+     * @param {string} feature
+     * @returns {Promise<boolean>}
+     */
+    async can(subject, feature) {
+      return traced(tracer, "entitle.can", { "entitle.subject": subject, "entitle.feature": feature }, async () => {
+        const eff = await resolve(subject)
+        return eff.features[feature] === true
+      })
+    },
+
+    /**
+     * The numeric ceiling for a limit key, after overrides. Returns `null` for an
+     * unlimited or undeclared limit. This is the static ceiling; it does not read usage.
+     * @param {string} subject
+     * @param {string} key
+     * @returns {Promise<number|null>}
+     */
+    async limit(subject, key) {
+      const eff = await resolve(subject)
+      return key in eff.limits ? eff.limits[key] : null
+    },
+
+    /**
+     * Check live usage against the subject's limit. Resolves the ceiling, then
+     * reads current usage from the meter for the metric of the same name. This is
+     * the composition seam: entitle supplies the limit, meter supplies the usage.
+     * Requires a `meter` to have been passed to `createEntitlements`.
+     * @param {string} subject
+     * @param {string} key - a limit key that is also a meter metric
+     * @param {{ period?: any, range?: any }} [usageQuery] - forwarded to `meter.usage`
+     * @returns {Promise<CheckResult>}
+     */
+    async check(subject, key, usageQuery = {}) {
+      if (!meter) {
+        throw new Error("check requires a `meter`; pass it to createEntitlements, or use limit() for the static ceiling")
+      }
+      return traced(tracer, "entitle.check", { "entitle.subject": subject, "entitle.feature": key }, async () => {
+        const limit = await this.limit(subject, key)
+        const usage = await meter.usage({ subject, metric: key, ...usageQuery })
+        const used = usage.quantity
+        const allowed = limit === null || used < limit
+        return {
+          allowed,
+          used,
+          remaining: limit === null ? null : Math.max(0, limit - used),
+          limit,
+          unit: usage.unit,
+          feature: key,
+        }
+      })
+    },
+
+    /**
+     * The subject's full effective entitlements, for a settings or billing page.
+     * @param {string} subject
+     * @returns {Promise<Effective>}
+     */
+    async describe(subject) {
+      const eff = await resolve(subject)
+      return { plan: eff.plan, features: { ...eff.features }, limits: { ...eff.limits } }
+    },
+
+    /** Release backing resources (driver connections). */
+    close() {
+      return driver.close?.()
+    },
+  }
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { createEntitlements } from "./entitlements.js"
+export { postgresDriver } from "./postgresDriver.js"
+export { memoryDriver } from "./memoryDriver.js"

package/src/memoryDriver.js

@@ -0,0 +1,36 @@
+/**
+ * In-memory entitlements driver. Mirrors the postgres driver's behavior so the
+ * test suite runs without infrastructure. Not durable - state lives for the
+ * lifetime of the process.
+ *
+ * @returns {object} a driver for `createEntitlements({ driver })`
+ */
+export function memoryDriver() {
+  const assignments = new Map()
+  const overrides = new Map()
+
+  return {
+    async setup() {},
+
+    async getState(subject) {
+      return {
+        plan: assignments.get(subject) ?? null,
+        override: overrides.get(subject) ?? null,
+      }
+    },
+
+    async assign(subject, plan) {
+      assignments.set(subject, plan)
+    },
+
+    async setOverride(subject, data) {
+      overrides.set(subject, data)
+    },
+
+    async clearOverride(subject) {
+      overrides.delete(subject)
+    },
+
+    async close() {},
+  }
+}

package/src/postgresDriver.js

@@ -0,0 +1,69 @@
+/**
+ * @typedef {Object} PostgresDriverOptions
+ * @property {import("pg").Pool} pool - a `pg` Pool
+ * @property {string} [prefix] - table name prefix (default `"entitle"`), for keeping several resolvers in one database
+ */
+
+/**
+ * Durable postgres entitlements driver. Two tables: plan assignments and
+ * per-subject overrides. Both are keyed by subject and read live on resolution.
+ *
+ * @param {PostgresDriverOptions} options
+ * @returns {object} a driver for `createEntitlements({ driver })`
+ */
+export function postgresDriver(options = {}) {
+  const { pool, prefix = "entitle" } = options
+  if (!pool) throw new Error("postgresDriver requires a `pool`")
+
+  const assignments = `${prefix}_assignments`
+  const overrides = `${prefix}_overrides`
+
+  return {
+    async setup() {
+      await pool.query(`
+        create table if not exists ${assignments} (
+          subject text primary key,
+          plan text not null,
+          updated_at timestamptz not null default now()
+        );
+        create table if not exists ${overrides} (
+          subject text primary key,
+          data jsonb not null,
+          updated_at timestamptz not null default now()
+        );
+      `)
+    },
+
+    async getState(subject) {
+      const r = await pool.query(
+        `select
+           (select plan from ${assignments} where subject = $1) as plan,
+           (select data from ${overrides} where subject = $1) as override`,
+        [subject],
+      )
+      return { plan: r.rows[0].plan ?? null, override: r.rows[0].override ?? null }
+    },
+
+    async assign(subject, plan) {
+      await pool.query(
+        `insert into ${assignments} (subject, plan) values ($1, $2)
+         on conflict (subject) do update set plan = excluded.plan, updated_at = now()`,
+        [subject, plan],
+      )
+    },
+
+    async setOverride(subject, data) {
+      await pool.query(
+        `insert into ${overrides} (subject, data) values ($1, $2)
+         on conflict (subject) do update set data = excluded.data, updated_at = now()`,
+        [subject, JSON.stringify(data)],
+      )
+    },
+
+    async clearOverride(subject) {
+      await pool.query(`delete from ${overrides} where subject = $1`, [subject])
+    },
+
+    async close() {},
+  }
+}

package/types/entitlements.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Create an entitlements resolver: given a subject, decide what their plan
+ * allows right now. Plans are declared up front; assignments and overrides live
+ * in the driver and are resolved live on every call, so a plan change or a
+ * crossed usage threshold takes effect immediately, not at the next restart.
+ *
+ * @param {EntitlementsOptions} options
+ */
+export function createEntitlements(options?: EntitlementsOptions): {
+    /** Create the backing tables if they do not exist. Idempotent. */
+    setup(): any;
+    /**
+     * Assign a subject to a plan. Takes effect immediately.
+     * @param {string} subject
+     * @param {string} plan - a key of the plan catalog
+     */
+    assign(subject: string, plan: string): Promise<void>;
+    /**
+     * Layer a per-subject override on top of the subject's plan. Shallow-merges,
+     * so pass only what differs. Takes effect immediately.
+     * @param {string} subject
+     * @param {Override} data
+     */
+    override(subject: string, data: Override): Promise<void>;
+    /**
+     * Remove a subject's override, falling back to plain plan entitlements.
+     * @param {string} subject
+     */
+    clearOverride(subject: string): Promise<void>;
+    /**
+     * The subject's effective plan name (the default plan if unassigned).
+     * @param {string} subject
+     * @returns {Promise<string>}
+     */
+    plan(subject: string): Promise<string>;
+    /**
+     * Whether a capability flag is granted to the subject.
+     * @param {string} subject
+     * @param {string} feature
+     * @returns {Promise<boolean>}
+     */
+    can(subject: string, feature: string): Promise<boolean>;
+    /**
+     * The numeric ceiling for a limit key, after overrides. Returns `null` for an
+     * unlimited or undeclared limit. This is the static ceiling; it does not read usage.
+     * @param {string} subject
+     * @param {string} key
+     * @returns {Promise<number|null>}
+     */
+    limit(subject: string, key: string): Promise<number | null>;
+    /**
+     * Check live usage against the subject's limit. Resolves the ceiling, then
+     * reads current usage from the meter for the metric of the same name. This is
+     * the composition seam: entitle supplies the limit, meter supplies the usage.
+     * Requires a `meter` to have been passed to `createEntitlements`.
+     * @param {string} subject
+     * @param {string} key - a limit key that is also a meter metric
+     * @param {{ period?: any, range?: any }} [usageQuery] - forwarded to `meter.usage`
+     * @returns {Promise<CheckResult>}
+     */
+    check(subject: string, key: string, usageQuery?: {
+        period?: any;
+        range?: any;
+    }): Promise<CheckResult>;
+    /**
+     * The subject's full effective entitlements, for a settings or billing page.
+     * @param {string} subject
+     * @returns {Promise<Effective>}
+     */
+    describe(subject: string): Promise<Effective>;
+    /** Release backing resources (driver connections). */
+    close(): any;
+};
+export type Plan = {
+    /**
+     * - capability flags this plan grants (`{ sso: true, export_csv: false }`)
+     */
+    features?: Record<string, boolean>;
+    /**
+     * - numeric ceilings keyed by metric name; `null` means unlimited (`{ tokens: 1000000, seats: 5 }`)
+     */
+    limits?: Record<string, number | null>;
+};
+/**
+ * A per-subject override layered on top of the subject's plan. Shallow-merges
+ * over the plan, so you only specify what differs (the enterprise customer who
+ * negotiated more seats, or got one feature switched on).
+ */
+export type Override = {
+    features?: Record<string, boolean>;
+    limits?: Record<string, number | null>;
+};
+export type EntitlementsOptions = {
+    /**
+     * - storage backend: `postgresDriver({ pool })` for production, `memoryDriver()` for tests
+     */
+    driver: any;
+    /**
+     * - the plan catalog, declared once at construction (your pricing tiers)
+     */
+    plans: Record<string, Plan>;
+    /**
+     * - plan applied to a subject with no assignment; must be a key of `plans`
+     */
+    defaultPlan: string;
+    /**
+     * - optional `@prsm/meter` instance; required only for `check()`, which reads live usage from it
+     */
+    meter?: {
+        usage: Function;
+    };
+    /**
+     * - how long resolved plan/override state is cached per subject, ms or a string like `"10s"` (default `"10s"`, `0` disables). Kept short and invalidated on writes so entitlements stay runtime-evaluated, never startup-frozen
+     */
+    cacheTtl?: number | string;
+    /**
+     * - optional `@prsm/trace` tracer
+     */
+    tracer?: {
+        startSpan: Function;
+    };
+};
+export type Effective = {
+    /**
+     * - the effective plan name
+     */
+    plan: string;
+    features: Record<string, boolean>;
+    limits: Record<string, number | null>;
+};
+export type CheckResult = {
+    /**
+     * - whether current usage is below the limit (always true when the limit is unlimited)
+     */
+    allowed: boolean;
+    /**
+     * - current usage, read live from the meter
+     */
+    used: number;
+    /**
+     * - `max(0, limit - used)`, or `null` when unlimited
+     */
+    remaining: number | null;
+    /**
+     * - the resolved ceiling, or `null` when unlimited
+     */
+    limit: number | null;
+    /**
+     * - the meter unit for this metric
+     */
+    unit?: string;
+    /**
+     * - the limit key that was checked
+     */
+    feature: string;
+};

package/types/index.d.ts

@@ -0,0 +1,3 @@
+export { createEntitlements } from "./entitlements.js";
+export { postgresDriver } from "./postgresDriver.js";
+export { memoryDriver } from "./memoryDriver.js";

package/types/memoryDriver.d.ts

@@ -0,0 +1,8 @@
+/**
+ * In-memory entitlements driver. Mirrors the postgres driver's behavior so the
+ * test suite runs without infrastructure. Not durable - state lives for the
+ * lifetime of the process.
+ *
+ * @returns {object} a driver for `createEntitlements({ driver })`
+ */
+export function memoryDriver(): object;

package/types/postgresDriver.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @typedef {Object} PostgresDriverOptions
+ * @property {import("pg").Pool} pool - a `pg` Pool
+ * @property {string} [prefix] - table name prefix (default `"entitle"`), for keeping several resolvers in one database
+ */
+/**
+ * Durable postgres entitlements driver. Two tables: plan assignments and
+ * per-subject overrides. Both are keyed by subject and read live on resolution.
+ *
+ * @param {PostgresDriverOptions} options
+ * @returns {object} a driver for `createEntitlements({ driver })`
+ */
+export function postgresDriver(options?: PostgresDriverOptions): object;
+export type PostgresDriverOptions = {
+    /**
+     * - a `pg` Pool
+     */
+    pool: any;
+    /**
+     * - table name prefix (default `"entitle"`), for keeping several resolvers in one database
+     */
+    prefix?: string;
+};