@revturbine/sdk 0.10.8 → 0.10.10

package/CHANGELOG.md

@@ -47,6 +47,115 @@ also require a changelog entry.
 
 ---
 
+## 0.10.10
+
+### Trial tokens now reach placement content, not only `getPersonalizationTokens()` (BL-0169)
+
+**What changed.** A placement whose copy authors `{{trial_days_remaining}}` or
+`{{trial_days_total}}` now renders the live values. Content interpolation sources
+its token map from the **output content itself**, so a provider-derived token
+only reaches the copy if the resolver writes it onto that content first. The
+usage lane always did (`usage_current`, `usage_limit`, `usage_percent`,
+`usage_remaining`, `reset_date`); the trial lane never did, so a `trial_ending`
+body reading `"{{trial_days_remaining}} days left"` shipped the literal
+`{{trial_days_remaining}}` to the end user — on every port. The two names were
+derived for `getPersonalizationTokens()` all along, which is why the gap survived:
+a host that read the token map saw the right numbers and a host that authored the
+token into copy did not.
+
+| | before | now |
+|---|---|---|
+| `getPersonalizationTokens().trial_days_remaining` | live value | live value (unchanged) |
+| content `{{trial_days_remaining}}` / `{{trial_days_total}}` | literal `{{…}}` | live value |
+| `outputContent.trial_days_remaining` / `_total` | absent | written when the plan provider carries a finite number |
+
+Identical on all three ports (`ts:local-resolver.ts`,
+`py:core/placements/local_resolver.py`, `rs:placements/static_resolver.rs`): the
+same two token names, a `Number.isFinite` guard, provider state winning over an
+authored content value of the same key, and the value passed through **without
+widening** — `day_number` 7 + `days_remaining` 3 is `trial_days_total` `10`, never
+`10.0` (BL-0155).
+
+**Who this reaches.** Any host whose placement copy authors either token. Copy
+that hard-coded one of those keys as a decorative literal now has it overwritten
+by live state — the same precedence the usage lane and
+`derivePlacementPersonalizationTokens` have always had. `{{trial_plan_name}}` and
+`{{trial_features_used}}` remain **not yet wired** by the placement-studio-ui
+spec's own note and are untouched.
+
+**Landed in.** `0.10.10`.
+
+**Fail-closed in.** `0.10.10` — absence still leaves the raw token standing
+rather than rendering `0`, so a host with no trial provider state sees exactly
+what it saw before.
+
+**Proving test.** Parity scenario `trial_tokens_in_content` under
+`"normalize": "preserve-representation"` (byte-locked ts ≡ py ≡ rs), plus
+`py:tests/placements/test_local_resolver.py` and `rs:tests/static_resolver.rs`
+`trial_tokens_are_injected_from_plan_provider_state` and its two neighbours,
+mirroring the scaffold-side `local-resolver.test.ts` cases. Needs
+`@revt-eng/core` 0.1.331 or later (scaffold #382) for the TS half; this release
+pins 0.1.332.
+
+---
+
+## 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.
+Scenario `trial_overlay_integer_fields` locks that the three ports still decide
+identically from an all-integer trial status.
+
+> **Correction, 2026-09-23 (BL-0158, harness-only — no release).** This entry
+> originally said the parity corpus *cannot* see this class of divergence,
+> because `tests/parity/normalize.*` rule 4 collapses integral floats by design
+> and nothing in the corpus returned the overlaid provider state. Both halves
+> are now closed and the sentence no longer holds:
+> `trial_overlay_integer_fields` drives `resolveProviders` (already shipped on
+> all three runtimes) under a new per-scenario
+> `"normalize": "preserve-representation"` flag that turns the collapse off, so
+> `14` and `14.0` are different bytes and the cross-language byte-diff fails on
+> a widened field. No public API changed; the harness gained the ability to see
+> provider state.
+
+---
+
 ## 0.10.8
 
 ### `{{recommended_plan_name}}` and `{{plan_name}}` no longer reach end users as raw tokens (BL-0121)

package/dist/headless.d.ts

@@ -13185,8 +13185,8 @@ declare const PlaybookObjectSchema: z.ZodObject<{
 /**
  * The one canonical config schema. Parses BOTH a canonical Playbook and a legacy
  * `export-config.json` (via `normalizeConfigHeaderInput`) into the canonical
- * Playbook shape, so `ExportedConfigSchema` / `RevTurbineConfigSchema` are true
- * aliases of it. `.meta({ id: 'Playbook' })` rides on this preprocess wrapper
+ * Playbook shape, so `RevTurbineConfigSchema` (and its deprecated
+ * `ExportedConfigSchema` alias) are true aliases of it. `.meta({ id: 'Playbook' })` rides on this preprocess wrapper
  * (the underlying object is id-less) so the OpenAPI / JSON-Schema generators emit
  * a single well-formed `Playbook` component. Introspection that needs `.shape`
  * must read `PlaybookObjectSchema`, not this wrapper.
@@ -17164,6 +17164,50 @@ type JsonObject = {
     [key: string]: JsonValue;
 };
 
+/**
+ * BL-0156 — `playbook` is the canonical option name; `exportedConfig` is a
+ * deprecated alias.
+ *
+ * "ExportedConfig" is dead vocabulary. Plan 118 renamed the domain object to
+ * **Playbook** and plan 104 renamed the schema type to `RevTurbineConfig`, but
+ * the *option* and *parameter* names that carry a Playbook around core still
+ * spelled it `exportedConfig`. This module is the single place that reconciles
+ * the two spellings, mirroring the plan-257 `publicKey` mechanism:
+ *
+ *   - the canonical `playbook` wins whenever it is supplied,
+ *   - the deprecated `exportedConfig` is still accepted,
+ *   - supplying only the alias emits ONE warning naming the canonical option,
+ *   - supplying BOTH with *different* Playbooks throws instead of silently
+ *     picking one — that combination is always a caller bug.
+ *
+ * Every read site resolves through `resolvePlaybookOption` /
+ * `requirePlaybookOption`, so the precedence cannot drift per call site.
+ *
+ * **Why the warning is not gated on a development build.** Core's ESLint config
+ * blocks the `process` global outright (`no-restricted-globals`) because core
+ * must run unchanged on edge runtimes and in browsers, so core cannot read
+ * `NODE_ENV` the way `web-sdk/build-mode.ts` does. The warning is therefore
+ * emitted once per runtime in every build — a single line, only for callers
+ * still on the deprecated spelling, and it names the fix.
+ *
+ * Aliases are removed in the minor after the SDK 0.11.0 cascade.
+ */
+
+/**
+ * An options bag that must carry a Playbook, under either the canonical
+ * `playbook` name or the deprecated `exportedConfig` alias.
+ *
+ * Modelled as a union so TypeScript still requires one of the two, exactly as
+ * the single required property did before the rename.
+ */
+type PlaybookOption = {
+    playbook: RevTurbineConfig;
+    exportedConfig?: RevTurbineConfig;
+} | {
+    playbook?: RevTurbineConfig;
+    exportedConfig: RevTurbineConfig;
+};
+
 /**
  * User context lifecycle — pure functions for building, merging,
  * and deriving targeting state from user context + RevTurbineConfig.
@@ -18118,12 +18162,18 @@ interface LocalPlacementDataset {
 type LocalPlacementEntry = NonNullable<RevTurbineConfig['placements']>[number];
 type LocalPlacementPayload = LocalPlacementEntry['payloads'][number];
 type LocalPlacementSurface = LocalPlacementPayload['surfaces'][number];
-/** Backward-compat JSON entry point. */
-interface StaticPlacementResolverOptions {
+/** Backward-compat JSON entry point, minus the Playbook. */
+interface StaticPlacementResolverOptionsBase {
     placements: LocalPlacementDataset;
-    exportedConfig: RevTurbineConfig;
     impressionHistory?: ImpressionHistory;
 }
+/**
+ * Options for {@link createStaticPlacementResolver}.
+ *
+ * The Playbook is supplied as `playbook`; `exportedConfig` is a deprecated
+ * alias removed in the minor after the SDK 0.11.0 cascade (BL-0156).
+ */
+type StaticPlacementResolverOptions = StaticPlacementResolverOptionsBase & PlaybookOption;
 /**
  * Backward-compat JSON entry. Thin wrapper around the unified
  * `createLocalPlacementResolver`. Use the unified factory directly
@@ -18551,8 +18601,8 @@ declare function createHydrationProviders(options: HydrationAdapterOptions): Any
  * const runtime = new LocalRuntime({
  *   tenantId: 'tenant_abc',
  *   userId: 'user_123',
- *   exportedConfig: myConfig,
- *   providers: createStaticProviders({ config: myConfig, planHandle: 'pro' }),
+ *   playbook: myPlaybook,
+ *   providers: createStaticProviders({ config: myPlaybook, planHandle: 'pro' }),
  *   storage: new InMemoryStorage(),
  * });
  *
@@ -18561,18 +18611,21 @@ declare function createHydrationProviders(options: HydrationAdapterOptions): Any
  * ```
  */
 
-interface LocalRuntimeOptions {
+/**
+ * `LocalRuntimeOptions` minus the Playbook, which arrives through
+ * {@link PlaybookOption} so both the canonical `playbook` name and the
+ * deprecated `exportedConfig` alias are accepted.
+ */
+interface LocalRuntimeOptionsBase {
     /** Tenant identifier. */
     tenantId: string;
     /** Current user identifier. */
     userId: string;
-    /** Full RevTurbineConfig for local resolution. */
-    exportedConfig: RevTurbineConfig;
     /** Pre-built domain providers (from createStaticProviders, etc.). */
     providers: AnyDomainProvider[];
     /**
      * Optional pre-built placements dataset. If not provided, derived from
-     * `exportedConfig.placements`.
+     * `playbook.placements`.
      */
     placements?: LocalPlacementDataset;
     /**
@@ -18589,6 +18642,14 @@ interface LocalRuntimeOptions {
     /** Interaction tracker options. */
     interactionOptions?: Partial<Pick<InteractionTrackerOptions, 'defaultDismissCooldownMs' | 'defaultRemindLaterMs'>>;
 }
+/**
+ * Options for {@link LocalRuntime}.
+ *
+ * The Playbook is supplied as `playbook`. The `exportedConfig` spelling is a
+ * deprecated alias kept so consumers can migrate incrementally; it is removed
+ * in the minor after the SDK 0.11.0 cascade (BL-0156).
+ */
+type LocalRuntimeOptions = LocalRuntimeOptionsBase & PlaybookOption;
 declare class LocalRuntime {
     readonly tenantId: string;
     readonly registry: DomainProviderRegistry;
@@ -18596,7 +18657,7 @@ declare class LocalRuntime {
     readonly interactionTracker: InteractionTracker;
     readonly capEnforcer: CapEnforcer;
     readonly impressionHistory: ImpressionHistory;
-    private readonly exportedConfig;
+    private readonly playbook;
     private readonly registeredPlacements;
     private userId;
     constructor(options: LocalRuntimeOptions);
@@ -18668,7 +18729,14 @@ declare class LocalRuntime {
     setUserId(userId: string): void;
     /** Current user ID. */
     getUserId(): string;
-    /** Return the active RevTurbineConfig snapshot. */
+    /** Return the active Playbook snapshot. */
+    getPlaybook(): RevTurbineConfig;
+    /**
+     * Return the active Playbook snapshot.
+     *
+     * @deprecated Use {@link LocalRuntime.getPlaybook}. Removed in the minor
+     * after the SDK 0.11.0 cascade (BL-0156).
+     */
     getExportedConfig(): RevTurbineConfig;
     /**
      * Pre-warm caches (impression history, etc.) for synchronous access.