@stigg/entitlements-runtime 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { EntitlementEvaluator } from './services/entitlementEvaluator';
+export { Decision } from './services/entitlementDecisionService';
+export { EntitlementFallbacks } from './services/entitlementFallbacks';
+export { EntitlementEvaluation, FeatureEntitlementKind, ResolvedCreditEntitlement, ResolvedFeatureEntitlement, } from './types/entitlementEvaluation';
+export { BooleanEntitlementFallback, CreditEntitlementFallback, CreditEntitlementsFallback, EntitlementFallbackConfig, EntitlementFallback, EntitlementsFallback, EnumEntitlementFallback, MeteredEntitlementFallback, NumericEntitlementFallback, } from './types/entitlementFallback';
+export { BooleanEntitlementOptions, CreditEntitlementOptions, EntitlementReadOptions, EnumEntitlementOptions, FeatureEntitlementOptions, MeteredEntitlementOptions, NumericEntitlementOptions, } from './types/entitlementOptions';

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitlementFallbacks = exports.EntitlementEvaluator = void 0;
+// Evaluator
+var entitlementEvaluator_1 = require("./services/entitlementEvaluator");
+Object.defineProperty(exports, "EntitlementEvaluator", { enumerable: true, get: function () { return entitlementEvaluator_1.EntitlementEvaluator; } });
+var entitlementFallbacks_1 = require("./services/entitlementFallbacks");
+Object.defineProperty(exports, "EntitlementFallbacks", { enumerable: true, get: function () { return entitlementFallbacks_1.EntitlementFallbacks; } });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEsWUFBWTtBQUNaLHdFQUF1RTtBQUE5RCw0SEFBQSxvQkFBb0IsT0FBQTtBQUU3Qix3RUFBdUU7QUFBOUQsNEhBQUEsb0JBQW9CLE9BQUEifQ==

package/dist/services/entitlementDecisionService.d.ts

@@ -0,0 +1,19 @@
+import { AccessDeniedReason, CachedEntitlement, EntitlementType, Maybe } from '@stigg/cache-core';
+export interface DecideEntitlementPolicyParams {
+    entitlementType: EntitlementType;
+    accessDeniedReason: Maybe<AccessDeniedReason>;
+    entitlement: Maybe<CachedEntitlement>;
+    requestedUsage?: number;
+    requestedValues?: string[];
+}
+export declare class EntitlementDecisionService {
+    static decideEntitlementPolicy({ entitlementType, accessDeniedReason, entitlement, requestedUsage, requestedValues, }: DecideEntitlementPolicyParams): Decision;
+    private static getNotFoundReason;
+    private static decideFeatureAccess;
+    private static decideCreditAccess;
+    private static decideUsageBasedAccess;
+}
+export interface Decision {
+    readonly hasAccess: boolean;
+    readonly accessDeniedReason?: AccessDeniedReason;
+}

package/dist/services/entitlementDecisionService.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitlementDecisionService = void 0;
+const cache_core_1 = require("@stigg/cache-core");
+const lodash_1 = require("lodash");
+class EntitlementDecisionService {
+    static decideEntitlementPolicy({ entitlementType, accessDeniedReason, entitlement, requestedUsage = 0, requestedValues = [], }) {
+        // Entitlement-first: if found, evaluate it normally.
+        // Fall back to global accessDeniedReason only when no entitlement exists.
+        if (!entitlement) {
+            if (accessDeniedReason) {
+                return { accessDeniedReason, hasAccess: false };
+            }
+            return { hasAccess: false, accessDeniedReason: this.getNotFoundReason(entitlementType) };
+        }
+        if (entitlement.calculatedEntitlement.accessDeniedReason) {
+            return {
+                hasAccess: false,
+                accessDeniedReason: entitlement.calculatedEntitlement.accessDeniedReason,
+            };
+        }
+        if ((0, cache_core_1.isCreditEntitlement)(entitlement)) {
+            return this.decideCreditAccess(entitlement);
+        }
+        if ((0, cache_core_1.isFeatureEntitlement)(entitlement)) {
+            return this.decideFeatureAccess(entitlement, requestedUsage, requestedValues);
+        }
+        return { hasAccess: false, accessDeniedReason: cache_core_1.AccessDeniedReason.NoFeatureEntitlementInSubscription };
+    }
+    static getNotFoundReason(entitlementType) {
+        if (entitlementType === cache_core_1.EntitlementType.Feature) {
+            // for backward compatability
+            return cache_core_1.AccessDeniedReason.NoFeatureEntitlementInSubscription;
+        }
+        return cache_core_1.AccessDeniedReason.EntitlementNotFound;
+    }
+    static decideFeatureAccess(entitlement, requestUsage, requestedValues) {
+        const { feature } = entitlement.calculatedEntitlement;
+        const { featureType, meterType } = feature;
+        switch (featureType) {
+            case cache_core_1.FeatureType.Boolean:
+                return { hasAccess: true };
+            case cache_core_1.FeatureType.Enum: {
+                const missingValues = (0, lodash_1.difference)(requestedValues, entitlement.calculatedEntitlement.enumValues || []);
+                if (!(0, lodash_1.isEmpty)(missingValues)) {
+                    return {
+                        hasAccess: false,
+                        accessDeniedReason: cache_core_1.AccessDeniedReason.RequestedValuesMismatch,
+                    };
+                }
+                return { hasAccess: true };
+            }
+            case cache_core_1.FeatureType.Number: {
+                if (meterType === cache_core_1.MeterType.None) {
+                    return { hasAccess: true };
+                }
+                if (entitlement.calculatedEntitlement.hasUnlimitedUsage || entitlement.calculatedEntitlement.hasSoftLimit) {
+                    return { hasAccess: true };
+                }
+                const usageLimit = entitlement.calculatedEntitlement.usageLimit || 0;
+                const currentUsage = entitlement.usageData.currentUsage;
+                return this.decideUsageBasedAccess(usageLimit, currentUsage, requestUsage);
+            }
+        }
+    }
+    static decideCreditAccess(entitlement) {
+        if (entitlement.calculatedEntitlement.hasSoftLimit) {
+            return { hasAccess: true };
+        }
+        const { usageLimit } = entitlement.calculatedEntitlement;
+        const { currentUsage } = entitlement.usageData;
+        // checking at least 1 credit to deny access when none remaining
+        const requestUsage = 1;
+        return this.decideUsageBasedAccess(usageLimit, currentUsage, requestUsage);
+    }
+    static decideUsageBasedAccess(usageLimit, currentUsage, requestUsage) {
+        if (currentUsage + requestUsage <= usageLimit) {
+            return { hasAccess: true };
+        }
+        else {
+            return { hasAccess: false, accessDeniedReason: cache_core_1.AccessDeniedReason.RequestedUsageExceedingLimit };
+        }
+    }
+}
+exports.EntitlementDecisionService = EntitlementDecisionService;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW50aXRsZW1lbnREZWNpc2lvblNlcnZpY2UuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc2VydmljZXMvZW50aXRsZW1lbnREZWNpc2lvblNlcnZpY2UudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEsa0RBUzJCO0FBQzNCLG1DQUE2QztBQVU3QyxNQUFhLDBCQUEwQjtJQUM5QixNQUFNLENBQUMsdUJBQXVCLENBQUMsRUFDcEMsZUFBZSxFQUNmLGtCQUFrQixFQUNsQixXQUFXLEVBQ1gsY0FBYyxHQUFHLENBQUMsRUFDbEIsZUFBZSxHQUFHLEVBQUUsR0FDVTtRQUM5QixxREFBcUQ7UUFDckQsMEVBQTBFO1FBQzFFLElBQUksQ0FBQyxXQUFXLEVBQUUsQ0FBQztZQUNqQixJQUFJLGtCQUFrQixFQUFFLENBQUM7Z0JBQ3ZCLE9BQU8sRUFBRSxrQkFBa0IsRUFBRSxTQUFTLEVBQUUsS0FBSyxFQUFFLENBQUM7WUFDbEQsQ0FBQztZQUNELE9BQU8sRUFBRSxTQUFTLEVBQUUsS0FBSyxFQUFFLGtCQUFrQixFQUFFLElBQUksQ0FBQyxpQkFBaUIsQ0FBQyxlQUFlLENBQUMsRUFBRSxDQUFDO1FBQzNGLENBQUM7UUFFRCxJQUFJLFdBQVcsQ0FBQyxxQkFBcUIsQ0FBQyxrQkFBa0IsRUFBRSxDQUFDO1lBQ3pELE9BQU87Z0JBQ0wsU0FBUyxFQUFFLEtBQUs7Z0JBQ2hCLGtCQUFrQixFQUFFLFdBQVcsQ0FBQyxxQkFBcUIsQ0FBQyxrQkFBa0I7YUFDekUsQ0FBQztRQUNKLENBQUM7UUFFRCxJQUFJLElBQUEsZ0NBQW1CLEVBQUMsV0FBVyxDQUFDLEVBQUUsQ0FBQztZQUNyQyxPQUFPLElBQUksQ0FBQyxrQkFBa0IsQ0FBQyxXQUFXLENBQUMsQ0FBQztRQUM5QyxDQUFDO1FBRUQsSUFBSSxJQUFBLGlDQUFvQixFQUFDLFdBQVcsQ0FBQyxFQUFFLENBQUM7WUFDdEMsT0FBTyxJQUFJLENBQUMsbUJBQW1CLENBQUMsV0FBVyxF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

