@prsm/entitle 1.1.0 → 2.1.0

package/README.md

@@ -30,6 +30,8 @@ const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL })
 const entitlements = createEntitlements({
   driver: postgresDriver({ pool }),
   defaultPlan: "free",
+  features: ["api_access", "export_csv", "sso"], // the universe of valid feature keys
+  limits: ["tokens", "seats"],                    // the universe of valid limit keys
   plans: {
     free: {
       features: { api_access: true, export_csv: false, sso: false },
@@ -49,6 +51,8 @@ const entitlements = createEntitlements({
 await entitlements.setup() // create tables if they do not exist; idempotent
 ```
 
+Declaring `features` and `limits` up front is the catalog: plans may only reference keys in it, and `can()`/`limit()`/`check()` throw on any other key, so a typo (`can(id, "exprot_csv")`) surfaces instead of silently returning `false`. The declarations are optional - if you omit them the universe is derived from the union of keys across your plans - but declaring them also catches typos in the plan definitions themselves.
+
 Gating a feature and a quota on a request:
 
 ```js
@@ -87,6 +91,7 @@ const entitlements = createEntitlements({
   meter,
 })
 
+// account.id is assigned the "pro" plan, whose tokens limit is 5_000_000
 const quota = await entitlements.check(account.id, "tokens")
 // { allowed: true, used: 84210, remaining: 4915790, limit: 5000000, unit: "tokens", feature: "tokens" }
 
@@ -95,16 +100,25 @@ 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.
 
+### Who owns what
+
+Entitle does not track usage. It has no usage state of its own. In the result above, `limit: 5000000` comes from the plan (entitle's only input), `used: 84210` comes from a single live `meter.usage()` call that `check()` makes for you, and `remaining` is just `limit - used`. All accrual happens in your application calling `meter.record(...)` on each usage event; meter stores and aggregates it. So meter owns "how much have they used," entitle owns "what is the ceiling," and `check()` fetches the ceiling, asks meter for the usage, and subtracts. Pass `meter` only to enable that one call - without it, use `limit()` for the ceiling and read usage from meter yourself.
+
+Two things must line up for `check()` to work:
+
+- **Same subject identifier.** `check(subject, key)` calls `meter.usage({ subject, ... })`, so the `subject` you pass here must be the same id you record usage under in meter.
+- **Matching key.** The entitle limit key must equal the meter metric name (`check(id, "tokens")` reads the `tokens` metric). If the metric does not exist in the meter, meter throws.
+
 ## 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.
+- **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; a known limit a plan does not grant resolves to `0` (no allowance), never silently 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`.
+**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`; `unassign(subject)` removes an assignment and reverts the subject to the default (distinct from assigning the default explicitly, which would not follow a later change to `defaultPlan`).
 
-Overrides accumulate: each `override()` call merges into the subject's existing override rather than replacing it, so granting more seats and later enabling a feature leaves both in place, and overriding a key again updates just that key. `clearOverride(subject)` removes the whole override; `clearOverride(subject, { limits: ["seats"] })` reverts only the named keys and keeps the rest.
+Overrides accumulate: each `override()` call merges into the subject's existing override rather than replacing it, so granting more seats and later enabling a feature leaves both in place, and overriding a key again updates just that key. The merge happens in the database under a row lock, so two concurrent overrides to the same subject both land instead of one clobbering the other. `clearOverride(subject)` removes the whole override; `clearOverride(subject, { limits: ["seats"] })` reverts only the named keys and keeps the rest.
 
 ```js
 await entitlements.override(account.id, { limits: { seats: 50 } })
@@ -117,9 +131,9 @@ Resolved entitlements are cached per subject for a short, configurable window (`
 
 ## API
 
-### `createEntitlements({ driver, plans, defaultPlan, meter?, cacheTtl?, tracer? })`
+### `createEntitlements({ driver, plans, defaultPlan, features?, limits?, 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.
+Creates a resolver. `driver` is `postgresDriver({ pool })` or `memoryDriver()`. `plans` is the catalog; `defaultPlan` must be one of its keys. `features` and `limits` declare the universe of valid keys (defaulting to the union across plans); when given, plans may only reference declared 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; `can()` and `check()` are wrapped in spans when it is present.
 
 ### `entitlements.setup()`
 
@@ -129,6 +143,10 @@ Creates the backing tables if they do not exist. Idempotent.
 
 Assigns a subject to a plan. Takes effect immediately.
 
+### `entitlements.unassign(subject)`
+
+Removes a subject's assignment, reverting them to the default plan.
+
 ### `entitlements.override(subject, { features?, limits? })`
 
 Layers a per-subject override on top of the plan. Shallow-merges; pass only what differs.
@@ -139,11 +157,11 @@ With no `keys`, removes the subject's entire override. With `keys` (`{ features?
 
 ### `entitlements.can(subject, feature)`
 
-Returns whether a capability flag is granted (`false` for an ungranted or unknown feature).
+Returns whether a capability flag is granted (`false` for an ungranted feature). Throws on a feature key outside the catalog, so typos surface instead of silently returning `false`.
 
 ### `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.
+Returns the numeric ceiling for a limit key after overrides: `null` only for an explicitly unlimited limit, `0` for a known limit the plan does not grant. Throws on a key outside the catalog. Does not read usage.
 
 ### `entitlements.check(subject, key, usageQuery?)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prsm/entitle",
-  "version": "1.1.0",
+  "version": "2.1.0",
   "description": "Plan-based entitlements and feature gating, resolved at runtime, backed by postgres",
   "type": "module",
   "exports": {

package/src/entitlements.js

@@ -20,6 +20,8 @@ import ms from "@prsm/ms"
  * @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 {string[]} [features] - the universe of valid feature keys. When given, plans may only reference these and `can()` throws on any other key (catches typos). Defaults to the union of feature keys across all plans
+ * @property {string[]} [limits] - the universe of valid limit keys. When given, plans may only reference these and `limit()`/`check()` throw on any other key. Defaults to the union of limit keys across all 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
@@ -42,26 +44,60 @@ import ms from "@prsm/ms"
  * @property {string} feature - the limit key that was checked
  */
 
-function validatePlans(plans, defaultPlan) {
+function assertBoolean(scope, key, v) {
+  if (typeof v !== "boolean") throw new Error(`${scope} feature "${key}" must be a boolean`)
+}
+
+function assertLimitValue(scope, key, v) {
+  if (v !== null && (typeof v !== "number" || !Number.isFinite(v))) {
+    throw new Error(`${scope} limit "${key}" must be a finite number or null (null means unlimited)`)
+  }
+}
+
+/**
+ * Validate the plan catalog, derive or enforce the feature/limit universes, and
+ * type-check every plan value. Returns the two universes as Sets.
+ */
+function buildCatalog(plans, defaultPlan, declaredFeatures, declaredLimits) {
   if (!plans || typeof plans !== "object" || Object.keys(plans).length === 0) {
     throw new Error("createEntitlements requires a non-empty `plans` catalog")
   }
+  if (!defaultPlan || !plans[defaultPlan]) {
+    throw new Error(`createEntitlements requires \`defaultPlan\` to be one of the declared plans: ${Object.keys(plans).join(", ")}`)
+  }
+
+  const featureUniverse = new Set(declaredFeatures ?? [])
+  const limitUniverse = new Set(declaredLimits ?? [])
+  const enforceFeatures = Array.isArray(declaredFeatures)
+  const enforceLimits = Array.isArray(declaredLimits)
+
   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`)
+    for (const [k, v] of Object.entries(plan.features ?? {})) {
+      assertBoolean(`plan "${name}"`, k, v)
+      if (enforceFeatures && !featureUniverse.has(k)) throw new Error(`plan "${name}" references undeclared feature "${k}"`)
+      featureUniverse.add(k)
+    }
+    for (const [k, v] of Object.entries(plan.limits ?? {})) {
+      assertLimitValue(`plan "${name}"`, k, v)
+      if (enforceLimits && !limitUniverse.has(k)) throw new Error(`plan "${name}" references undeclared limit "${k}"`)
+      limitUniverse.add(k)
+    }
   }
-  if (!defaultPlan || !plans[defaultPlan]) {
-    throw new Error(`createEntitlements requires \`defaultPlan\` to be one of the declared plans: ${Object.keys(plans).join(", ")}`)
-  }
+
+  return { featureUniverse, limitUniverse }
 }
 
-function validateOverride(data) {
+function validateOverride(data, featureUniverse, limitUniverse) {
   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`)
+    assertBoolean("override", k, v)
+    if (!featureUniverse.has(k)) throw new Error(`override references unknown feature "${k}"`)
   }
   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`)
+    assertLimitValue("override", k, v)
+    if (!limitUniverse.has(k)) throw new Error(`override references unknown limit "${k}"`)
   }
 }
 
@@ -111,11 +147,22 @@ async function traced(tracer, name, attrs, fn) {
 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 { featureUniverse, limitUniverse } = buildCatalog(plans, defaultPlan, options.features, options.limits)
 
   const catalog = { ...plans }
   const cache = createCache(ms(options.cacheTtl ?? "10s"))
 
+  function requireFeature(feature) {
+    if (!featureUniverse.has(feature)) {
+      throw new Error(`unknown feature "${feature}". declared features: ${[...featureUniverse].join(", ") || "(none)"}`)
+    }
+  }
+  function requireLimit(key) {
+    if (!limitUniverse.has(key)) {
+      throw new Error(`unknown limit "${key}". declared limits: ${[...limitUniverse].join(", ") || "(none)"}`)
+    }
+  }
+
   async function resolve(subject) {
     if (!subject) throw new Error("a `subject` is required")
     const cached = cache.get(subject)
@@ -155,6 +202,18 @@ export function createEntitlements(options = {}) {
       cache.invalidate(subject)
     },
 
+    /**
+     * Remove a subject's plan assignment, reverting them to the default plan.
+     * Distinct from assigning the default plan explicitly: an unassigned subject
+     * follows `defaultPlan` if it later changes.
+     * @param {string} subject
+     */
+    async unassign(subject) {
+      if (!subject) throw new Error("unassign requires a `subject`")
+      await driver.unassign(subject)
+      cache.invalidate(subject)
+    },
+
     /**
      * Add or adjust a per-subject override, layered on top of the subject's plan.
      * Merges into any existing override for the subject, so repeated calls
@@ -166,12 +225,8 @@ export function createEntitlements(options = {}) {
      */
     async override(subject, data) {
       if (!subject) throw new Error("override requires a `subject`")
-      validateOverride(data)
-      const current = (await driver.getState(subject))?.override ?? {}
-      await driver.setOverride(subject, {
-        features: { ...(current.features ?? {}), ...(data.features ?? {}) },
-        limits: { ...(current.limits ?? {}), ...(data.limits ?? {}) },
-      })
+      validateOverride(data, featureUniverse, limitUniverse)
+      await driver.mergeOverride(subject, { features: data.features ?? {}, limits: data.limits ?? {} })
       cache.invalidate(subject)
     },
 
@@ -186,20 +241,8 @@ export function createEntitlements(options = {}) {
       if (!subject) throw new Error("clearOverride requires a `subject`")
       if (!keys) {
         await driver.clearOverride(subject)
-        cache.invalidate(subject)
-        return
-      }
-      const current = (await driver.getState(subject))?.override
-      if (current) {
-        const features = { ...(current.features ?? {}) }
-        const limits = { ...(current.limits ?? {}) }
-        for (const k of keys.features ?? []) delete features[k]
-        for (const k of keys.limits ?? []) delete limits[k]
-        if (Object.keys(features).length === 0 && Object.keys(limits).length === 0) {
-          await driver.clearOverride(subject)
-        } else {
-          await driver.setOverride(subject, { features, limits })
-        }
+      } else {
+        await driver.removeOverrideKeys(subject, { features: keys.features ?? [], limits: keys.limits ?? [] })
       }
       cache.invalidate(subject)
     },
@@ -214,12 +257,15 @@ export function createEntitlements(options = {}) {
     },
 
     /**
-     * Whether a capability flag is granted to the subject.
+     * Whether a capability flag is granted to the subject. Throws on a feature
+     * key outside the declared/derived universe, so typos surface instead of
+     * silently returning false.
      * @param {string} subject
      * @param {string} feature
      * @returns {Promise<boolean>}
      */
     async can(subject, feature) {
+      requireFeature(feature)
       return traced(tracer, "entitle.can", { "entitle.subject": subject, "entitle.feature": feature }, async () => {
         const eff = await resolve(subject)
         return eff.features[feature] === true
@@ -227,15 +273,19 @@ export function createEntitlements(options = {}) {
     },
 
     /**
-     * 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.
+     * The numeric ceiling for a limit key, after overrides. Returns `null` only
+     * when the limit is explicitly unlimited, and `0` for a known limit the
+     * subject's plan does not grant - never silently unlimited. Throws on a key
+     * outside the declared/derived universe. This is the static ceiling; it does
+     * not read usage.
      * @param {string} subject
      * @param {string} key
      * @returns {Promise<number|null>}
      */
     async limit(subject, key) {
+      requireLimit(key)
       const eff = await resolve(subject)
-      return key in eff.limits ? eff.limits[key] : null
+      return key in eff.limits ? eff.limits[key] : 0
     },
 
     /**
@@ -254,7 +304,7 @@ export function createEntitlements(options = {}) {
       }
       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 usage = await meter.usage({ ...usageQuery, subject, metric: key })
         const used = usage.quantity
         const allowed = limit === null || used < limit
         return {

package/src/memoryDriver.js

@@ -23,8 +23,26 @@ export function memoryDriver() {
       assignments.set(subject, plan)
     },
 
-    async setOverride(subject, data) {
-      overrides.set(subject, data)
+    async unassign(subject) {
+      assignments.delete(subject)
+    },
+
+    async mergeOverride(subject, delta) {
+      const current = overrides.get(subject) ?? { features: {}, limits: {} }
+      overrides.set(subject, {
+        features: { ...(current.features ?? {}), ...(delta.features ?? {}) },
+        limits: { ...(current.limits ?? {}), ...(delta.limits ?? {}) },
+      })
+    },
+
+    async removeOverrideKeys(subject, keys) {
+      const current = overrides.get(subject)
+      if (!current) return
+      const features = { ...(current.features ?? {}) }
+      const limits = { ...(current.limits ?? {}) }
+      for (const k of keys.features ?? []) delete features[k]
+      for (const k of keys.limits ?? []) delete limits[k]
+      overrides.set(subject, { features, limits })
     },
 
     async clearOverride(subject) {

package/src/postgresDriver.js

@@ -52,11 +52,34 @@ export function postgresDriver(options = {}) {
       )
     },
 
-    async setOverride(subject, data) {
+    async unassign(subject) {
+      await pool.query(`delete from ${assignments} where subject = $1`, [subject])
+    },
+
+    async mergeOverride(subject, delta) {
+      await pool.query(
+        `insert into ${overrides} (subject, data)
+         values ($1, jsonb_build_object('features', $2::jsonb, 'limits', $3::jsonb))
+         on conflict (subject) do update set
+           data = jsonb_build_object(
+             'features', coalesce(${overrides}.data -> 'features', '{}'::jsonb) || (excluded.data -> 'features'),
+             'limits',   coalesce(${overrides}.data -> 'limits',   '{}'::jsonb) || (excluded.data -> 'limits')
+           ),
+           updated_at = now()`,
+        [subject, JSON.stringify(delta.features ?? {}), JSON.stringify(delta.limits ?? {})],
+      )
+    },
+
+    async removeOverrideKeys(subject, keys) {
       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)],
+        `update ${overrides} set
+           data = jsonb_build_object(
+             'features', coalesce(data -> 'features', '{}'::jsonb) - $2::text[],
+             'limits',   coalesce(data -> 'limits',   '{}'::jsonb) - $3::text[]
+           ),
+           updated_at = now()
+         where subject = $1`,
+        [subject, keys.features ?? [], keys.limits ?? []],
       )
     },
 

package/types/entitlements.d.ts

@@ -15,6 +15,13 @@ export function createEntitlements(options?: EntitlementsOptions): {
      * @param {string} plan - a key of the plan catalog
      */
     assign(subject: string, plan: string): Promise<void>;
+    /**
+     * Remove a subject's plan assignment, reverting them to the default plan.
+     * Distinct from assigning the default plan explicitly: an unassigned subject
+     * follows `defaultPlan` if it later changes.
+     * @param {string} subject
+     */
+    unassign(subject: string): Promise<void>;
     /**
      * Add or adjust a per-subject override, layered on top of the subject's plan.
      * Merges into any existing override for the subject, so repeated calls
@@ -43,15 +50,20 @@ export function createEntitlements(options?: EntitlementsOptions): {
      */
     plan(subject: string): Promise<string>;
     /**
-     * Whether a capability flag is granted to the subject.
+     * Whether a capability flag is granted to the subject. Throws on a feature
+     * key outside the declared/derived universe, so typos surface instead of
+     * silently returning false.
      * @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.
+     * The numeric ceiling for a limit key, after overrides. Returns `null` only
+     * when the limit is explicitly unlimited, and `0` for a known limit the
+     * subject's plan does not grant - never silently unlimited. Throws on a key
+     * outside the declared/derived universe. This is the static ceiling; it does
+     * not read usage.
      * @param {string} subject
      * @param {string} key
      * @returns {Promise<number|null>}
@@ -112,6 +124,14 @@ export type EntitlementsOptions = {
      * - plan applied to a subject with no assignment; must be a key of `plans`
      */
     defaultPlan: string;
+    /**
+     * - the universe of valid feature keys. When given, plans may only reference these and `can()` throws on any other key (catches typos). Defaults to the union of feature keys across all plans
+     */
+    features?: string[];
+    /**
+     * - the universe of valid limit keys. When given, plans may only reference these and `limit()`/`check()` throw on any other key. Defaults to the union of limit keys across all plans
+     */
+    limits?: string[];
     /**
      * - optional `@prsm/meter` instance; required only for `check()`, which reads live usage from it
      */