@owlmeans/payment 0.1.18-rc.7 → 0.1.18-rc.9

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/payment",
-  "version": "0.1.18-rc.7",
-  "generatedAt": "2026-08-24T21:14:00.136Z",
+  "version": "0.1.18-rc.8",
+  "generatedAt": "2026-08-27T16:32:18.507Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/payment/SKILL.md

@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/payment
 
 **Layer:** Core
-**Install:** `"@owlmeans/payment": "^0.1.18-rc.7"` in `dependencies`
+**Install:** `"@owlmeans/payment": "^0.1.18-rc.8"` in `dependencies`
 
 ## Key Exports
 

package/build/entitlement.d.ts

@@ -0,0 +1,60 @@
+import type { CommonEntrypointOptions } from '@owlmeans/entrypoint';
+import type { PermissionSet } from '@owlmeans/auth';
+/**
+ * The gate alias a paid capability is asserted under.
+ *
+ * Distinct from `paymentGate.base` (a ROUTE id) and from the gateway service alias — three
+ * different things that would otherwise all be called "payment gate".
+ */
+export declare const ENTITLEMENT_GATE = "entitlement-gate";
+/**
+ * The capability scope that carries FEATURE flags.
+ *
+ * Kept apart from `renewable`, which carries numeric quotas that are consumed or counted. Merging
+ * them would make "has one production slot left" and "may remove the platform credit" the same
+ * number, and the first purchase that spent the quota would take the feature with it.
+ */
+export declare const CAPABILITY_FEATURE_SCOPE = "feature";
+export interface EntitlementParam {
+    /** Capability scope. Absent means any scope. */
+    scope?: string;
+    /** The permission key inside `PermissionSet.permissions`. */
+    permission: string;
+    /** Numeric floor: `credits>=100` passes when the held value is a number at least that big. */
+    atLeast?: number;
+}
+/**
+ * Grammar: `[<scope>:]<permission>[>=<n>]`.
+ *
+ * `feature:branding--whitelabel` · `renewable:credits>=100` · `production--standalone`
+ *
+ * `@` is deliberately not part of it: that is `@owlmeans/iam`'s resource-selector syntax, and a
+ * grammar that reused it would make two different things look the same in a route declaration.
+ */
+export declare const parseEntitlementParam: (param: string) => EntitlementParam;
+export declare const formatEntitlementParam: (parsed: EntitlementParam) => string;
+/**
+ * Whether a union of capability sets satisfies one requirement.
+ *
+ * Pure, and shared by the server gate and the browser: the UI has to know whether to render a
+ * control disabled, and a second implementation of the rule for the client would eventually
+ * disagree with the one that actually refuses.
+ *
+ * A malformed parameter answers `false` rather than throwing. A gate that crashed on a typo would
+ * take down the endpoint it guards, which is a strictly worse failure than refusing it.
+ */
+export declare const hasEntitlement: (capabilities: PermissionSet[] | undefined, param: string) => boolean;
+/** Everything a union grants, formatted back into parameters. The wire shape of a client read. */
+export declare const entitlementList: (capabilities: PermissionSet[] | undefined) => string[];
+/**
+ * Declare that an entrypoint needs a paid capability.
+ *
+ * Sugar over `gate(ENTITLEMENT_GATE, params)` so a route reads as what it means. Several
+ * parameters are OR'd, matching every other gate in the framework.
+ *
+ * Putting the requirement HERE rather than in a handler is the point: the framework asserts a gate
+ * before the handler is entered, so the route table states what a feature costs and no new
+ * endpoint can forget to check.
+ */
+export declare const entitled: (params: string | string[], opts?: CommonEntrypointOptions) => CommonEntrypointOptions;
+//# sourceMappingURL=entitlement.d.ts.map

package/build/entitlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlement.d.ts","sourceRoot":"","sources":["../src/entitlement.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAA;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,YAAY,CAAA;AAEjD,MAAM,WAAW,gBAAgB;IAC/B,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAA;IAClB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,UAAW,MAAM,KAAG,gBAerD,CAAA;AAED,eAAO,MAAM,sBAAsB,WAAY,gBAAgB,KAAG,MAER,CAAA;AAE1D;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,iBACX,aAAa,EAAE,GAAG,SAAS,SAAS,MAAM,KACvD,OAqBF,CAAA;AAED,kGAAkG;AAClG,eAAO,MAAM,eAAe,iBAAkB,aAAa,EAAE,GAAG,SAAS,KAAG,MAAM,EAYjF,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,WACX,MAAM,GAAG,MAAM,EAAE,SAAS,uBAAuB,KACxD,uBAA+D,CAAA"}

