@prsm/entitle 2.1.2 → 2.2.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.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.2.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)

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)
@@ -169,6 +179,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)