package/dist/services/entitlementEvaluator.d.ts

@@ -0,0 +1,24 @@
+import { AccessDeniedReason, CachedEntitlement, EntitlementQuery, EntitlementType, Maybe } from '@stigg/cache-core';
+import { EntitlementFallbacks } from './entitlementFallbacks';
+import { BooleanEntitlementOptions, CreditEntitlementOptions, EntitlementReadOptions, EnumEntitlementOptions, MeteredEntitlementOptions, NumericEntitlementOptions } from '../types/entitlementOptions';
+import { EntitlementEvaluation, FeatureEntitlement, FeatureQuery } from '../types/entitlementEvaluation';
+export declare class EntitlementEvaluator {
+    readonly fallbacks: EntitlementFallbacks;
+    constructor(fallbacks: EntitlementFallbacks);
+    evaluateBoolean(query: FeatureQuery, entitlement: FeatureEntitlement, accessDeniedReason: Maybe<AccessDeniedReason>, options?: BooleanEntitlementOptions): EntitlementEvaluation<EntitlementType.Feature>;
+    evaluateNumeric(query: FeatureQuery, entitlement: FeatureEntitlement, accessDeniedReason: Maybe<AccessDeniedReason>, options?: NumericEntitlementOptions): EntitlementEvaluation<EntitlementType.Feature>;
+    evaluateMetered(query: FeatureQuery, entitlement: FeatureEntitlement, accessDeniedReason: Maybe<AccessDeniedReason>, options?: MeteredEntitlementOptions): EntitlementEvaluation<EntitlementType.Feature>;
+    evaluateEnum(query: FeatureQuery, entitlement: FeatureEntitlement, accessDeniedReason: Maybe<AccessDeniedReason>, options?: EnumEntitlementOptions): EntitlementEvaluation<EntitlementType.Feature>;
+    evaluateCredit(query: EntitlementQuery<EntitlementType.Credit>, entitlement: CachedEntitlement<EntitlementType.Credit> | null, accessDeniedReason: Maybe<AccessDeniedReason>, options?: CreditEntitlementOptions): EntitlementEvaluation<EntitlementType.Credit>;
+    /**
+     * The type-agnostic path, for callers that state no expected kind up front, so the kind is
+     * inferred from the options rather than asserted against them.
+     *
+     * Differs from the typed reads on one point, deliberately: here a miss *does* answer from the
+     * fallback. The typed reads treat "not in the subscription" as a real answer and ignore the
+     * fallback; `getEntitlement`/`getEntitlementV2` have always fallen back instead, and callers
+     * depend on it. Only the precedence between a per-call and a configured fallback is shared.
+     */
+    evaluate<TType extends EntitlementType>(query: EntitlementQuery<TType>, cached: CachedEntitlement<TType> | null, accessDeniedReason: Maybe<AccessDeniedReason>, options?: EntitlementReadOptions): EntitlementEvaluation<TType>;
+    private evaluateFeature;
+}