package/build/entitlement.js

@@ -0,0 +1,95 @@
+import { gate } from '@owlmeans/entrypoint';
+/**
+ * The gate alias a paid capability is asserted under.
+ *
+ * Distinct from `paymentGate.base` (a ROUTE id) and from the gateway service alias — three
+ * different things that would otherwise all be called "payment gate".
+ */
+export const ENTITLEMENT_GATE = 'entitlement-gate';
+/**
+ * The capability scope that carries FEATURE flags.
+ *
+ * Kept apart from `renewable`, which carries numeric quotas that are consumed or counted. Merging
+ * them would make "has one production slot left" and "may remove the platform credit" the same
+ * number, and the first purchase that spent the quota would take the feature with it.
+ */
+export const CAPABILITY_FEATURE_SCOPE = 'feature';
+/**
+ * Grammar: `[<scope>:]<permission>[>=<n>]`.
+ *
+ * `feature:branding--whitelabel` · `renewable:credits>=100` · `production--standalone`
+ *
+ * `@` is deliberately not part of it: that is `@owlmeans/iam`'s resource-selector syntax, and a
+ * grammar that reused it would make two different things look the same in a route declaration.
+ */
+export const parseEntitlementParam = (param) => {
+    const [scoped, floor] = param.split('>=');
+    const colon = scoped.indexOf(':');
+    const parsed = colon >= 0
+        ? { scope: scoped.slice(0, colon), permission: scoped.slice(colon + 1) }
+        : { permission: scoped };
+    if (floor != null) {
+        const value = Number.parseFloat(floor);
+        if (!Number.isNaN(value)) {
+            parsed.atLeast = value;
+        }
+    }
+    return parsed;
+};
+export const formatEntitlementParam = (parsed) => `${parsed.scope != null ? `${parsed.scope}:` : ''}${parsed.permission}` +
+    `${parsed.atLeast != null ? `>=${parsed.atLeast}` : ''}`;
+/**
+ * Whether a union of capability sets satisfies one requirement.
+ *
+ * Pure, and shared by the server gate and the browser: the UI has to know whether to render a
+ * control disabled, and a second implementation of the rule for the client would eventually
+ * disagree with the one that actually refuses.
+ *
+ * A malformed parameter answers `false` rather than throwing. A gate that crashed on a typo would
+ * take down the endpoint it guards, which is a strictly worse failure than refusing it.
+ */
+export const hasEntitlement = (capabilities, param) => {
+    if (capabilities == null || capabilities.length < 1) {
+        return false;
+    }
+    const { scope, permission, atLeast } = parseEntitlementParam(param);
+    if (permission === '') {
+        return false;
+    }
+    return capabilities.some(set => {
+        if (scope != null && set.scope !== scope) {
+            return false;
+        }
+        const held = set.permissions?.[permission];
+        if (held == null || held === false) {
+            return false;
+        }
+        // A floor is a numeric question: a boolean flag, however true, does not answer it.
+        return atLeast != null ? typeof held === 'number' && held >= atLeast : true;
+    });
+};
+/** Everything a union grants, formatted back into parameters. The wire shape of a client read. */
+export const entitlementList = (capabilities) => {
+    const list = [];
+    for (const set of capabilities ?? []) {
+        for (const [permission, value] of Object.entries(set.permissions ?? {})) {
+            if (value == null || value === false) {
+                continue;
+            }
+            list.push(formatEntitlementParam({ scope: set.scope, permission }));
+        }
+    }
+    return [...new Set(list)];
+};
+/**
+ * Declare that an entrypoint needs a paid capability.
+ *
+ * Sugar over `gate(ENTITLEMENT_GATE, params)` so a route reads as what it means. Several
+ * parameters are OR'd, matching every other gate in the framework.
+ *
+ * Putting the requirement HERE rather than in a handler is the point: the framework asserts a gate
+ * before the handler is entered, so the route table states what a feature costs and no new
+ * endpoint can forget to check.
+ */
+export const entitled = (params, opts) => gate(ENTITLEMENT_GATE, params, opts);
+//# sourceMappingURL=entitlement.js.map

package/build/entitlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlement.js","sourceRoot":"","sources":["../src/entitlement.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -2,6 +2,7 @@ export type * from './types.js';
 export * from './model/index.js';
 export * from './errors.js';
 export * from './consts.js';
