@prsm/entitle 1.0.0 → 1.1.0

package/README.md

@@ -104,6 +104,15 @@ The **plan catalog** is declared once at construction, the way you declare your
 
 **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
@@ -124,9 +133,9 @@ Assigns a subject to a plan. Takes effect immediately.
 
 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)`
 

package/package.json

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

package/src/entitlements.js

@@ -156,25 +156,51 @@ 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.
+     * 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 ?? {} })
+      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)
     },
 

package/types/entitlements.d.ts

@@ -16,17 +16,26 @@ 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.
+     * 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