package/dist/services/entitlementEvaluator.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitlementEvaluator = void 0;
+const cache_core_1 = require("@stigg/cache-core");
+const entitlementDecisionService_1 = require("./entitlementDecisionService");
+const entitlementOptions_1 = require("../types/entitlementOptions");
+const resolveEntitlement_1 = require("./resolveEntitlement");
+const MATCHES_KIND = {
+    BOOLEAN: cache_core_1.isBoolean,
+    NUMERIC: cache_core_1.isNumeric,
+    METERED: cache_core_1.isMetered,
+    ENUM: cache_core_1.isEnum,
+};
+class EntitlementEvaluator {
+    constructor(fallbacks) {
+        this.fallbacks = fallbacks;
+    }
+    evaluateBoolean(query, entitlement, accessDeniedReason, options) {
+        return this.evaluateFeature(query, entitlement, accessDeniedReason, 'BOOLEAN', options);
+    }
+    evaluateNumeric(query, entitlement, accessDeniedReason, options) {
+        return this.evaluateFeature(query, entitlement, accessDeniedReason, 'NUMERIC', options);
+    }
+    evaluateMetered(query, entitlement, accessDeniedReason, options) {
+        return this.evaluateFeature(query, entitlement, accessDeniedReason, 'METERED', options);
+    }
+    evaluateEnum(query, entitlement, accessDeniedReason, options) {
+        return this.evaluateFeature(query, entitlement, accessDeniedReason, 'ENUM', options);
+    }
+    evaluateCredit(query, entitlement, accessDeniedReason, options) {
+        var _a;
+        const decision = entitlementDecisionService_1.EntitlementDecisionService.decideEntitlementPolicy({
+            entitlementType: cache_core_1.EntitlementType.Credit,
+            accessDeniedReason,
+            entitlement,
+        });
+        // Unlike a feature miss, a credit miss does answer from the fallback when one is available.
+        const fallback = entitlement ? undefined : this.fallbacks.resolve(query, options === null || options === void 0 ? void 0 : options.fallback);
+        const hasAccess = (_a = fallback === null || fallback === void 0 ? void 0 : fallback.hasAccess) !== null && _a !== void 0 ? _a : decision.hasAccess;
+        return Object.assign(Object.assign({}, decision), { hasAccess, 
+            // The reason belongs to the decision that was overridden, so a granted answer must drop it —
+            // the same rule the untyped path applies.
+            accessDeniedReason: hasAccess ? undefined : decision.accessDeniedReason, query, resolved: (0, resolveEntitlement_1.resolveCredit)(query.id, entitlement, fallback), entitlement: entitlement !== null && entitlement !== void 0 ? entitlement : undefined, isFallback: !!fallback });
+    }
+    /**
+     * The type-agnostic path, for callers that state no expected kind up front, so the kind is
+     * inferred from the options rather than asserted against them.
+     *
+     * Differs from the typed reads on one point, deliberately: here a miss *does* answer from the
+     * fallback. The typed reads treat "not in the subscription" as a real answer and ignore the
+     * fallback; `getEntitlement`/`getEntitlementV2` have always fallen back instead, and callers
+     * depend on it. Only the precedence between a per-call and a configured fallback is shared.
+     */
+    evaluate(query, cached, accessDeniedReason, options) {
+        var _a;
+        // A persisted entry is keyed independently of the kind recorded inside it, and `fromJSON`
+        // checks neither — so treat a disagreeing entry as absent rather than answering with the kind
+        // it claims to be, which would hand a feature read a credit model.
+        const entitlement = (cached === null || cached === void 0 ? void 0 : cached.calculatedEntitlement.type) === query.type ? cached : null;
+        const { requestedUsage, requestedValues } = options !== null && options !== void 0 ? options : {};
+        const decision = entitlementDecisionService_1.EntitlementDecisionService.decideEntitlementPolicy({
+            entitlementType: query.type,
+            accessDeniedReason,
+            entitlement,
+            requestedUsage,
+            requestedValues,
+        });
+        const isCredit = query.type === cache_core_1.EntitlementType.Credit;
+        const requestedKind = isCredit ? undefined : (0, entitlementOptions_1.featureKindFromOptions)(options);
+        if (!entitlement) {
+            const fallback = this.fallbacks.resolve(query, options === null || options === void 0 ? void 0 : options.fallback);
+            const hasAccess = (_a = fallback === null || fallback === void 0 ? void 0 : fallback.hasAccess) !== null && _a !== void 0 ? _a : decision.hasAccess;
+            return {
+                hasAccess,
+                // A granted answer carries no denial reason, which is what this path has always returned.
+                accessDeniedReason: hasAccess ? undefined : decision.accessDeniedReason,
+                query,
+                resolved: (0, resolveEntitlement_1.resolveCacheMiss)(query, fallback),
+                isFallback: true,
+                requestedKind,
+                requestedUsage,
+                requestedValues,
+            };
+        }
+        return Object.assign(Object.assign({}, decision), { query, resolved: (0, resolveEntitlement_1.resolveEntitlement)(entitlement), entitlement, isFallback: false, requestedKind,
+            requestedUsage,
+            requestedValues });
+    }
+    evaluateFeature(query, entitlement, accessDeniedReason, requestedKind, options) {
+        var _a;
+        const { requestedUsage, requestedValues } = options !== null && options !== void 0 ? options : {};
+        const decision = entitlementDecisionService_1.EntitlementDecisionService.decideEntitlementPolicy({
+            entitlementType: cache_core_1.EntitlementType.Feature,
+            accessDeniedReason,
+            entitlement,
+            requestedUsage,
+            requestedValues,
+        });
+        // The caller asked for a kind this entitlement isn't, so their fallback is the answer. A plain
+        // miss is a real answer ("not in the subscription") and deliberately ignores the fallback, which
+        // is why the fallback is only resolved here.
+        if (entitlement && !MATCHES_KIND[requestedKind](entitlement.calculatedEntitlement.feature)) {
+            const fallback = this.fallbacks.resolve(query, options === null || options === void 0 ? void 0 : options.fallback);
+            const hasAccess = (_a = fallback === null || fallback === void 0 ? void 0 : fallback.hasAccess) !== null && _a !== void 0 ? _a : false;
+            return {
+                hasAccess,
+                // The mismatch is the reason access was denied, so a fallback that grants it drops the
+                // reason — the same rule the credit and untyped paths apply.
+                accessDeniedReason: hasAccess ? undefined : cache_core_1.AccessDeniedReason.FeatureTypeMismatch,
+                query,
+                resolved: (0, resolveEntitlement_1.resolveFeature)(null, fallback),
+                isFallback: true,
+                requestedKind,
+                requestedUsage,
+                requestedValues,
+            };
+        }
+        return Object.assign(Object.assign({}, decision), { query, resolved: (0, resolveEntitlement_1.resolveFeature)(entitlement), entitlement: entitlement !== null && entitlement !== void 0 ? entitlement : undefined, isFallback: false, requestedKind,
+            requestedUsage,
+            requestedValues });
+    }
+}
+exports.EntitlementEvaluator = EntitlementEvaluator;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW50aXRsZW1lbnRFdmFsdWF0b3IuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc2VydmljZXMvZW50aXRsZW1lbnRFdmFsdWF0b3IudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEsa0RBVTJCO0FBQzNCLDZFQUFvRjtBQUVwRixvRUFTcUM7QUFRckMsNkRBQTJHO0FBRTNHLE1BQU0sWUFBWSxHQUFxRDtJQUNyRSxPQUFPLEVBQUUsc0JBQVM7SUFDbEIsT0FBTyxFQUFFLHNCQUFTO0lBQ2xCLE9BQU8sRUFBRSxzQkFBUztJQUNsQixJQUFJLEVBQUUsbUJBQU07Q0FDYixDQUFDO0FBRUYsTUFBYSxvQkFBb0I7SUFDL0IsWUFBcUIsU0FBK0I7UUFBL0IsY0FBUyxHQUFULFNBQVMsQ0FBc0I7SUFBRyxDQUFDO0lBRXhELGVBQWUsQ0FDYixLQUFtQixFQUNuQixXQUErQixFQUMvQixrQkFBNkMsRUFDN0MsT0FBbUM7UUFFbkMsT0FBTyxJQUFJLENBQUMsZUFBZSxDQUFDLEtBQUssRUFBRSxXQUFXLEVBQUUsa0JBQWtCLEVBQUUsU0FBUyxFQUFFLE9BQU8sQ0FBQyxDQUFDO0lBQzFGLENBQUM7SUFFRCxlQUFlLENBQ2IsS0FBbUIsRUFDbkIsV0FBK0IsRUFDL0Isa0JBQTZDLEVBQzdDLE9BQW1DO1FBRW5DLE9BQU8sSUFBSSxDQUFDLGVBQWUsQ0FBQyxLQUFLLEVBQUUsV0FBVyxFQUFFLGtCQUFrQixFQUFFLFNBQVMsRUFBRSxPQUFPLENBQUMsQ0FBQztJQUMxRixDQUFDO0lBRUQsZUFBZSxDQUNiLEtBQW1CLEVBQ25CLFdBQStCLEVBQy9CLGtCQUE2QyxFQUM3QyxPQUFtQztRQUVuQyxPQUFPLElBQUksQ0FBQyxlQUFlLENBQUMsS0FBSyxFQUFFLFdBQVcsRUFBRSxrQkFBa0IsRUFBRSxTQUFTLEVBQUUsT0FBTyxDQUFDLENBQUM7SUFDMUYsQ0FBQztJQUVELFlBQVksQ0FDVixLQUFtQixFQUNuQixXQUErQixFQUMvQixr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