+export * from './entitlement.js';
 export * from './service.js';
 export * from './i18n.js';
 export * from './helper.js';

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}

package/build/index.js

@@ -1,6 +1,7 @@
 export * from './model/index.js';
 export * from './errors.js';
 export * from './consts.js';
+export * from './entitlement.js';
 export * from './service.js';
 export * from './i18n.js';
 export * from './helper.js';

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,kBAAkB,CAAA;AAChC,cAAc,cAAc,CAAA;AAC5B,cAAc,WAAW,CAAA;AACzB,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/payment",
-  "version": "0.1.18-rc.7",
+  "version": "0.1.18-rc.9",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -31,13 +31,13 @@
     "ajv": "*"
   },
   "dependencies": {
-    "@owlmeans/auth": "^0.1.18-rc.6",
-    "@owlmeans/basic-envelope": "^0.1.18-rc.7",
-    "@owlmeans/config": "^0.1.18-rc.7",
+    "@owlmeans/auth": "^0.1.18-rc.7",
+    "@owlmeans/basic-envelope": "^0.1.18-rc.9",
+    "@owlmeans/config": "^0.1.18-rc.8",
     "@owlmeans/context": "^0.1.18-rc.6",
     "@owlmeans/error": "^0.1.18-rc.6",
     "@owlmeans/i18n": "^0.1.18-rc.6",
-    "@owlmeans/entrypoint": "^0.1.18-rc.7",
+    "@owlmeans/entrypoint": "^0.1.18-rc.8",
     "@owlmeans/resource": "^0.1.18-rc.7",
     "@owlmeans/route": "^0.1.18-rc.6"
   },

package/src/entitlement.ts

@@ -0,0 +1,122 @@
+import { gate } from '@owlmeans/entrypoint'
+import type { CommonEntrypointOptions } from '@owlmeans/entrypoint'
+import type { PermissionSet } from '@owlmeans/auth'
+
+/**
+ * The gate alias a paid capability is asserted under.
+ *
+ * Distinct from `paymentGate.base` (a ROUTE id) and from the gateway service alias — three
+ * different things that would otherwise all be called "payment gate".
+ */
+export const ENTITLEMENT_GATE = 'entitlement-gate'
+
+/**
+ * The capability scope that carries FEATURE flags.
+ *
+ * Kept apart from `renewable`, which carries numeric quotas that are consumed or counted. Merging
+ * them would make "has one production slot left" and "may remove the platform credit" the same
+ * number, and the first purchase that spent the quota would take the feature with it.
+ */
+export const CAPABILITY_FEATURE_SCOPE = 'feature'
+
+export interface EntitlementParam {
+  /** Capability scope. Absent means any scope. */
+  scope?: string
+  /** The permission key inside `PermissionSet.permissions`. */
+  permission: string
+  /** Numeric floor: `credits>=100` passes when the held value is a number at least that big. */
+  atLeast?: number
+}
+
+/**
+ * Grammar: `[<scope>:]<permission>[>=<n>]`.
+ *
+ * `feature:branding--whitelabel` · `renewable:credits>=100` · `production--standalone`
+ *
+ * `@` is deliberately not part of it: that is `@owlmeans/iam`'s resource-selector syntax, and a
+ * grammar that reused it would make two different things look the same in a route declaration.
+ */
+export const parseEntitlementParam = (param: string): EntitlementParam => {
+  const [scoped, floor] = param.split('>=')
+  const colon = scoped.indexOf(':')
+  const parsed: EntitlementParam = colon >= 0
+    ? { scope: scoped.slice(0, colon), permission: scoped.slice(colon + 1) }
+    : { permission: scoped }
+
+  if (floor != null) {
+    const value = Number.parseFloat(floor)
+    if (!Number.isNaN(value)) {
+      parsed.atLeast = value
+    }
+  }
+
+  return parsed
+}
+
+export const formatEntitlementParam = (parsed: EntitlementParam): string =>
+  `${parsed.scope != null ? `${parsed.scope}:` : ''}${parsed.permission}` +
+  `${parsed.atLeast != null ? `>=${parsed.atLeast}` : ''}`
+
+/**
+ * Whether a union of capability sets satisfies one requirement.
+ *
+ * Pure, and shared by the server gate and the browser: the UI has to know whether to render a
+ * control disabled, and a second implementation of the rule for the client would eventually
+ * disagree with the one that actually refuses.
+ *
+ * A malformed parameter answers `false` rather than throwing. A gate that crashed on a typo would
+ * take down the endpoint it guards, which is a strictly worse failure than refusing it.
+ */
+export const hasEntitlement = (
+  capabilities: PermissionSet[] | undefined, param: string
+): boolean => {
+  if (capabilities == null || capabilities.length < 1) {
+    return false
+  }
+  const { scope, permission, atLeast } = parseEntitlementParam(param)
+  if (permission === '') {
+    return false
+  }
+
+  return capabilities.some(set => {
+    if (scope != null && set.scope !== scope) {
+      return false
+    }
+    const held = set.permissions?.[permission]
+    if (held == null || held === false) {
+      return false
+    }
+
+    // A floor is a numeric question: a boolean flag, however true, does not answer it.
+    return atLeast != null ? typeof held === 'number' && held >= atLeast : true
+  })
+}
+
+/** Everything a union grants, formatted back into parameters. The wire shape of a client read. */
+export const entitlementList = (capabilities: PermissionSet[] | undefined): string[] => {
+  const list: string[] = []
+  for (const set of capabilities ?? []) {
+    for (const [permission, value] of Object.entries(set.permissions ?? {})) {
+      if (value == null || value === false) {
+        continue
+      }
+      list.push(formatEntitlementParam({ scope: set.scope, permission }))
+    }
+  }
+
+  return [...new Set(list)]
+}
+
+/**
+ * Declare that an entrypoint needs a paid capability.
+ *
+ * Sugar over `gate(ENTITLEMENT_GATE, params)` so a route reads as what it means. Several
+ * parameters are OR'd, matching every other gate in the framework.
+ *
+ * Putting the requirement HERE rather than in a handler is the point: the framework asserts a gate
+ * before the handler is entered, so the route table states what a feature costs and no new
+ * endpoint can forget to check.
+ */
+export const entitled = (
+  params: string | string[], opts?: CommonEntrypointOptions
+): CommonEntrypointOptions => gate(ENTITLEMENT_GATE, params, opts)

