@revturbine/sdk 0.10.7 → 0.10.9

package/CHANGELOG.md

@@ -47,6 +47,97 @@ also require a changelog entry.
 
 ---
 
+## 0.10.9
+
+### The trial-status overlay no longer changes a number's type (BL-0155)
+
+**What changed.** The `UserTrialStatus` → `trial_*` PlanProviderState overlay now
+passes each numeric field through on every port, instead of two ports widening
+it to a float. The canonical behaviour is the TS SDK's
+`synthesizeProviderContext` (`web-sdk/customer-side.ts`, the `planTrialFields`
+block), which spreads every `UserTrialStatus` member verbatim: an integer
+`progress_percent` stays an integer on the provider state, and
+`trial_days_total` is `day_number + days_remaining` in the inputs' own kind, so
+`7 + 3` is `14`. The two server ports diverged from it:
+
+| field | Python before | Rust before | all three now |
+|---|---|---|---|
+| `progress_percent` → `trial_progress_percent` | `float(v)` | verbatim | verbatim |
+| `days_remaining` → `trial_days_remaining` | `float(v)` | verbatim | verbatim |
+| `usage_consumed` → `trial_usage_consumed` | `float(v)` | verbatim | verbatim |
+| `usage_limit` → `trial_usage_limit` | `float(v)` | verbatim | verbatim |
+| `in_trial` → `trial_active` | `bool(v)` | verbatim | verbatim |
+| derived `trial_days_total` | `float(a) + float(b)` | `f64` sum | `int + int` → `int`; any fractional half → float |
+
+**Who this reaches.** Only a host that reads the provider state it built —
+`revturbine::overlay_trial_status_on_plan_provider` on Rust, or the merged
+`PlanProviderState` on Python — and cares whether it holds `70` or `70.0`
+(serializing it, comparing it to an integer, or logging it). No decision
+changes: every reader in the trial-gating layer widens on read, which is exactly
+why the divergence survived. A non-numeric `day_number`/`days_remaining` half
+now derives no total on Python instead of raising, matching Rust's existing
+numeric guard.
+
+**Landed in.** `0.10.9`.
+
+**Fail-closed in.** `0.10.9` — there was no tolerated-old-shape window; the
+representation simply changes.
+
+**Proving test.**
+`server-python/tests/test_trial_overlay_upsert.py::test_overlay_preserves_integer_numeric_representation`
+and `server-rust/src/sdk.rs::overlay_preserves_integer_numeric_representation`
+— both assert the *type*, not just the value, because `100 == 100.0` in Python.
+The parity corpus cannot see this class of divergence (`tests/parity/normalize.*`
+rule 4 collapses integral floats by design); scenario
+`trial_overlay_integer_fields` locks that the three ports still decide
+identically from an all-integer trial status.
+
+---
+
+## 0.10.8
+
+### `{{recommended_plan_name}}` and `{{plan_name}}` no longer reach end users as raw tokens (BL-0121)
+
+**What changed.** The placement-decision lane now substitutes the five tokens
+the SDK resolves from the Playbook — `plan_name`, `plan_price`,
+`upgrade_plan_price`, `recommended_plan_handle`, `recommended_plan_name` —
+into `RevTurbinePlacementDecision.content` (and the mirrored
+`decision.output.content`). It previously substituted `plan_price` and
+`upgrade_plan_price` only.
+
+`recommended_plan_handle` / `recommended_plan_name` were already derived, by
+the parity-locked `resolveRecommendedPlanTokens` dispatch, and already readable
+via `getPersonalizationTokens()`. Nothing wrote them into rendered content, so
+a placement authored with `"Upgrade to {{recommended_plan_name}}"` shipped the
+literal braces to the end user. Observed on the CybeDefend demo, 2026-09-22.
+
+Two properties of the substitution are deliberate:
+
+| input | result |
+|---|---|
+| a token the SDK owns but cannot resolve (top-of-ladder user has no next plan) | empty string — the spec's documented empty-token convention |
+| a token the SDK does not own (`{{usage_percent}}`, an app-defined token) | left verbatim, so the React render lane still resolves it |
+
+`plan_name` resolves through the plan's `unique_handle`, the matching identity
+— the lookup used to be handed the plan *object*, which by design resolves
+nothing, so `{{plan_name}}` rendered raw for every user identified by
+`plan_handle`.
+
+**Landed in.** `0.10.8`.
+
+**Not fixed here.** `{{upgrade_plan_price}}` still renders the ANNUAL amount
+for a plan that has both an annual and a monthly variation. Variation
+preference keys off the user's billing cadence, but no supported input carries
+it (`billing_period` is absent from `UserContextSchema` and from the recognized
+`identify()` / `update()` keys), so selection falls through to the
+alphabetically-first variation and `<plan>_annual` always wins. Closing it
+needs a schema field for the cadence and a contract for which period the token
+reflects when the cadence is unknown; both are open on BL-0121.
+
+**Proving test.** `web-sdk/customer-side-upgrade-tokens.test.ts`.
+
+---
+
 ## 0.10.7
 
 ### The Python and Rust ports stop filtering payloads on `status` (BL-0151)

package/dist/headless.d.ts

@@ -21140,6 +21140,29 @@ declare class RevTurbineCustomerSdk {
     getEligibleAddons(): Promise<EligibleAddon[]>;
     private formatEligiblePrice;
     private priceTokensForProviders;
+    /**
+     * The plan-and-recommendation token family the SDK resolves authoritatively
+     * from the Playbook, for substitution into decision content.
+     *
+     * These five are exactly the tokens whose values come from the Playbook's
+     * plan catalogue plus the recommendation strategy, so the SDK — not the
+     * host app — is the only thing that can fill them in. Every other token in
+     * the studio table (usage, trial, seats, credits) is resolved on the React
+     * render lane by `derivePlacementPersonalizationTokens`, which unknown
+     * tokens pass through untouched.
+     */
+    private derivedContentTokens;
+    /**
+     * Substitute the SDK-resolved plan/price/recommendation tokens into a
+     * decision's content.
+     *
+     * Only the tokens in {@link derivedContentTokens} are substituted; any
+     * other `{{token}}` is left verbatim so the render lane (or the host app)
+     * can still resolve it. A token the SDK owns but cannot resolve — a
+     * top-of-ladder user has no recommended plan — becomes an empty string,
+     * which is the spec's documented empty-token convention and is what keeps
+     * raw `{{...}}` braces off the end user's screen.
+     */
     private applyPriceTokens;
     /**
      * Return current SDK policy snapshot.