@prsm/entitle 2.1.2 → 2.3.0

package/README.md

@@ -175,6 +175,14 @@ Returns the subject's effective plan name.
 
 Returns the full effective snapshot `{ plan, features, limits }`, for a settings or billing page.
 
+### `entitlements.subjects({ limit? })`
+
+Lists subjects that have an explicit assignment or override, most-recently-configured first, capped at `limit` (default `100`). Subjects on the default plan with no override are never stored, so they do not appear - this lists the configured subjects, for discovery in dashboards and admin tools. Returns `[{ subject, assigned, overridden, lastConfiguredAt }]`.
+
+### `entitlements.catalog()`
+
+Returns the static configuration `{ defaultPlan, plans, features, limits }`: every declared plan, the default plan, and the full feature and limit universes. Where `describe` resolves a single subject, `catalog` exposes the whole offering, for a plan comparison table, an admin dashboard, or documenting what the system grants. Subject-independent and read-only, so it never touches storage. The returned object is a fresh copy.
+
 ### `entitlements.close()`
 
 Releases driver resources.

package/package.json

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

package/src/entitlements.js

@@ -34,6 +34,14 @@ import ms from "@prsm/ms"
  * @property {Record<string, number|null>} limits - the resolved limit ceilings, after applying the subject's override on top of the plan (`null` means unlimited)
  */
 
+/**
+ * @typedef {Object} Catalog
+ * @property {string} defaultPlan - the plan applied to a subject with no assignment
+ * @property {Record<string, Plan>} plans - the declared plan catalog (your pricing tiers)
+ * @property {string[]} features - the full feature universe (declared, or derived from the union across plans)
+ * @property {string[]} limits - the full limit universe (declared, or derived from the union across plans)
+ */
+
 /**
  * @typedef {Object} CheckResult
  * @property {boolean} allowed - whether current usage is below the limit (always true when the limit is unlimited)
@@ -200,6 +208,29 @@ export function createEntitlements(options = {}) {
       return driver.setup()
     },
 
+    /**
+     * The static configuration of this resolver: the plan catalog, the default
+     * plan, and the full feature and limit universes. Unlike describe(), which
+     * resolves a single subject, this exposes every plan and every declared key
+     * - for plan comparison tables, admin dashboards, or documenting what the
+     * system offers. Subject-independent, so it never touches storage. The
+     * returned object is a fresh copy; mutating it does not affect the resolver.
+     * @returns {Catalog}
+     */
+    catalog() {
+      return {
+        defaultPlan,
+        plans: Object.fromEntries(
+          Object.entries(catalog).map(([name, p]) => [name, {
+            features: { ...(p.features ?? {}) },
+            limits: { ...(p.limits ?? {}) },
+          }]),
+        ),
+        features: [...featureUniverse],
+        limits: [...limitUniverse],
+      }
+    },
+
     /**
      * Assign a subject to a plan. Takes effect immediately.
      * @param {string} subject - the subject identifier (whatever id you key entitlements by, such as an account or user id)
@@ -326,6 +357,19 @@ export function createEntitlements(options = {}) {
       })
     },
 
+    /**
+     * List subjects that have an explicit assignment or override, most-recently-
+     * configured first, capped at `limit` (default 100). Subjects on the default
+     * plan with no override are not stored, so they do not appear - this lists
+     * the configured subjects, for discovery in dashboards and admin tools.
+     * @param {{ limit?: number }} [query]
+     * @returns {Promise<Array<{ subject: string, assigned: boolean, overridden: boolean, lastConfiguredAt: Date|null }>>}
+     */
+    async subjects(query = {}) {
+      if (!driver.subjects) throw new Error("this driver does not support listing subjects")
+      return driver.subjects({ limit: query.limit ?? 100 })
+    },
+
     /**
      * The subject's full effective entitlements, for a settings or billing page.
      * @param {string} subject - the subject identifier to resolve

package/src/memoryDriver.js

@@ -8,6 +8,9 @@
 export function memoryDriver() {
   const assignments = new Map()
   const overrides = new Map()
+  const touched = new Map()
+
+  const touch = (subject) => touched.set(subject, new Date())
 
   return {
     async setup() {},
@@ -19,12 +22,27 @@ export function memoryDriver() {
       }
     },
 
+    async subjects({ limit }) {
+      const subs = new Set([...assignments.keys(), ...overrides.keys()])
+      return [...subs]
+        .map((subject) => ({
+          subject,
+          assigned: assignments.has(subject),
+          overridden: overrides.has(subject),
+          lastConfiguredAt: touched.get(subject) ?? null,
+        }))
+        .sort((a, b) => (b.lastConfiguredAt?.getTime() ?? 0) - (a.lastConfiguredAt?.getTime() ?? 0) || (a.subject < b.subject ? -1 : 1))
+        .slice(0, limit)
+    },
+
     async assign(subject, plan) {
       assignments.set(subject, plan)
+      touch(subject)
     },
 
     async unassign(subject) {
       assignments.delete(subject)
+      touch(subject)
     },
 
     async mergeOverride(subject, delta) {
@@ -33,6 +51,7 @@ export function memoryDriver() {
         features: { ...(current.features ?? {}), ...(delta.features ?? {}) },
         limits: { ...(current.limits ?? {}), ...(delta.limits ?? {}) },
       })
+      touch(subject)
     },
 
     async removeOverrideKeys(subject, keys) {
@@ -43,10 +62,12 @@ export function memoryDriver() {
       for (const k of keys.features ?? []) delete features[k]
       for (const k of keys.limits ?? []) delete limits[k]
       overrides.set(subject, { features, limits })
+      touch(subject)
     },
 
     async clearOverride(subject) {
       overrides.delete(subject)
+      touch(subject)
     },
 
     async close() {},

package/src/postgresDriver.js

@@ -44,6 +44,28 @@ export function postgresDriver(options = {}) {
       return { plan: r.rows[0].plan ?? null, override: r.rows[0].override ?? null }
     },
 
+    async subjects({ limit }) {
+      const r = await pool.query(
+        `select subject,
+           bool_or(src = 'a') as assigned,
+           bool_or(src = 'o') as overridden,
+           max(updated_at) as last_at
+         from (
+           select subject, updated_at, 'a' as src from ${assignments}
+           union all
+           select subject, updated_at, 'o' as src from ${overrides}
+         ) u
+         group by subject order by last_at desc, subject asc limit $1`,
+        [limit],
+      )
+      return r.rows.map((row) => ({
+        subject: row.subject,
+        assigned: row.assigned,
+        overridden: row.overridden,
+        lastConfiguredAt: row.last_at,
+      }))
+    },
+
     async assign(subject, plan) {
       await pool.query(
         `insert into ${assignments} (subject, plan) values ($1, $2)

package/types/entitlements.d.ts

@@ -9,6 +9,16 @@
 export function createEntitlements(options?: EntitlementsOptions): {
     /** Create the backing tables if they do not exist. Idempotent. */
     setup(): any;