package/src/index.ts

@@ -3,6 +3,7 @@ export type * from './types.js'
 export * from './model/index.js'
 export * from './errors.js'
 export * from './consts.js'
+export * from './entitlement.js'
 export * from './service.js'
 export * from './i18n.js'
 export * from './helper.js'

package/tests/entitlement.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=entitlement.spec.d.ts.map

package/tests/entitlement.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlement.spec.d.ts","sourceRoot":"","sources":["entitlement.spec.ts"],"names":[],"mappings":""}

package/tests/entitlement.spec.js

@@ -0,0 +1,72 @@
+import { describe, test, expect } from 'bun:test';
+import { CAPABILITY_FEATURE_SCOPE, entitlementList, formatEntitlementParam, hasEntitlement, parseEntitlementParam, } from '../src/entitlement.js';
+const pro = [
+    { scope: 'renewable', permissions: { production: 1, credits: 5000 } },
+    { scope: CAPABILITY_FEATURE_SCOPE, permissions: { 'branding--whitelabel': true, 'domain--custom': true } },
+];
+describe('the parameter grammar', () => {
+    test('a bare permission has no scope and no floor', () => {
+        expect(parseEntitlementParam('domain--custom')).toEqual({ permission: 'domain--custom' });
+    });
+    test('a scope is everything before the first colon', () => {
+        expect(parseEntitlementParam('feature:branding--whitelabel'))
+            .toEqual({ scope: 'feature', permission: 'branding--whitelabel' });
+    });
+    test('a floor is parsed as a number', () => {
+        expect(parseEntitlementParam('renewable:credits>=100'))
+            .toEqual({ scope: 'renewable', permission: 'credits', atLeast: 100 });
+    });
+    test('formatting round-trips', () => {
+        for (const param of ['domain--custom', 'feature:branding--whitelabel', 'renewable:credits>=100']) {
+            expect(formatEntitlementParam(parseEntitlementParam(param))).toBe(param);
+        }
+    });
+});
+describe('the predicate', () => {
+    test('a held feature passes', () => {
+        expect(hasEntitlement(pro, 'feature:branding--whitelabel')).toBe(true);
+    });
+    test('a feature nobody granted does not', () => {
+        expect(hasEntitlement(pro, 'feature:branding--nonexistent')).toBe(false);
+    });
+    test('a scope that does not match is not consulted', () => {
+        expect(hasEntitlement(pro, 'renewable:branding--whitelabel')).toBe(false);
+        // …and without a scope, any set may answer.
+        expect(hasEntitlement(pro, 'branding--whitelabel')).toBe(true);
+    });
+    test('a numeric floor compares', () => {
+        expect(hasEntitlement(pro, 'renewable:credits>=5000')).toBe(true);
+        expect(hasEntitlement(pro, 'renewable:credits>=5001')).toBe(false);
+    });
+    test('a boolean cannot satisfy a numeric floor', () => {
+        expect(hasEntitlement(pro, 'feature:branding--whitelabel>=1')).toBe(false);
+    });
+    test('an explicit false is not a grant', () => {
+        expect(hasEntitlement([{ scope: 'feature', permissions: { x: false } }], 'feature:x')).toBe(false);
+        expect(hasEntitlement([{ scope: 'feature', permissions: { x: null } }], 'feature:x')).toBe(false);
+    });
+    test('no capabilities at all is a refusal, never a pass', () => {
+        expect(hasEntitlement(undefined, 'feature:branding--whitelabel')).toBe(false);
+        expect(hasEntitlement([], 'feature:branding--whitelabel')).toBe(false);
+    });
+    test('a malformed parameter refuses rather than throwing', () => {
+        // A gate that crashed on a typo would take down the endpoint it guards.
+        expect(() => hasEntitlement(pro, '')).not.toThrow();
+        expect(hasEntitlement(pro, '')).toBe(false);
+        expect(hasEntitlement(pro, 'feature:')).toBe(false);
+        expect(hasEntitlement(pro, 'renewable:credits>=abc')).toBe(true);
+    });
+});
+describe('listing', () => {
+    test('unions every granted capability, scoped', () => {
+        expect(entitlementList(pro).sort()).toEqual([
+            'feature:branding--whitelabel', 'feature:domain--custom',
+            'renewable:credits', 'renewable:production',
+        ]);
+    });
+    test('skips what is not granted', () => {
+        expect(entitlementList([{ scope: 'feature', permissions: { a: true, b: false, c: null } }]))
+            .toEqual(['feature:a']);
+    });
+});
+//# sourceMappingURL=entitlement.spec.js.map

