@prsm/entitle 1.0.0 → 2.0.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
@@ -95,22 +99,40 @@ 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`; `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`).
 
-**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`.
+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.
+
+```js
+await entitlements.override(account.id, { limits: { seats: 50 } })
+await entitlements.override(account.id, { features: { sso: true } }) // seats override stays
+await entitlements.clearOverride(account.id, { limits: ["seats"] })   // seats reverts to plan, sso stays
+await entitlements.clearOverride(account.id)                          // back to plain plan
+```
 
 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? })`
+### `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.
 
 ### `entitlements.setup()`
 
@@ -120,21 +142,25 @@ 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.
 
-### `entitlements.clearOverride(subject)`
+### `entitlements.clearOverride(subject, keys?)`
 
-Removes the subject's override.
+With no `keys`, removes the subject's entire override. With `keys` (`{ features?: string[], limits?: string[] }`), removes only those entries and keeps the rest.
 
 ### `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.0.0",
+  "version": "2.0.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)
@@ -156,25 +203,63 @@ export function createEntitlements(options = {}) {
     },
 
     /**
-     * Layer a per-subject override on top of the subject's plan. Shallow-merges,
-     * so pass only what differs. Takes effect immediately.
+     * 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
+     * accumulate: overriding `seats`, then later overriding `sso`, leaves both in
+     * place, and overriding a key again updates just that key. Use clearOverride
+     * to remove overrides. 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 ?? {} })
+      validateOverride(data, featureUniverse, limitUniverse)
+      const current = (await driver.getState(subject))?.override ?? {}
+      await driver.setOverride(subject, {
+        features: { ...(current.features ?? {}), ...(data.features ?? {}) },
+        limits: { ...(current.limits ?? {}), ...(data.limits ?? {}) },
+      })
       cache.invalidate(subject)
     },
 
     /**
-     * Remove a subject's override, falling back to plain plan entitlements.
+     * Remove overrides for a subject. With no `keys`, removes the entire override
+     * and the subject falls back to plain plan entitlements. With `keys`, removes
+     * only those override entries (reverting them to the plan) and keeps the rest.
      * @param {string} subject
+     * @param {{ features?: string[], limits?: string[] }} [keys]
      */
-    async clearOverride(subject) {
+    async clearOverride(subject, keys) {
       if (!subject) throw new Error("clearOverride requires a `subject`")
-      await driver.clearOverride(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 })
+        }
+      }
       cache.invalidate(subject)
     },
 
@@ -188,12 +273,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
@@ -201,15 +289,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
     },
 
     /**
@@ -228,7 +320,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,6 +23,10 @@ export function memoryDriver() {
       assignments.set(subject, plan)
     },
 
+    async unassign(subject) {
+      assignments.delete(subject)
+    },
+
     async setOverride(subject, data) {
       overrides.set(subject, data)
     },

package/src/postgresDriver.js

@@ -52,6 +52,10 @@ export function postgresDriver(options = {}) {
       )
     },
 
+    async unassign(subject) {
+      await pool.query(`delete from ${assignments} where subject = $1`, [subject])
+    },
+
     async setOverride(subject, data) {
       await pool.query(
         `insert into ${overrides} (subject, data) values ($1, $2)

package/types/entitlements.d.ts

@@ -16,17 +16,33 @@ export function createEntitlements(options?: EntitlementsOptions): {
      */
     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.
+     * 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
+     * accumulate: overriding `seats`, then later overriding `sso`, leaves both in
+     * place, and overriding a key again updates just that key. Use clearOverride
+     * to remove overrides. 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.
+     * Remove overrides for a subject. With no `keys`, removes the entire override
+     * and the subject falls back to plain plan entitlements. With `keys`, removes
+     * only those override entries (reverting them to the plan) and keeps the rest.
      * @param {string} subject
+     * @param {{ features?: string[], limits?: string[] }} [keys]
      */
-    clearOverride(subject: string): Promise<void>;
+    clearOverride(subject: string, keys?: {
+        features?: string[];
+        limits?: string[];
+    }): Promise<void>;
     /**
      * The subject's effective plan name (the default plan if unassigned).
      * @param {string} subject
@@ -34,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>}
@@ -103,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
      */