+    /**
+     * The static configuration of this resolver: the plan catalog, the default
+     * plan, and the full feature and limit universes. Unlike describe(), which
+     * resolves a single subject, this exposes every plan and every declared key
+     * - for plan comparison tables, admin dashboards, or documenting what the
+     * system offers. Subject-independent, so it never touches storage. The
+     * returned object is a fresh copy; mutating it does not affect the resolver.
+     * @returns {Catalog}
+     */
+    catalog(): Catalog;
     /**
      * Assign a subject to a plan. Takes effect immediately.
      * @param {string} subject - the subject identifier (whatever id you key entitlements by, such as an account or user id)
@@ -83,6 +93,22 @@ export function createEntitlements(options?: EntitlementsOptions): {
         period?: any;
         range?: any;
     }): Promise<CheckResult>;
+    /**
+     * List subjects that have an explicit assignment or override, most-recently-
+     * configured first, capped at `limit` (default 100). Subjects on the default
+     * plan with no override are not stored, so they do not appear - this lists
+     * the configured subjects, for discovery in dashboards and admin tools.
+     * @param {{ limit?: number }} [query]
+     * @returns {Promise<Array<{ subject: string, assigned: boolean, overridden: boolean, lastConfiguredAt: Date|null }>>}
+     */
+    subjects(query?: {
+        limit?: number;
+    }): Promise<Array<{
+        subject: string;
+        assigned: boolean;
+        overridden: boolean;
+        lastConfiguredAt: Date | null;
+    }>>;
     /**
      * The subject's full effective entitlements, for a settings or billing page.
      * @param {string} subject - the subject identifier to resolve
@@ -169,6 +195,24 @@ export type Effective = {
      */
     limits: Record<string, number | null>;
 };
+export type Catalog = {
+    /**
+     * - the plan applied to a subject with no assignment
+     */
+    defaultPlan: string;
+    /**
+     * - the declared plan catalog (your pricing tiers)
+     */
+    plans: Record<string, Plan>;
+    /**
+     * - the full feature universe (declared, or derived from the union across plans)
+     */
+    features: string[];
+    /**
+     * - the full limit universe (declared, or derived from the union across plans)
+     */
+    limits: string[];
+};
 export type CheckResult = {
     /**
      * - whether current usage is below the limit (always true when the limit is unlimited)