package/tests/entitlement.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitlement.spec.js","sourceRoot":"","sources":["entitlement.spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EACL,wBAAwB,EAAE,eAAe,EAAE,sBAAsB,EAAE,cAAc,EACjF,qBAAqB,GACtB,MAAM,uBAAuB,CAAA;AAG9B,MAAM,GAAG,GAAoB;IAC3B,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;IACrE,EAAE,KAAK,EAAE,wBAAwB,EAAE,WAAW,EAAE,EAAE,sBAAsB,EAAE,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,EAAE;CAC3G,CAAA;AAED,QAAQ,CAAC,uBAAuB,EAAE,GAAG,EAAE;IACrC,IAAI,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACvD,MAAM,CAAC,qBAAqB,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,gBAAgB,EAAE,CAAC,CAAA;IAC3F,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,qBAAqB,CAAC,8BAA8B,CAAC,CAAC;aAC1D,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,sBAAsB,EAAE,CAAC,CAAA;IACtE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,qBAAqB,CAAC,wBAAwB,CAAC,CAAC;aACpD,OAAO,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAA;IACzE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,wBAAwB,EAAE,GAAG,EAAE;QAClC,KAAK,MAAM,KAAK,IAAI,CAAC,gBAAgB,EAAE,8BAA8B,EAAE,wBAAwB,CAAC,EAAE,CAAC;YACjG,MAAM,CAAC,sBAAsB,CAAC,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC1E,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,IAAI,CAAC,uBAAuB,EAAE,GAAG,EAAE;QACjC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,8BAA8B,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACxE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC7C,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,+BAA+B,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC1E,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,gCAAgC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACzE,4CAA4C;QAC5C,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,sBAAsB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,0BAA0B,EAAE,GAAG,EAAE;QACpC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACjE,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,0CAA0C,EAAE,GAAG,EAAE;QACpD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,iCAAiC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC5E,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAClG,MAAM,CAAC,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACnG,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,cAAc,CAAC,SAAS,EAAE,8BAA8B,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC7E,MAAM,CAAC,cAAc,CAAC,EAAE,EAAE,8BAA8B,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACxE,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC9D,wEAAwE;QACxE,MAAM,CAAC,GAAG,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,CAAA;QACnD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC3C,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACnD,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClE,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,SAAS,EAAE,GAAG,EAAE;IACvB,IAAI,CAAC,yCAAyC,EAAE,GAAG,EAAE;QACnD,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC;YAC1C,8BAA8B,EAAE,wBAAwB;YACxD,mBAAmB,EAAE,sBAAsB;SAC5C,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;aACzF,OAAO,CAAC,CAAC,WAAW,CAAC,CAAC,CAAA;IAC3B,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/tests/entitlement.spec.ts

