@prsm/entitle 2.1.1 → 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.1",
+  "version": "2.2.0",
   "description": "Plan-based entitlements and feature gating, resolved at runtime, backed by postgres",
   "type": "module",
   "exports": {

package/src/entitlements.js

@@ -11,8 +11,8 @@ import ms from "@prsm/ms"
  * A per-subject override layered on top of the subject's plan. Shallow-merges
  * over the plan, so you only specify what differs (the enterprise customer who
  * negotiated more seats, or got one feature switched on).
- * @property {Record<string, boolean>} [features]
- * @property {Record<string, number|null>} [limits]
+ * @property {Record<string, boolean>} [features] - feature flags to override for this subject; merged over the plan's features, so include only the ones that differ
+ * @property {Record<string, number|null>} [limits] - limit ceilings to override for this subject; merged over the plan's limits, so include only the ones that differ (`null` means unlimited)
  */
 
 /**
@@ -29,9 +29,17 @@ import ms from "@prsm/ms"
 
 /**
  * @typedef {Object} Effective
- * @property {string} plan - the effective plan name
- * @property {Record<string, boolean>} features
- * @property {Record<string, number|null>} limits
+ * @property {string} plan - the effective plan name (the default plan if the subject is unassigned)
+ * @property {Record<string, boolean>} features - the resolved feature flags, after applying the subject's override on top of the plan
+ * @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)
  */
 
 /**
@@ -200,9 +208,32 @@ 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
+     * @param {string} subject - the subject identifier (whatever id you key entitlements by, such as an account or user id)
      * @param {string} plan - a key of the plan catalog
      */
     async assign(subject, plan) {
@@ -216,7 +247,7 @@ export function createEntitlements(options = {}) {
      * 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
+     * @param {string} subject - the subject identifier whose assignment is removed
      */
     async unassign(subject) {
       if (!subject) throw new Error("unassign requires a `subject`")
@@ -230,8 +261,8 @@ export function createEntitlements(options = {}) {
      * 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
+     * @param {string} subject - the subject identifier to override
+     * @param {Override} data - the features and/or limits to override; merged into any existing override
      */
     async override(subject, data) {
       if (!subject) throw new Error("override requires a `subject`")
@@ -244,8 +275,8 @@ export function createEntitlements(options = {}) {
      * 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]
+     * @param {string} subject - the subject identifier whose override is cleared
+     * @param {{ features?: string[], limits?: string[] }} [keys] - the specific feature and limit keys to revert; omit to clear the entire override
      */
     async clearOverride(subject, keys) {
       if (!subject) throw new Error("clearOverride requires a `subject`")
@@ -259,7 +290,7 @@ export function createEntitlements(options = {}) {
 
     /**
      * The subject's effective plan name (the default plan if unassigned).
-     * @param {string} subject
+     * @param {string} subject - the subject identifier to resolve
      * @returns {Promise<string>}
      */
     async plan(subject) {
@@ -270,8 +301,8 @@ export function createEntitlements(options = {}) {
      * 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
+     * @param {string} subject - the subject identifier to resolve
+     * @param {string} feature - the feature key to check; must be in the declared/derived feature universe
      * @returns {Promise<boolean>}
      */
     async can(subject, feature) {
@@ -288,8 +319,8 @@ export function createEntitlements(options = {}) {
      * 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
+     * @param {string} subject - the subject identifier to resolve
+     * @param {string} key - the limit key to resolve; must be in the declared/derived limit universe
      * @returns {Promise<number|null>}
      */
     limit(subject, key) {
@@ -301,7 +332,7 @@ export function createEntitlements(options = {}) {
      * reads current usage from the meter for the metric of the same name. This is
      * the composition seam: entitle supplies the limit, meter supplies the usage.
      * Requires a `meter` to have been passed to `createEntitlements`.
-     * @param {string} subject
+     * @param {string} subject - the subject identifier; must match the id usage is recorded under in the meter
      * @param {string} key - a limit key that is also a meter metric
      * @param {{ period?: any, range?: any }} [usageQuery] - forwarded to `meter.usage`
      * @returns {Promise<CheckResult>}
@@ -328,7 +359,7 @@ export function createEntitlements(options = {}) {
 
     /**
      * The subject's full effective entitlements, for a settings or billing page.
-     * @param {string} subject
+     * @param {string} subject - the subject identifier to resolve
      * @returns {Promise<Effective>}
      */
     async describe(subject) {

package/types/entitlements.d.ts

@@ -9,9 +9,19 @@
 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
+     * @param {string} subject - the subject identifier (whatever id you key entitlements by, such as an account or user id)
      * @param {string} plan - a key of the plan catalog
      */
     assign(subject: string, plan: string): Promise<void>;
@@ -19,7 +29,7 @@ export function createEntitlements(options?: EntitlementsOptions): {
      * 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
+     * @param {string} subject - the subject identifier whose assignment is removed
      */
     unassign(subject: string): Promise<void>;
     /**
@@ -28,16 +38,16 @@ export function createEntitlements(options?: EntitlementsOptions): {
      * 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
+     * @param {string} subject - the subject identifier to override
+     * @param {Override} data - the features and/or limits to override; merged into any existing override
      */
     override(subject: string, data: Override): Promise<void>;
     /**
      * 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]
+     * @param {string} subject - the subject identifier whose override is cleared
+     * @param {{ features?: string[], limits?: string[] }} [keys] - the specific feature and limit keys to revert; omit to clear the entire override
      */
     clearOverride(subject: string, keys?: {
         features?: string[];
@@ -45,7 +55,7 @@ export function createEntitlements(options?: EntitlementsOptions): {
     }): Promise<void>;
     /**
      * The subject's effective plan name (the default plan if unassigned).
-     * @param {string} subject
+     * @param {string} subject - the subject identifier to resolve
      * @returns {Promise<string>}
      */
     plan(subject: string): Promise<string>;
@@ -53,8 +63,8 @@ export function createEntitlements(options?: EntitlementsOptions): {
      * 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
+     * @param {string} subject - the subject identifier to resolve
+     * @param {string} feature - the feature key to check; must be in the declared/derived feature universe
      * @returns {Promise<boolean>}
      */
     can(subject: string, feature: string): Promise<boolean>;
@@ -64,8 +74,8 @@ export function createEntitlements(options?: EntitlementsOptions): {
      * 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
+     * @param {string} subject - the subject identifier to resolve
+     * @param {string} key - the limit key to resolve; must be in the declared/derived limit universe
      * @returns {Promise<number|null>}
      */
     limit(subject: string, key: string): Promise<number | null>;
@@ -74,7 +84,7 @@ export function createEntitlements(options?: EntitlementsOptions): {
      * reads current usage from the meter for the metric of the same name. This is
      * the composition seam: entitle supplies the limit, meter supplies the usage.
      * Requires a `meter` to have been passed to `createEntitlements`.
-     * @param {string} subject
+     * @param {string} subject - the subject identifier; must match the id usage is recorded under in the meter
      * @param {string} key - a limit key that is also a meter metric
      * @param {{ period?: any, range?: any }} [usageQuery] - forwarded to `meter.usage`
      * @returns {Promise<CheckResult>}
@@ -85,7 +95,7 @@ export function createEntitlements(options?: EntitlementsOptions): {
     }): Promise<CheckResult>;
     /**
      * The subject's full effective entitlements, for a settings or billing page.
-     * @param {string} subject
+     * @param {string} subject - the subject identifier to resolve
      * @returns {Promise<Effective>}
      */
     describe(subject: string): Promise<Effective>;
@@ -108,7 +118,13 @@ export type Plan = {
  * negotiated more seats, or got one feature switched on).
  */
 export type Override = {
+    /**
+     * - feature flags to override for this subject; merged over the plan's features, so include only the ones that differ
+     */
     features?: Record<string, boolean>;
+    /**
+     * - limit ceilings to override for this subject; merged over the plan's limits, so include only the ones that differ (`null` means unlimited)
+     */
     limits?: Record<string, number | null>;
 };
 export type EntitlementsOptions = {
@@ -151,12 +167,36 @@ export type EntitlementsOptions = {
 };
 export type Effective = {
     /**
-     * - the effective plan name
+     * - the effective plan name (the default plan if the subject is unassigned)
      */
     plan: string;
+    /**
+     * - the resolved feature flags, after applying the subject's override on top of the plan
+     */
     features: Record<string, boolean>;
+    /**
+     * - the resolved limit ceilings, after applying the subject's override on top of the plan (`null` means unlimited)
+     */
     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)