@revturbine/sdk 0.11.19 → 0.11.21

package/dist/index.d.ts

@@ -27720,6 +27720,52 @@ type PlaybookOption = {
     exportedConfig: RevTurbineConfig;
 };
 
+/**
+ * Effective entitlements — the ONE answer every SDK runtime uses (D-61,
+ * Kent 2026-10-06).
+ *
+ * The shared evaluator (`deriveLocalEntitlementFromConfiguredRules`) decides
+ * each entitlement from the Playbook + user context. An app may then enrich
+ * that answer with its own data ("Entitlement Mirroring"): grants on
+ * `UserContext.entitlements` and/or an app-registered entitlement provider.
+ * The two are merged with a configurable precedence — provider level
+ * (`precedence`, default `'app'`) with optional per-field overrides.
+ *
+ * Browser and server SDKs run this same function on the same inputs: the
+ * browser result shapes interaction, the server result verifies it.
+ *
+ * An entitlement handle neither the Playbook nor the app knows is DENIED
+ * (`entitlement_not_in_playbook`) and flagged `unknownHandle`, so the runtime
+ * can warn and report it.
+ */
+
+/** Which side wins a merge: the app's own data, or the Playbook evaluation. */
+type EntitlementSource = 'app' | 'playbook';
+/** Fields that can be given their own precedence. `status` carries `allowed` and `reason` with it. */
+type EntitlementMergeField = 'status' | 'limit' | 'used' | 'remaining';
+interface EntitlementMergeOptions {
+    /** Provider-level precedence. Default `'app'`: app-supplied data wins. */
+    precedence?: EntitlementSource;
+    /** Per-field overrides of `precedence`. */
+    fields?: Partial<Record<EntitlementMergeField, EntitlementSource>>;
+}
+/** A mirrored grant on `UserContext.entitlements`: a boolean, or a grant-shaped record. */
+type MirroredEntitlement = boolean | {
+    status?: string;
+    allowed?: boolean;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    reason?: string;
+};
+/** The trial facts reverse-trial grants depend on (`UserTrialStatus` subset). */
+interface ReverseTrialView {
+    in_trial?: boolean;
+    trial_type?: string;
+    /** The user's BASE plan while on a reverse trial. */
+    plan_handle?: string;
+}
+
 /**
  * User context lifecycle — pure functions for building, merging,
  * and deriving targeting state from user context + RevTurbineConfig.
@@ -27742,7 +27788,12 @@ interface UserContextSnapshot {
      */
     plan?: string | UserPlanContext;
     custom?: Record<string, JsonValue>;
-    entitlements?: Record<string, boolean>;
+    /**
+     * App-supplied entitlement data keyed by handle — a boolean or a grant
+     * (D-61 Entitlement Mirroring). Merged with the Playbook evaluation by the
+     * effective-entitlement core; flattened into segment traits as a boolean.
+     */
+    entitlements?: Record<string, MirroredEntitlement>;
     usage?: Record<string, UserUsageEntry>;
     personalization?: Record<string, JsonValue>;
     /** Canonical experiment-handle to variant-handle assignments. */