@@ -0,0 +1,90 @@
+import { describe, test, expect } from 'bun:test'
+import {
+  CAPABILITY_FEATURE_SCOPE, entitlementList, formatEntitlementParam, hasEntitlement,
+  parseEntitlementParam,
+} from '../src/entitlement.js'
+import type { PermissionSet } from '@owlmeans/auth'
+
+const pro: PermissionSet[] = [
+  { scope: 'renewable', permissions: { production: 1, credits: 5000 } },
+  { scope: CAPABILITY_FEATURE_SCOPE, permissions: { 'branding--whitelabel': true, 'domain--custom': true } },
+]
+
+describe('the parameter grammar', () => {
+  test('a bare permission has no scope and no floor', () => {
+    expect(parseEntitlementParam('domain--custom')).toEqual({ permission: 'domain--custom' })
+  })
+
+  test('a scope is everything before the first colon', () => {
+    expect(parseEntitlementParam('feature:branding--whitelabel'))
+      .toEqual({ scope: 'feature', permission: 'branding--whitelabel' })
+  })
+
+  test('a floor is parsed as a number', () => {
+    expect(parseEntitlementParam('renewable:credits>=100'))
+      .toEqual({ scope: 'renewable', permission: 'credits', atLeast: 100 })
+  })
+
+  test('formatting round-trips', () => {
+    for (const param of ['domain--custom', 'feature:branding--whitelabel', 'renewable:credits>=100']) {
+      expect(formatEntitlementParam(parseEntitlementParam(param))).toBe(param)
+    }
+  })
+})
+
+describe('the predicate', () => {
+  test('a held feature passes', () => {
+    expect(hasEntitlement(pro, 'feature:branding--whitelabel')).toBe(true)
+  })
+
+  test('a feature nobody granted does not', () => {
+    expect(hasEntitlement(pro, 'feature:branding--nonexistent')).toBe(false)
+  })
+
+  test('a scope that does not match is not consulted', () => {
+    expect(hasEntitlement(pro, 'renewable:branding--whitelabel')).toBe(false)
+    // …and without a scope, any set may answer.
+    expect(hasEntitlement(pro, 'branding--whitelabel')).toBe(true)
+  })
+
+  test('a numeric floor compares', () => {
+    expect(hasEntitlement(pro, 'renewable:credits>=5000')).toBe(true)
+    expect(hasEntitlement(pro, 'renewable:credits>=5001')).toBe(false)
+  })
+
+  test('a boolean cannot satisfy a numeric floor', () => {
+    expect(hasEntitlement(pro, 'feature:branding--whitelabel>=1')).toBe(false)
+  })
+
+  test('an explicit false is not a grant', () => {
+    expect(hasEntitlement([{ scope: 'feature', permissions: { x: false } }], 'feature:x')).toBe(false)
+    expect(hasEntitlement([{ scope: 'feature', permissions: { x: null } }], 'feature:x')).toBe(false)
+  })
+
+  test('no capabilities at all is a refusal, never a pass', () => {
+    expect(hasEntitlement(undefined, 'feature:branding--whitelabel')).toBe(false)
+    expect(hasEntitlement([], 'feature:branding--whitelabel')).toBe(false)
+  })
+
+  test('a malformed parameter refuses rather than throwing', () => {
+    // A gate that crashed on a typo would take down the endpoint it guards.
+    expect(() => hasEntitlement(pro, '')).not.toThrow()
+    expect(hasEntitlement(pro, '')).toBe(false)
+    expect(hasEntitlement(pro, 'feature:')).toBe(false)
+    expect(hasEntitlement(pro, 'renewable:credits>=abc')).toBe(true)
+  })
+})
+
+describe('listing', () => {
+  test('unions every granted capability, scoped', () => {
+    expect(entitlementList(pro).sort()).toEqual([
+      'feature:branding--whitelabel', 'feature:domain--custom',
+      'renewable:credits', 'renewable:production',
+    ])
+  })
+
+  test('skips what is not granted', () => {
+    expect(entitlementList([{ scope: 'feature', permissions: { a: true, b: false, c: null } }]))
+      .toEqual(['feature:a'])
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -6,5 +6,10 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./tests/**/*",
+    "./*.ts"
+  ]
 }