@prsm/entitle 2.2.0 → 2.3.0

package/README.md

@@ -175,6 +175,10 @@ 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.

package/package.json

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

package/src/entitlements.js

@@ -357,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

@@ -93,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