package/dist/services/entitlementFallbacks.d.ts

@@ -0,0 +1,48 @@
+import { EntitlementQuery, EntitlementType } from '@stigg/cache-core';
+import { EntitlementFallback, EntitlementFallbackConfig } from '../types/entitlementFallback';
+import { BooleanEntitlementOptions, CreditEntitlementOptions, EntitlementReadOptions, EnumEntitlementOptions, MeteredEntitlementOptions, NumericEntitlementOptions } from '../types/entitlementOptions';
+import { EntitlementEvaluation } from '../types/entitlementEvaluation';
+/**
+ * Owns what a caller falls back to when an entitlement cannot be answered from cached state: the
+ * configured defaults, the precedence between those and a per-call fallback, and the shape of the
+ * answer itself. Holds no cache or transport, so a host can build one before — or without — the
+ * service that reads entitlements.
+ */
+export declare class EntitlementFallbacks {
+    private readonly config;
+    constructor(config?: EntitlementFallbackConfig);
+    /**
+     * The answer when cached state was never reached at all — the host is offline, or the read failed.
+     * Distinct from a miss, which *is* a real answer ("not in the subscription") and therefore ignores
+     * the fallback. The caller picks how to present it, as only it knows which kind it is serving.
+     */
+    forBoolean(featureId: string, options?: BooleanEntitlementOptions): EntitlementEvaluation<EntitlementType.Feature>;
+    forNumeric(featureId: string, options?: NumericEntitlementOptions): EntitlementEvaluation<EntitlementType.Feature>;
+    forMetered(featureId: string, options?: MeteredEntitlementOptions): EntitlementEvaluation<EntitlementType.Feature>;
+    forEnum(featureId: string, options?: EnumEntitlementOptions): EntitlementEvaluation<EntitlementType.Feature>;
+    forCredit(currencyId: string, options?: CreditEntitlementOptions): EntitlementEvaluation<EntitlementType.Credit>;
+    /**
+     * The untyped equivalent of the five above, for reads that state no kind up front
+     * (`getEntitlement`, `getEntitlementV2`) and must infer it from the caller's options.
+     *
+     * Unlike the typed reads, this family drops the denial reason once the fallback grants access —
+     * a granted answer with a reason attached is what it has never returned.
+     */
+    forQuery<TType extends EntitlementType>(query: EntitlementQuery<TType>, options?: EntitlementReadOptions): EntitlementEvaluation<TType>;
+    /**
+     * Every configured fallback, as the answers a bulk read gives when it cannot be served. Goes
+     * through the same path as a single read, so one configured entry produces the same shape whether
+     * the caller asks for it alone or asks for everything.
+     */
+    forAllConfigured(): EntitlementEvaluation[];
+    /**
+     * A per-call fallback replaces the configured one wholesale. The configured maps are keyed by id
+     * and cannot know which kind the caller asked for, so an entry is taken on trust — the same
+     * looseness every caller had when it did this lookup itself.
+     */
+    resolve<TFallback extends EntitlementFallback>(query: EntitlementQuery, fallback?: Partial<TFallback>): Partial<TFallback> | undefined;
+    /** A granted answer carries no denial reason, which `unavailable` cannot know when it sets one. */
+    private clearDeniedReasonOnGrant;
+    private unavailable;
+    private feature;
+}