@@ -28023,6 +28074,13 @@ interface EntitlementUsageEntry {
     reset_date?: string;
 }
 interface EntitlementProviderState {
+    /**
+     * D-61: `'playbook_default'` marks entries the static adapter fills with a
+     * blanket default policy. Those are NOT app data and never override the
+     * Playbook evaluation; entries from any other provider are app-mirrored
+     * data and merge with it per the runtime's precedence.
+     */
+    origin?: 'playbook_default';
     /**
      * All entitlement results keyed by entitlement handle.
      * Each entry carries status ('allowed' | 'limited' | 'denied') so the
@@ -28496,7 +28554,7 @@ interface DecisionEngineOptions {
     enableCapsEnforcement?: boolean;
     /** Enable category pipeline for local-mode priority ordering. Default: false. */
     enableCategoryPipelineLocalMode?: boolean;
-    /** Default entitlement policy when no provider or entry found. Default: 'allow'. */
+    /** Default entitlement policy when no provider or entry found. Default: 'deny' (fail closed, D-61). */
     defaultEntitlementPolicy?: 'allow' | 'deny';
 }
 interface EntitlementCheckResult {
@@ -29391,6 +29449,20 @@ interface LocalRuntimeOptionsBase {
     impressionStore?: ImpressionHistoryStore;
     /** Decision engine behavior flags. */
     engineOptions?: DecisionEngineOptions;
+    /**
+     * D-61 Entitlement Mirroring: the user context's own entitlement data
+     * (`UserContext.entitlements`), merged with the Playbook evaluation.
+     */
+    userEntitlements?: Record<string, MirroredEntitlement>;
+    /** D-61: the user's trial status, so reverse-trial grants evaluate exactly as in the browser. */
+    trialStatus?: ReverseTrialView;
+    /** D-61: how app-supplied entitlement data merges with the Playbook result. Default: app wins. */
+    entitlementMerge?: EntitlementMergeOptions;
+    /**
+     * Called once per entitlement handle that neither the Playbook nor the app
+     * knows (it is denied). The runtime also logs a warning. Wire telemetry here.
+     */
+    onUnknownEntitlement?: (handle: string) => void;
     /** Interaction tracker options. */
     interactionOptions?: Partial<Pick<InteractionTrackerOptions, 'defaultDismissCooldownMs' | 'defaultRemindLaterMs'>>;
 }
@@ -29411,6 +29483,11 @@ declare class LocalRuntime {
     readonly impressionHistory: ImpressionHistory;
     private readonly playbook;
     private readonly registeredPlacements;
+    private readonly userEntitlements;
+    private readonly trialStatus;
+    private readonly entitlementMerge;
+    private readonly onUnknownEntitlement;
+    private readonly reportedUnknownEntitlements;
     private userId;
     constructor(options: LocalRuntimeOptions);
     /**
@@ -29448,7 +29525,12 @@ declare class LocalRuntime {
      */
     getPlacement(config: RevTurbinePlacementRequestConfig$1): Promise<RevTurbinePlacementDecision | null>;
     /**
-     * Check entitlement access locally using RevTurbineConfig rules.
+     * Check entitlement access locally (D-61): the shared evaluator decides
+     * from the Playbook + user context, then app-mirrored data (user-context
+     * grants and any app entitlement provider) merges per the runtime's
+     * precedence (default: app wins). The browser SDK runs the same function on
+     * the same inputs, so the server verifies exactly what the browser showed.
+     * An entitlement nobody knows is denied, warned and reported.
      */
     checkEntitlement(handle: string, context?: RevTurbineEntitlementContext): Promise<EntitlementResult>;
     /**
@@ -29511,7 +29593,11 @@ declare class LocalRuntime {
      */
     private slotRecordForConfig;
     private buildPlacementResolver;
-    private deriveEntitlementFromConfig;
+    /** Evaluator inputs from the resolved providers — the same facts the browser SDK uses. */
+    private effectiveBase;
+    /** App-mirrored data per handle: user-context grants plus non-default provider entries. */
+    private appInputsByHandle;
+    private reportUnknownEntitlement;
 }
 
 /**
@@ -31009,8 +31095,14 @@ interface RevTurbineUserContext extends Omit<UserContextInput, 'custom' | 'entit
     context_hash?: UserContextInput['context_hash'];
     /** Customer-defined fields for segmentation and personalization. */
     custom?: SdkTraits;
-    /** Feature entitlements granted by plan + entitlement rules. */
-    entitlements?: Record<string, boolean>;
+    /**
+     * App-supplied entitlement data, keyed by handle — a boolean or a grant
+     * (`status`, `limit`, `used`). This is Entitlement Mirroring (D-61): it
+     * merges with the Playbook evaluation, and by default the app's data wins.
+     * Browser-supplied data shapes the UI only; the server re-check on the
+     * same inputs stays authoritative for paid actions.
+     */
+    entitlements?: UserContextInput['entitlements'];
     /** Usage entries derived from credits / usage_limit entitlements, keyed by handle. */
     usage?: UserContextInput['usage'];
     /**
@@ -31493,6 +31585,14 @@ interface RevTurbineInitOptions {
      * Playbook.
      */
     placementBehavior?: Partial<RevTurbinePlacementBehaviorFlags>;
+    /**
+     * How app-supplied entitlement data (`userContext.entitlements`, an app
+     * entitlement provider) merges with the Playbook evaluation (D-61).
+     * Provider-level `precedence` defaults to `'app'`; `fields` overrides it
+     * per field (`status`, `limit`, `used`, `remaining`). Use the same value
+     * on your server SDK so verification matches.
+     */
+    entitlementMerge?: EntitlementMergeOptions;
     extension?: {
         enabled?: boolean;
     };
@@ -31614,6 +31714,11 @@ interface RevTurbineEventBatchingOptions {
 }
 interface RevTurbineLocalRuntimeData {
     placementDecisionsByPlacementId?: Record<string, RevTurbinePlacementDecision>;
+    /**
+     * @deprecated Ignored since 0.11.21 (D-39 / BL-0379): `getPlacement` is a
+     * pure function of the user context and `localRuntime.playbook`, so
+     * pre-decided outputs are never consulted. Removed in 0.12.0.
+     */
     placementsByLookupKey?: Record<string, PlacementOutput | null>;
     entitlementByHandle?: Record<string, EntitlementResult>;
     userContextByUserId?: Record<string, UserTargetingContext>;
@@ -32267,6 +32372,16 @@ declare class RevTurbineCustomerSdk {
     private readonly policy;
     private readonly extensionEnabled;
     private readonly placementBehaviorOverrides;
+    private readonly entitlementMerge;
+    /** Entries from an app-registered entitlement provider (D-61 mirroring), from the last provider resolution. */
+    private appProviderEntitlements;
+    /** Plan from an app-registered plan provider (D-61) — wins over the user-context plan, as on the server. */
+    private appProviderPlanHandle;
+    /** Usage from an app entitlement provider (D-61), fed into the evaluation as on the server. */
+    private appProviderUsage;
+    /** Segment membership from an app segment provider (D-61), as a server runtime sees it. */
+    private appProviderSegments;
+    private readonly reportedUnknownEntitlements;
     private derivedPlacementBehaviorMemo;
     private readonly providerFailureSlotBehavior;
     private readonly uiPathResolvers;
@@ -32381,7 +32496,6 @@ declare class RevTurbineCustomerSdk {
     private pendingConversionPlan?;
     private usageBalances;
     private localDecisionsByPlacementId;
-    private localPlacementsByLookupKey;
     private localEntitlementsByHandle;
     private localUserContextsByUserId;
     /**
@@ -32682,12 +32796,6 @@ declare class RevTurbineCustomerSdk {
      */
     private hasEndpointOverride;
     private endpointFor;
-    private localPlacementLookupKey;
-    private localLookupMatchesConfig;
-    private localOutputMatchesConfig;
-    private applyCategoryConflictSuppression;
-    private resolveLocalPlacementFromCandidates;
-    private localPlacementForConfig;
     /**
      * The `placement_slots[]` entry the loaded Playbook authors for a request.
      *
@@ -32765,6 +32873,14 @@ declare class RevTurbineCustomerSdk {
      */
     private candidateCapGate;
     private recordPresentationCapRules;
+    /**
+     * D-60 + D-61: the resolver's gates read the SAME effective entitlements
+     * `checkEntitlement` returns — the shared evaluation merged with
+     * app-mirrored data — for every handle the Playbook, the user context or an
+     * app provider knows. A gate slot's reported `entitlement_status` still
+     * wins inside the resolver.
+     */
+    private withSlotEntitlementStatus;
     private slotIdForRecord;
     private hydratePresentationCaps;
     private persistPresentationCaps;
@@ -32941,22 +33057,25 @@ declare class RevTurbineCustomerSdk {
      * @public
      */
     setApiBranding(branding: BrandingConfig | undefined): void;
+    /**
+     * The effective entitlement (D-61): the shared core evaluator decides from
+     * the Playbook + user context, then app-mirrored data merges per
+     * `entitlementMerge` (default: app wins). The server SDKs run the same
+     * function on the same inputs, so a server re-check verifies exactly this.
+     * An entitlement nobody knows is denied, warned once and reported.
+     */
     private deriveLocalEntitlementFromConfiguredRules;
     /**
-     * Inline adapter — given a UserTrialStatus + the tenant's
-     * reverse_trial_rules from RevTurbineConfig, derive the inputs that
-     * close plan 43 TASK-2. Returns undefined fields when the user
-     * isn't on an active reverse trial, when no rule matches, or when
-     * the rule has no entitlements_during_trial[].
-     *
-     * Why inline (not calling scaffold's deriveReverseTrialGrants):
-     * the scaffold helper takes a `TrialInstance` (DB-side state) and
-     * matches by `rule_id`. The SDK only holds `UserTrialStatus` (the
-     * transient runtime shape) and doesn't see the rule_id. We match
-     * by `fallback_plan_id === plan_handle` instead — that's the
-     * single configured rule the user can be on per spec §2.4.2.
+     * D-61: snapshot what the app's own providers say — plan, entitlement
+     * entries, usage — so the browser evaluates on exactly the inputs a server
+     * runtime with the same providers would. A static adapter's blanket
+     * defaults are not app data.
      */
-    private resolveReverseTrialGrants;
+    private captureAppProviderState;
+    /** D-61: resolve the app's providers before an entitlement check (cached per provider TTL). */
+    private refreshAppProviderState;
+    /** D-61: an unknown entitlement handle is denied; say so once, locally and in telemetry. */
+    private reportUnknownEntitlement;
     /**
      * Return the SDK-resolved targeting snapshot for the active user.
      *