@revturbine/sdk 0.11.18 → 0.11.20

package/CHANGELOG.md

@@ -47,6 +47,96 @@ also require a changelog entry.
 
 ---
 
+## 0.11.20
+
+### One entitlement answer for browser and server, with Entitlement Mirroring; Access Gates only fire while denied (D-60, D-61)
+
+**What changed.** Behaviour change in every port. Browser and server now run
+the same evaluation on the same inputs: the browser is trusted for
+interaction, and the server verifies.
+
+- **One effective entitlement (ts/py/rs/web).** Every entitlement check runs
+  the shared core evaluator over the Playbook and the user context (plan,
+  segments, usage, reverse-trial grants), then merges app-supplied data. Server
+  runtimes previously used a separate rule path that ignored reverse-trial
+  grants and allowed everything when the Playbook had no entitlement rules.
+  **Server-side results change for the live design partner:** a configured
+  entitlement with no rule for the user's plan is now denied on the server
+  too, and reverse-trial grants are honoured there.
+- **Entitlement Mirroring.** `UserContext.entitlements` accepts a boolean or a
+  grant (`status`, `limit`, `used`), and an app entitlement provider's
+  entries count as app data. By default the app's data wins;
+  `entitlementMerge` (`entitlement_merge` in Python and Rust) sets provider-level
+  `precedence` and per-field overrides. Browser-supplied data shapes the UI;
+  the server re-check stays authoritative.
+- **Unknown entitlement handles fail closed.** A handle neither the Playbook
+  nor the app knows is denied with `entitlement_not_in_playbook`, warned once,
+  and reported (browser telemetry; `onUnknownEntitlement` on the server).
+  0.11.19 returned `entitlement_not_found_default_allow`.
+- **Access Gates (D-60).** A gate placement appears only in an Access Gate
+  slot and fires only while its entitlement is denied or limited (a
+  tier-scoped gate below its tier counts as limited). Placement gates read the
+  same effective entitlements `checkEntitlement` returns.
+- **Reason codes.** New entitlement reason `entitlement_mirrored`; new
+  placement reasons `entitlement_not_denied` and `gate_outside_access_gate`.
+- **Scaffold pin 0.1.402 → 0.1.409** (revturbine-scaffold #462, #465
+  and #468; vendored `types.py` / `types.rs` refreshed).
+
+**Landed in** 0.11.20. **Fail-closed in** 0.11.20.
+
+**Proving tests.** `web-sdk/entitlement-mirroring.test.ts`; the D-60/D-61
+blocks in each port's resolver and runtime tests; parity fixtures
+`placement_slot_selection_is_category_first` and
+`placement_category_interactions`.
+
+## 0.11.19
+
+### Placement decisions rank category first; caps run before the pick; overall presentation cap rules enforced (D-59, BL-0536)
+
+**What changed.** Behaviour change in every port; no public signature changes.
+
+- **Ranking (ts/py/rs).** When several placements qualify for one slot, the
+  decision now ranks by category first — Access Gates, then Fixed, then
+  usage/credit/seat + trial alerts, then conversion/retention nudges — and
+  then within the category: two-stage urgency for alerts (trial transition,
+  then limit reached, then approaching; then proximity), drag order
+  otherwise. 0.11.18 took the first eligible placement in list order (D-34),
+  so an "approaching" warning listed above a "limit reached" alert used to
+  win; now the limit-reached alert wins. Equal drag order across the two
+  categories of a shared tier resolves Usage before Trials and Conversion
+  before Retention. Among fired usage thresholds on one entitlement, the
+  highest wins.
+- **Caps before the pick (web).** A placement over its per-payload cap or an
+  overall presentation cap is skipped and the next-ranked placement is shown.
+  0.11.18 picked first, then hid the slot. A cached decision whose winner is
+  now capped re-resolves instead of blanking the slot.
+- **Payload caps are enforced (web).** Playbook-authored `max_per_period` /
+  `cooldown_days` never reached the cap check; they now do. A placement with
+  authored caps may now stop showing where 0.11.18 kept showing it.
+- **Overall presentation cap rules (web).** The Placement Settings cap rules
+  and session cooldown (`placement_settings[].global_frequency_cap`) are
+  enforced for conversion/retention placements, persisted per user;
+  `session` periods count from the tab session's start.
+- **Access Gate slots (all ports + web).** A slot that asks for an
+  entitlement is answered only by that entitlement's placements; with none
+  authored, the decision is `no_gate_for_entitlement` and
+  `<AccessGateSurfaceSlot>` renders the new `<AccessDeniedPlaceholder>`
+  unless the app passes `deniedFallback`. 0.11.18 showed any other gate on
+  the same template.
+- **Reason codes.** New placement reasons `no_gate_for_entitlement`,
+  `suppressed_by_presentation_cap` and `suppressed_by_system_cooldown`
+  (added to the reason-code baseline).
+- **Scaffold pin 0.1.383 → 0.1.402** (`@revt-eng/core` with revturbine-scaffold #460; vendored `types.py` / `types.rs` refreshed).
+
+**Landed in** 0.11.19. **Fail-closed in** 0.11.19.
+
+**Proving tests.** Parity fixtures `placement_slot_selection_is_category_first`,
+`placement_limit_reached_beats_approaching` and
+`placement_shared_tier_tie_resolves_by_category` (they replace
+`placement_slot_selection_is_entry_order` and
+`placement_first_eligible_beats_urgency`); `web-sdk/presentation-cap-rules.test.ts`;
+`web-sdk/placements/AccessGateSurfaceSlot.placeholder.test.tsx`.
+
 ## 0.11.18
 
 ### Scaffold pin 0.1.383: interaction decision context moves onto core's input type; `growth_signal_observed` retired (plan 282 TASK-9 follow-up, BL-0463)

package/dist/growthbook.d.ts

@@ -293,6 +293,16 @@ type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
 };
 
+/** 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;
+};
+
 /**
  * User context lifecycle — pure functions for building, merging,
  * and deriving targeting state from user context + RevTurbineConfig.
@@ -315,7 +325,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. */