@revturbine/sdk 0.10.6 → 0.10.8

package/CHANGELOG.md

@@ -47,6 +47,105 @@ also require a changelog entry.
 
 ---
 
+## 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)
+
+**What changed.** Payload `status` is no longer a runtime predicate in any port.
+Python and Rust required `status == "active"` on a placement payload before it
+could become a candidate, and read a `status` off each content-linked studio
+payload before overlaying its copy. Both now ignore it, matching the TypeScript
+port, which never gated on it.
+
+| | Before | After |
+|---|---|---|
+| Placement payload candidacy (Python, Rust) | required `status == "active"` | every payload, status ignored |
+| Content-linked copy overlay (Python, Rust) | required the studio payload's `status` to read `active` | always overlaid |
+| TypeScript | already ignored `status` | unchanged |
+
+**Why it mattered.** `status` is not a field of the exported Playbook.
+`RevTurbineConfigStudioPayload` and `RevTurbineConfigPlacementPayloadItem` carry
+no `status` key, unknown keys are stripped on parse, and the published JSON
+Schema is `additionalProperties: false` — because runtime status is *derived*
+control-plane side and the stored column was dropped. So `status == "active"` was
+false for **every** payload of a real Playbook: the Python and Rust resolvers
+indexed no candidates at all and returned `placement_not_found`, and their
+content-lookup adapters dropped every content-linked payload, keeping the inline
+copy where TypeScript overlaid the linked block. A config whose first payload
+carried a stray authored `status` also decided differently across ports.
+
+The cross-language parity gate could not see any of this: the only fixtures
+reaching these paths hand-write `status` on each payload — a key the schema would
+strip — so the ports were compared on a shape no Playbook has.
+
+**Landed in.** 0.10.7 (`server-python`, `server-rust`). No `@revt-eng/core`
+change rides with it: TypeScript was already correct, so there is no scaffold
+release and no pin bump.
+
+**Fail-closed in.** n/a — this release removes a fail-*closed* filter. Python and
+Rust consumers on a real Playbook go from no decision to the decision
+TypeScript has always returned.
+
+**Proving test.** `tests/parity/fixtures/payload_status_filter.json` — two lanes:
+a stray authored `status` that disagrees with drag order (payload 1 `draft`,
+payload 2 `active`; payload 1 must still win), and the real wire shape with no
+`status` anywhere plus a content-linked overlay. Mutation-checked by reinstating
+the Python filter, which diverges on the first call. Plus
+`server-python/tests/placements/test_local_resolver.py`,
+`test_json_content_provider.py` and `server-rust/tests/static_resolver.rs`, each
+covering both the stray-value and the no-key case.
+
+**Who is affected.** Every `revturbine` (PyPI) and `revturbine` (crates.io)
+consumer resolving placements from a schema-valid exported Playbook — that is,
+one produced by the control plane rather than hand-written with a `status` field.
+Those integrations were receiving no placement decisions at all.
+
+---
+
 ## 0.10.6
 
 ### The trial-status PlanProvider overlay ships in the Rust crate (BL-0153)

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.