@revturbine/sdk 0.10.4 → 0.10.6

package/CHANGELOG.md

@@ -47,6 +47,103 @@ also require a changelog entry.
 
 ---
 
+## 0.10.6
+
+### The trial-status PlanProvider overlay ships in the Rust crate (BL-0153)
+
+**What changed.** `revturbine::overlay_trial_status_on_plan_provider` is a new
+public function on the Rust crate: it maps a runtime `UserTrialStatus` onto the
+`trial_*` fields of a resolved PlanProviderState, the fields the placement
+resolver's `trial_progress` / `trial_ending` / `trial_ended` /
+`trial_converted` gates and milestone supersession read. Python has always done
+this inside its shipped package
+(`revturbine.sdk._overlay_trial_status_on_plan_provider`); on Rust the mapping
+existed only as a private helper the facade used, so a host that assembles its
+own provider context — including this repo's own parity runner — had to
+re-implement it. Additive: no existing signature changed.
+
+Porting Python's mapping faithfully corrected two Rust-only divergences in the
+overlay the facade applies:
+
+| `UserTrialStatus` field | Rust before | Rust now (= TS/Python) |
+|---|---|---|
+| `day_number` + `days_remaining` | not derived | `trial_days_total = day_number + days_remaining`, only when both are present |
+| `day_number` | written to `trial_day_number` | not written — no provider-state field reads it |
+| `usage_entitlement_handle` | dropped | `trial_usage_entitlement_handle` |
+
+`trial_days_total` is the input to the time-mode progress fallback in
+`placements::trial_gating`, so before this the fallback could never fire on the
+Rust port.
+
+**Landed in.** `0.10.6`.
+
+**Fail-closed in.** `0.10.6` — the parity facade-presence gate
+(`tests/parity/facade-surface.json`) no longer allow-lists a runner-local
+overlay, so a future re-implementation harness-side fails the gate.
+
+**Proving test.** `server-rust/src/sdk.rs` `overlay_maps_every_canonical_trial_field`,
+`trial_days_total_requires_both_halves`, `overlay_does_not_clobber_base_state_with_null`
+(mirroring `server-python/tests/test_trial_overlay_upsert.py`), plus the
+`trial_ending_days_before_end`, `trial_ended_post_expiry` and
+`trial_progress_milestone_supersession` parity fixtures.
+
+---
+
+## 0.10.5
+
+### Trial-only local integrations get provider context (BL-0120)
+
+**What changed.** `synthesizeProviderContext()` — the fallback that builds
+`DomainProvider` state from `userContext` when no explicit domain provider is
+registered — dropped an integration's trial data whenever no commercial
+`plan` / `plan_handle` was also present. An app supplying **only**
+`initialData.trialStatus` (or `setTrialInstances()` / `setTrialStatus()` with
+no plan) got no provider context at all: `providers.plan` came back
+`undefined`, so `{{trial_days_remaining}}` (and every other `trial*` token
+`derivePlacementPersonalizationTokens` derives from `providers.plan`) stayed
+raw, unresolved, in placement copy. Reported against the CybeDefend demo
+(SDK 0.7.13): a `trial_ending` placement with `in_trial: true,
+days_remaining: 3` left `{{trial_days_remaining}}` literal in the rendered
+body.
+
+Two omissions, same root cause — trial was never checked alongside
+`plan` / `plan_handle` / `usage` / `tiers` / `experiments`:
+
+- the early-return guard (`if (!plan && !planHandle && !usage && !hasTiers
+  && !hasExperiments) return undefined;`) treated a trial-only integration as
+  having no signal whatsoever;
+- even past that guard, the returned `plan` key itself was gated on
+  `plan || planHandle` — so the trial fields (`trialActive`,
+  `trialDaysRemaining`, etc.) it computed were still discarded for a
+  plan-less trial.
+
+Both gates now also check `hasTrial` (an explicit trial signal — the default
+untouched `{ in_trial: false }` sentinel does not count, so the omitted-signal
+short-circuit is otherwise unchanged for integrations that supply nothing at
+all). `usage`-only, `tiers`-only, and `experiments`-only integrations already
+threaded through correctly before this change; trial was the only signal
+missing from both checks.
+
+No public API change — `synthesizeProviderContext` is private, and the fix is
+additive: a plan-less trial integration now gets a `providers.plan` it never
+got before, with an empty `currentPlanHandle: ''` (no plan name/handle was
+ever supplied to derive one from).
+
+**Landed in** `0.10.5`. **Fail-closed in** n/a — a previously-dropped signal
+is now included; nothing that resolved before stops resolving.
+
+**Proving test:** `web-sdk/customer-side-trial-token-signal.test.ts` — a
+trial-only local integration now gets a non-empty provider context with
+`trialActive`/`trialDaysRemaining` set, and feeding those through
+`derivePlacementPersonalizationTokens` + `resolveContent` renders
+`{{trial_days_remaining}}` as `"3"` instead of leaving it literal. Includes
+the positive control (trial + plan together — unchanged), the negative
+control (no trial data at all — the token stays absent, never coerced to
+`"0"`), and a sibling check confirming usage-only integrations were already
+unaffected by the guard.
+
+---
+
 ## 0.10.4
 
 ### Every payload is a selection candidate, not just the first (BL-0122)
@@ -94,6 +191,8 @@ placement where payload 1 is not the payload a given user matches. Those users
 now see the payload their chips select — which is the fix, and is a live
 behaviour change for such configs. Single-payload placements are unaffected.
 
+---
+
 ## 0.10.3
 
 ### The Rust port gains the decision surfaces Python already shipped (BL-0145)
@@ -124,6 +223,8 @@ and the crate could lack the capability entirely without a single fixture
 going red. The runner now calls `revturbine::plans`, and the inline copies are
 deleted; all 102 comparisons stay byte-identical.
 
+---
+
 ## 0.10.2
 
 ### Local mode resolves placements by slot id (BL-0119)