package/dist/services/entitlementFallbacks.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntitlementFallbacks = void 0;
+const cache_core_1 = require("@stigg/cache-core");
+const entitlementOptions_1 = require("../types/entitlementOptions");
+const resolveEntitlement_1 = require("./resolveEntitlement");
+/**
+ * Owns what a caller falls back to when an entitlement cannot be answered from cached state: the
+ * configured defaults, the precedence between those and a per-call fallback, and the shape of the
+ * answer itself. Holds no cache or transport, so a host can build one before — or without — the
+ * service that reads entitlements.
+ */
+class EntitlementFallbacks {
+    constructor(config = {}) {
+        this.config = config;
+    }
+    /**
+     * The answer when cached state was never reached at all — the host is offline, or the read failed.
+     * Distinct from a miss, which *is* a real answer ("not in the subscription") and therefore ignores
+     * the fallback. The caller picks how to present it, as only it knows which kind it is serving.
+     */
+    forBoolean(featureId, options) {
+        return this.unavailable(this.feature(featureId), options === null || options === void 0 ? void 0 : options.fallback, { requestedKind: 'BOOLEAN' });
+    }
+    forNumeric(featureId, options) {
+        return this.unavailable(this.feature(featureId), options === null || options === void 0 ? void 0 : options.fallback, { requestedKind: 'NUMERIC' });
+    }
+    forMetered(featureId, options) {
+        return this.unavailable(this.feature(featureId), options === null || options === void 0 ? void 0 : options.fallback, {
+            requestedKind: 'METERED',
+            requestedUsage: options === null || options === void 0 ? void 0 : options.requestedUsage,
+        });
+    }
+    forEnum(featureId, options) {
+        return this.unavailable(this.feature(featureId), options === null || options === void 0 ? void 0 : options.fallback, {
+            requestedKind: 'ENUM',
+            requestedValues: options === null || options === void 0 ? void 0 : options.requestedValues,
+        });
+    }
+    forCredit(currencyId, options) {
+        return this.unavailable({ type: cache_core_1.EntitlementType.Credit, id: currencyId }, options === null || options === void 0 ? void 0 : options.fallback);
+    }
+    /**
+     * The untyped equivalent of the five above, for reads that state no kind up front
+     * (`getEntitlement`, `getEntitlementV2`) and must infer it from the caller's options.
+     *
+     * Unlike the typed reads, this family drops the denial reason once the fallback grants access —
+     * a granted answer with a reason attached is what it has never returned.
+     */
+    forQuery(query, options) {
+        const evaluation = query.type === cache_core_1.EntitlementType.Credit
+            ? this.unavailable(query, options === null || options === void 0 ? void 0 : options.fallback)
+            : this.unavailable(query, options === null || options === void 0 ? void 0 : options.fallback, {
+                requestedKind: (0, entitlementOptions_1.featureKindFromOptions)(options),
+                requestedUsage: options === null || options === void 0 ? void 0 : options.requestedUsage,
+                requestedValues: options === null || options === void 0 ? void 0 : options.requestedValues,
+            });
+        return this.clearDeniedReasonOnGrant(evaluation);
+    }
+    /**
+     * Every configured fallback, as the answers a bulk read gives when it cannot be served. Goes
+     * through the same path as a single read, so one configured entry produces the same shape whether
+     * the caller asks for it alone or asks for everything.
+     */
+    forAllConfigured() {
+        var _a, _b;
+        const features = Object.entries((_a = this.config.entitlementsFallback) !== null && _a !== void 0 ? _a : {}).map(([featureId, fallback]) => this.clearDeniedReasonOnGrant(this.unavailable(this.feature(featureId), fallback, { requestedKind: (0, entitlementOptions_1.featureKindFromFallback)(fallback) })));
+        const credits = Object.keys((_b = this.config.creditEntitlementsFallback) !== null && _b !== void 0 ? _b : {}).map((currencyId) => this.clearDeniedReasonOnGrant(this.forCredit(currencyId)));
+        return [...features, ...credits];
+    }
+    /**
+     * A per-call fallback replaces the configured one wholesale. The configured maps are keyed by id
+     * and cannot know which kind the caller asked for, so an entry is taken on trust — the same
+     * looseness every caller had when it did this lookup itself.
+     */
+    resolve(query, fallback) {
+        var _a, _b;
+        if (fallback) {
+            return fallback;
+        }
+        const configured = query.type === cache_core_1.EntitlementType.Credit
+            ? (_a = this.config.creditEntitlementsFallback) === null || _a === void 0 ? void 0 : _a[query.id]
+            : (_b = this.config.entitlementsFallback) === null || _b === void 0 ? void 0 : _b[query.id];
+        return configured;
+    }
+    /** A granted answer carries no denial reason, which `unavailable` cannot know when it sets one. */
+    clearDeniedReasonOnGrant(evaluation) {
+        return evaluation.hasAccess ? Object.assign(Object.assign({}, evaluation), { accessDeniedReason: undefined }) : evaluation;
+    }
+    unavailable(query, fallback, requested = {}) {
+        var _a;
+        const resolved = this.resolve(query, fallback);
+        return Object.assign({ hasAccess: (_a = resolved === null || resolved === void 0 ? void 0 : resolved.hasAccess) !== null && _a !== void 0 ? _a : false, accessDeniedReason: cache_core_1.AccessDeniedReason.Unknown, query, resolved: (0, resolveEntitlement_1.resolveCacheMiss)(query, resolved), isFallback: true }, requested);
+    }
+    feature(featureId) {
+        return { type: cache_core_1.EntitlementType.Feature, id: featureId };
+    }
+}
+exports.EntitlementFallbacks = EntitlementFallbacks;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW50aXRsZW1lbnRGYWxsYmFja3MuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvc2VydmljZXMvZW50aXRsZW1lbnRGYWxsYmFja3MudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQUEsa0RBQTBGO0FBRTFGLG9FQVNxQztBQUVyQyw2REFBd0Q7QUFFeEQ7Ozs7O0dBS0c7QUFDSCxNQUFhLG9CQUFvQjtJQUMvQixZQUE2QixTQUFvQyxFQUFFO1FBQXRDLFdBQU0sR0FBTixNQUFNLENBQWdDO0lBQUcsQ0FBQztJQUV2RTs7OztPQUlHO0lBQ0gsVUFBVSxDQUFDLFNBQWlCLEVBQUUsT0FBbUM7UUFDL0QsT0FBTyxJQUFJLENBQUMsV0FBVyxDQUFDLElBQUksQ0FBQyxPQUFPLENBQUMsU0FBUyxDQUFDLEVBQUUsT0FBTyxhQUFQLE9BQU8sdUJBQVAsT0FBTyxDQUFFLFFBQVEsRUFBRSxFQUFFLGFBQWEsRUFBRSxTQUFTLEVBQUUsQ0FBQyxDQUFDO0lBQ3BHLENBQUM7SUFFRCxVQUFVLENBQUMsU0FBaUIsRUFBRSxPQUFtQztRQUMvRCxPQUFPLElBQUksQ0FBQyxXQUFXLENBQUMsSUFBSSxDQUFDLE9BQU8sQ0FBQyxTQUFTLENBQUMsRUFBRSxPQUFPLGFBQVAsT0FBTyx1QkFBUCxPQUFPLENBQUUsUUFBUSxFQUFFLEVBQUUsYUFBYSxFQUFFLFNBQVMsRUFBRSxDQUFDLENBQUM7SUFDcEcsQ0FBQztJQUVELFVBQVUsQ0FBQyxTQUFpQixFQUFFLE9BQW1DO1FBQy9ELE9BQU8sSUFBSSxDQUFDLFdBQVcsQ0FBQyxJQUFJLENBQUMsT0FBTyxDQUFDLFNBQVMsQ0FBQyxFQUFFLE9BQU8sYUFBUCxPQUFPLHVCQUFQLE9BQU8sQ0FBRSxRQUFRLEVBQUU7WUFDbEUsYUFBYSxFQUFFLFNBQVM7WUFDeEIsY0FBYyxFQUFFLE9BQU8sYUFBUCxPQUFPLHVCQUFQLE9BQU8sQ0FBRSxjQUFjO1NBQ3hDLENBQUMsQ0FBQztJQUNMLENBQUM7SUFF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

package/dist/services/resolveEntitlement.d.ts

@@ -0,0 +1,18 @@
+import { CachedEntitlement, EntitlementQuery, EntitlementType } from '@stigg/cache-core';
+import { CreditEntitlementFallback, EntitlementFallback, FeatureEntitlementFallback } from '../types/entitlementFallback';
+import { FeatureEntitlement, ResolvedByType, ResolvedCreditEntitlement, ResolvedFeatureEntitlement } from '../types/entitlementEvaluation';
+export declare function resolveFeature(entitlement: FeatureEntitlement, fallback?: FeatureEntitlementFallback): ResolvedFeatureEntitlement;
+export declare function resolveCredit(currencyId: string, entitlement: CachedEntitlement<EntitlementType.Credit> | null, fallback?: Partial<CreditEntitlementFallback>): ResolvedCreditEntitlement;
+/**
+ * Answers from a cached entitlement, which carries both its own kind and its own currency — so the
+ * query that found it adds nothing here.
+ *
+ * Declared as an overload because the return type is conditional on `TType`, and a type guard
+ * narrows the value rather than the type parameter.
+ */
+export declare function resolveEntitlement<TType extends EntitlementType>(entitlement: CachedEntitlement<TType>): ResolvedByType<TType>;
+/**
+ * Answers a cache miss, where the query is the only thing left that names the kind — and, for
+ * credit, the currency the caller asked about.
+ */
+export declare function resolveCacheMiss<TType extends EntitlementType>(query: EntitlementQuery<TType>, fallback?: Partial<EntitlementFallback>): ResolvedByType<TType>;

package/dist/services/resolveEntitlement.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFeature = resolveFeature;
+exports.resolveCredit = resolveCredit;
+exports.resolveEntitlement = resolveEntitlement;
+exports.resolveCacheMiss = resolveCacheMiss;
+const cache_core_1 = require("@stigg/cache-core");
+function resolveFeature(entitlement, fallback) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    if (!entitlement) {
+        return {
+            usageLimit: (_a = fallback === null || fallback === void 0 ? void 0 : fallback.value) !== null && _a !== void 0 ? _a : fallback === null || fallback === void 0 ? void 0 : fallback.usageLimit,
+            enumValues: (_b = fallback === null || fallback === void 0 ? void 0 : fallback.enumValues) !== null && _b !== void 0 ? _b : [],
+            isUnlimited: (_c = fallback === null || fallback === void 0 ? void 0 : fallback.isUnlimited) !== null && _c !== void 0 ? _c : false,
+            hasSoftLimit: false,
+            currentUsage: 0,
+        };
+    }
+    const { calculatedEntitlement: calculated, usageData } = entitlement;
+    return {
+        feature: calculated.feature,
+        usageLimit: (_d = calculated.usageLimit) !== null && _d !== void 0 ? _d : undefined,
+        enumValues: (_e = calculated.enumValues) !== null && _e !== void 0 ? _e : [],
+        isUnlimited: calculated.hasUnlimitedUsage,
+        hasSoftLimit: !!calculated.hasSoftLimit,
+        currentUsage: usageData.currentUsage,
+        resetPeriod: (_f = calculated.resetPeriod) !== null && _f !== void 0 ? _f : undefined,
+        usagePeriodAnchor: (_g = calculated.usagePeriodAnchor) !== null && _g !== void 0 ? _g : undefined,
+        usagePeriodStart: (_h = usageData.usagePeriodStart) !== null && _h !== void 0 ? _h : undefined,
+        usagePeriodEnd: (_j = usageData.usagePeriodEnd) !== null && _j !== void 0 ? _j : undefined,
+    };
+}
+function resolveCredit(currencyId, entitlement, fallback) {
+    var _a, _b, _c, _d;
+    const usageLimit = (_a = (entitlement ? entitlement.calculatedEntitlement.usageLimit : fallback === null || fallback === void 0 ? void 0 : fallback.usageLimit)) !== null && _a !== void 0 ? _a : 0;
+    const currentUsage = (_b = (entitlement ? entitlement.usageData.currentUsage : fallback === null || fallback === void 0 ? void 0 : fallback.currentUsage)) !== null && _b !== void 0 ? _b : 0;
+    return {
+        currency: entitlement ? entitlement.calculatedEntitlement.currency : { currencyId },
+        usageLimit,
+        currentUsage,
+        remaining: Math.max(usageLimit - currentUsage, 0),
+        hasSoftLimit: entitlement ? ((_c = entitlement.calculatedEntitlement.hasSoftLimit) !== null && _c !== void 0 ? _c : false) : false,
+        usagePeriodEnd: (_d = (entitlement ? entitlement.usageData.usagePeriodEnd : undefined)) !== null && _d !== void 0 ? _d : undefined,
+    };
+}
+function resolveEntitlement(entitlement) {
+    if ((0, cache_core_1.isCreditEntitlement)(entitlement)) {
+        return resolveCredit(entitlement.calculatedEntitlement.currency.currencyId, entitlement);
+    }
+    if ((0, cache_core_1.isFeatureEntitlement)(entitlement)) {
+        return resolveFeature(entitlement);
+    }
+    // Unreachable while the two kinds are the only ones, but a guard cannot prove that: negating one
+    // leaves `CachedEntitlement<T>` unnarrowed, since it is a generic class rather than a union.
+    throw new Error(`Unknown entitlement type: ${entitlement.calculatedEntitlement.type}`);
+}
+function resolveCacheMiss(query, fallback) {
+    return query.type === cache_core_1.EntitlementType.Credit
+        ? resolveCredit(query.id, null, fallback)
+        : resolveFeature(null, fallback);
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVzb2x2ZUVudGl0bGVtZW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3NlcnZpY2VzL3Jlc29sdmVFbnRpdGxlbWVudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQW1CQSx3Q0EyQkM7QUFFRCxzQ0FlQztBQVlELGdEQVlDO0FBVUQsNENBT0M7QUF4R0Qsa0RBTTJCO0FBYTNCLFNBQWdCLGNBQWMsQ0FDNUIsV0FBK0IsRUFDL0IsUUFBcUM7O0lBRXJDLElBQUksQ0FBQyxXQUFXLEVBQUUsQ0FBQztRQUNqQixPQUFPO1lBQ0wsVUFBVSxFQUFFLE1BQUEsUUFBUSxhQUFSLFFBQVEsdUJBQVIsUUFBUSxDQUFFLEtBQUssbUNBQUksUUFBUSxhQUFSLFFBQVEsdUJBQVIsUUFBUSxDQUFFLFVBQVU7WUFDbkQsVUFBVSxFQUFFLE1BQUEsUUFBUSxhQUFSLFFBQVEsdUJBQVIsUUFBUSxDQUFFLFVBQVUsbUNBQUksRUFBRTtZQUN0QyxXQUFXLEVBQUUsTUFBQSxRQUFRLGFBQVIsUUFBUSx1QkFBUixRQUFRLENBQUUsV0FBVyxtQ0FBSSxLQUFLO1lBQzNDLFlBQVksRUFBRSxLQUFLO1lBQ25CLFlBQVksRUFBRSxDQUFDO1NBQ2hCLENBQUM7SUFDSixDQUFDO0lBRUQsTUFBTSxFQUFFLHFCQUFxQixFQUFFLFVBQVUsRUFBRSxTQUFTLEVBQUUsR0FBRyxXQUFXLENBQUM7SUFDckUsT0FBTztRQUNMLE9BQU8sRUFBRSxVQUFVLENBQUMsT0FBTztRQUMzQixVQUFVLEVBQUUsTUFBQSxVQUFVLENBQUMsVUFBVSxtQ0FBSSxTQUFTO1FBQzlDLFVBQVUsRUFBRSxNQUFBLFVBQVUsQ0FBQyxVQUFVLG1DQUFJLEVBQUU7UUFDdkMsV0FBVyxFQUFFLFVBQVUsQ0FBQyxpQkFBaUI7UUFDekMsWUFBWSxFQUFFLENBQUMsQ0FBQyxVQUFVLENBQUMsWUFBWTtRQUN2QyxZQUFZLEVBQUUsU0FBUyxDQUFDLFlBQVk7UUFDcEMsV0FBVyxFQUFFLE1B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

package/dist/types/entitlementEvaluation.d.ts

@@ -0,0 +1,61 @@
+import { AccessDeniedReason, CachedEntitlement, CalculatedCreditEntitlement, EntitlementFeature, EntitlementQuery, EntitlementResetPeriod, EntitlementType } from '@stigg/cache-core';
+/**
+ * The answer's values, already merged from whichever source won — the cached entitlement, or the
+ * caller's fallback. Deliberately *not* a `CachedEntitlement`: that type means "real, fully-mapped
+ * cache state" and requires a `feature` with a `featureType`, which is precisely what a miss does not
+ * know. Resolving here is what lets every transport translate without a branch.
+ */
+export interface ResolvedFeatureEntitlement {
+    /** Absent when nothing was found — there is no feature to describe. */
+    readonly feature?: EntitlementFeature;
+    readonly usageLimit?: number;
+    readonly enumValues: string[];
+    readonly isUnlimited: boolean;
+    readonly hasSoftLimit: boolean;
+    readonly currentUsage: number;
+    readonly resetPeriod?: EntitlementResetPeriod;
+    readonly usagePeriodAnchor?: number;
+    readonly usagePeriodStart?: number;
+    readonly usagePeriodEnd?: number;
+}
+export interface ResolvedCreditEntitlement {
+    readonly currency: CalculatedCreditEntitlement['currency'];
+    readonly usageLimit: number;
+    readonly currentUsage: number;
+    readonly remaining: number;
+    readonly hasSoftLimit: boolean;
+    readonly usagePeriodEnd?: number;
+}
+export type ResolvedByType<TType extends EntitlementType> = TType extends EntitlementType.Feature ? ResolvedFeatureEntitlement : TType extends EntitlementType.Credit ? ResolvedCreditEntitlement : ResolvedFeatureEntitlement | ResolvedCreditEntitlement;
+/**
+ * The outcome of evaluating cached state for one entitlement, in cache vocabulary.
+ *
+ * This is the shared seam: the access logic runs once in `EntitlementEvaluator`, and each transport
+ * translates the result into its own representation — `ModelMapper` into the SDK models today, the
+ * REST DTOs later. Keeping it free of API types is what lets both live over the same evaluation.
+ */
+export interface EntitlementEvaluation<TType extends EntitlementType = EntitlementType> {
+    readonly hasAccess: boolean;
+    readonly accessDeniedReason?: AccessDeniedReason;
+    /** What was asked for. */
+    readonly query: EntitlementQuery<TType>;
+    /** The answer's values, whichever source they came from. */
+    readonly resolved: ResolvedByType<TType>;
+    /** The cached entitlement the decision was made from; absent on a miss or a kind mismatch. */
+    readonly entitlement?: CachedEntitlement<TType>;
+    /** Whether the answer is the caller's fallback rather than resolved state. */
+    readonly isFallback: boolean;
+    /**
+     * The kind the caller asked for. Authoritative only when there is no `resolved.feature` to read a
+     * kind from — a miss or an unavailable read knows nothing about the feature, yet still has to be
+     * rendered as one specific kind. On a hit the feature's own type wins.
+     */
+    readonly requestedKind?: FeatureEntitlementKind;
+    readonly requestedUsage?: number;
+    readonly requestedValues?: string[];
+}
+/** The four shapes a feature entitlement can be answered as. */
+export type FeatureEntitlementKind = 'BOOLEAN' | 'NUMERIC' | 'METERED' | 'ENUM';
+export type FeatureQuery = EntitlementQuery<EntitlementType.Feature>;
+export type FeatureEntitlement = CachedEntitlement<EntitlementType.Feature> | null;
+export type FeaturePredicate = (feature?: EntitlementFeature) => boolean;

package/dist/types/entitlementEvaluation.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW50aXRsZW1lbnRFdmFsdWF0aW9uLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3R5cGVzL2VudGl0bGVtZW50RXZhbHVhdGlvbi50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist/types/entitlementFallback.d.ts

@@ -0,0 +1,52 @@
+/**
+ * What a caller wants returned when an entitlement can't be resolved.
+ *
+ * Kept out of `models.ts` deliberately: these carry no transport vocabulary, only primitives, so the
+ * evaluator can accept one without reaching for the GraphQL-flavoured models and every transport can
+ * expand it into its own representation.
+ */
+export type BooleanEntitlementFallback = {
+    hasAccess: boolean;
+};
+export type NumericEntitlementFallback = {
+    hasAccess: boolean;
+    value?: number;
+    isUnlimited?: boolean;
+};
+export type MeteredEntitlementFallback = {
+    hasAccess: boolean;
+    usageLimit?: number;
+    isUnlimited?: boolean;
+};
+export type EnumEntitlementFallback = {
+    hasAccess: boolean;
+    enumValues?: string[];
+};
+export type CreditEntitlementFallback = {
+    hasAccess: boolean;
+    usageLimit?: number;
+    currentUsage?: number;
+};
+export type EntitlementFallback = BooleanEntitlementFallback | NumericEntitlementFallback | MeteredEntitlementFallback | EnumEntitlementFallback | CreditEntitlementFallback;
+/**
+ * Any feature fallback, read structurally rather than per kind. The resolved answer carries a single
+ * limit, so a caller naming it `value` (numeric) and one naming it `usageLimit` (metered) both land
+ * on it — and reading with `??` rather than `in` keeps a present-but-undefined key from shadowing
+ * the other.
+ */
+export type FeatureEntitlementFallback = Partial<NumericEntitlementFallback & MeteredEntitlementFallback & EnumEntitlementFallback>;
+/** Feature fallbacks keyed by feature id. Credit is keyed separately, by currency id. */
+export type EntitlementsFallback = {
+    [featureId: string]: BooleanEntitlementFallback | NumericEntitlementFallback | MeteredEntitlementFallback | EnumEntitlementFallback;
+};
+export type CreditEntitlementsFallback = {
+    [currencyId: string]: CreditEntitlementFallback;
+};
+/**
+ * Fallbacks the host was configured with once, rather than passed per call. A fallback passed on the
+ * call itself replaces the configured one wholesale — the two are never merged.
+ */
+export type EntitlementFallbackConfig = {
+    entitlementsFallback?: EntitlementsFallback;
+    creditEntitlementsFallback?: CreditEntitlementsFallback;
+};

package/dist/types/entitlementFallback.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * What a caller wants returned when an entitlement can't be resolved.
+ *
+ * Kept out of `models.ts` deliberately: these carry no transport vocabulary, only primitives, so the
+ * evaluator can accept one without reaching for the GraphQL-flavoured models and every transport can
+ * expand it into its own representation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW50aXRsZW1lbnRGYWxsYmFjay5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90eXBlcy9lbnRpdGxlbWVudEZhbGxiYWNrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7QUFBQTs7Ozs7O0dBTUcifQ==

package/dist/types/entitlementOptions.d.ts

@@ -0,0 +1,39 @@
+import { BooleanEntitlementFallback, CreditEntitlementFallback, EnumEntitlementFallback, MeteredEntitlementFallback, FeatureEntitlementFallback, NumericEntitlementFallback } from './entitlementFallback';
+import { FeatureEntitlementKind } from './entitlementEvaluation';
+/**
+ * Per-call options for a read, in cache vocabulary. `sdk-core` widens these with the SDKs'
+ * backward-compatible fields before publishing them under the same names.
+ */
+export type BooleanEntitlementOptions = {
+    fallback?: BooleanEntitlementFallback;
+};
+export type NumericEntitlementOptions = {
+    fallback?: NumericEntitlementFallback;
+};
+export type MeteredEntitlementOptions = {
+    fallback?: MeteredEntitlementFallback;
+    requestedUsage?: number;
+};
+export type EnumEntitlementOptions = {
+    fallback?: EnumEntitlementFallback;
+    requestedValues?: string[];
+};
+export type CreditEntitlementOptions = {
+    fallback?: CreditEntitlementFallback;
+};
+/** Whatever any of the four feature reads may pass, for the paths they share. */
+export type FeatureEntitlementOptions = BooleanEntitlementOptions & NumericEntitlementOptions & MeteredEntitlementOptions & EnumEntitlementOptions;
+export type EntitlementReadOptions = FeatureEntitlementOptions & CreditEntitlementOptions;
+/**
+ * Which kind an untyped read (`getEntitlement`, `getEntitlementV2`) is asking for. There is no
+ * feature to consult when the read cannot be answered, so the caller's own options are the only
+ * evidence — the same discrimination the SDKs applied before, kept in one place so every transport
+ * answers the same way.
+ */
+export declare function featureKindFromOptions(options?: FeatureEntitlementOptions): FeatureEntitlementKind;
+/**
+ * Which kind a *configured* fallback describes. A different question from the one above: there is no
+ * caller stating what they want, only an entry someone wrote in the config, so its own fields are
+ * the evidence. Used where entries are answered without anyone having asked for one by kind.
+ */
+export declare function featureKindFromFallback(fallback?: FeatureEntitlementFallback): FeatureEntitlementKind;

package/dist/types/entitlementOptions.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.featureKindFromOptions = featureKindFromOptions;
+exports.featureKindFromFallback = featureKindFromFallback;
+/**
+ * Which kind an untyped read (`getEntitlement`, `getEntitlementV2`) is asking for. There is no
+ * feature to consult when the read cannot be answered, so the caller's own options are the only
+ * evidence — the same discrimination the SDKs applied before, kept in one place so every transport
+ * answers the same way.
+ */
+function featureKindFromOptions(options) {
+    if (options == null) {
+        return 'BOOLEAN';
+    }
+    if ('requestedUsage' in options) {
+        return 'METERED';
+    }
+    if ('requestedValues' in options) {
+        return 'ENUM';
+    }
+    return options.fallback != null && 'value' in options.fallback ? 'NUMERIC' : 'BOOLEAN';
+}
+/**
+ * Which kind a *configured* fallback describes. A different question from the one above: there is no
+ * caller stating what they want, only an entry someone wrote in the config, so its own fields are
+ * the evidence. Used where entries are answered without anyone having asked for one by kind.
+ */
+function featureKindFromFallback(fallback) {
+    if (fallback == null) {
+        return 'BOOLEAN';
+    }
+    if ('enumValues' in fallback) {
+        return 'ENUM';
+    }
+    if ('usageLimit' in fallback) {
+        return 'METERED';
+    }
+    return 'value' in fallback ? 'NUMERIC' : 'BOOLEAN';
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZW50aXRsZW1lbnRPcHRpb25zLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3R5cGVzL2VudGl0bGVtZW50T3B0aW9ucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQWtEQSx3REFXQztBQU9ELDBEQVdDO0FBbkNEOzs7OztHQUtHO0FBQ0gsU0FBZ0Isc0JBQXNCLENBQUMsT0FBbUM7SUFDeEUsSUFBSSxPQUFPLElBQUksSUFBSSxFQUFFLENBQUM7UUFDcEIsT0FBTyxTQUFTLENBQUM7SUFDbkIsQ0FBQztJQUNELElBQUksZ0JBQWdCLElBQUksT0FBTyxFQUFFLENBQUM7UUFDaEMsT0FBTyxTQUFTLENBQUM7SUFDbkIsQ0FBQztJQUNELElBQUksaUJBQWlCLElBQUksT0FBTyxFQUFFLENBQUM7UUFDakMsT0FBTyxNQUFNLENBQUM7SUFDaEIsQ0FBQztJQUNELE9BQU8sT0FBTyxDQUFDLFFBQVEsSUFBSSxJQUFJLElBQUksT0FBTyxJQUFJLE9BQU8sQ0FBQyxRQUFRLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDO0FBQ3pGLENBQUM7QUFFRDs7OztHQUlHO0FBQ0gsU0FBZ0IsdUJBQXVCLENBQUMsUUFBcUM7SUFDM0UsSUFBSSxRQUFRLElBQUksSUFBSSxFQUFFLENBQUM7UUFDckIsT0FBTyxTQUFTLENBQUM7SUFDbkIsQ0FBQztJQUNELElBQUksWUFBWSxJQUFJLFFBQVEsRUFBRSxDQUFDO1FBQzdCLE9BQU8sTUFBTSxDQUFDO0lBQ2hCLENBQUM7SUFDRCxJQUFJLFlBQVksSUFBSSxRQUFRLEVBQUUsQ0FBQztRQUM3QixPQUFPLFNBQVMsQ0FBQztJQUNuQixDQUFDO0lBQ0QsT0FBTyxPQUFPLElBQUksUUFBUSxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLFNBQVMsQ0FBQztBQUNyRCxDQUFDIn0=

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@stigg/entitlements-runtime",
+  "version": "2.0.0",
+  "description": "Transport-agnostic entitlement decision logic for Stigg SDKs",
+  "main": "dist/index.js",
+  "typings": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.js",
+    "typings": "dist/index.d.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stiggio/stigg-sdk.git",
+    "directory": "packages/entitlements-runtime"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "yarn run -T tsc -p tsconfig.build.json",
+    "lint": "yarn run -T eslint \"src/**/*.ts\"",
+    "test": "yarn run -T jest --forceExit"
+  },
+  "files": [
+    "dist/**/*"
+  ],
+  "dependencies": {
+    "lodash": "^4.18.1"
+  },
+  "peerDependencies": {
+    "@stigg/cache-core": "1.27.0"
+  }
+}