@revturbine/sdk 0.11.4 → 0.11.6

package/CHANGELOG.md

@@ -47,6 +47,137 @@ also require a changelog entry.
 
 ---
 
+## 0.11.6
+
+### `sdk.convert()` reloads the UserContext, so a mounted slot re-decides (BL-0004)
+
+**What changed.** `sdk.convert(outputId)` used to record the conversion and stop
+there. Conversion writes **no** cooldown and **no** permanent retirement — by
+design (Kent's plan 254 D-9 ruling; the `convert` row of the spec's interaction
+table) — so eligibility is a function of the user's CURRENT plan and targeting.
+That left a real gap: a host that called the public convert path while the
+placement was mounted saw the upgrade banner stay on screen until the slot next
+happened to resolve a decision. The documented workaround was a manual
+`refresh()` or the component's `ctaComplete()`. Plan 236 TASK-13 recorded it as
+an open product call rather than asserting it away.
+
+Kent ruled on it, 2026-09-25: *"Converting should trigger a reloading of
+UserContext with the new plan/billing state the user has converted to."*
+
+So `convert()` now, after recording the interaction:
+
+1. **Optimistically** moves the held plan when the converted output's CTA names
+   one (`cta_path.plan_handle` — e.g. `open_checkout` with `config.purchase`).
+   The Playbook supplies the plan's display name when it knows it.
+2. Notifies user-context subscribers **either way** — a CTA that names no plan
+   still re-decides mounted surfaces.
+3. **Then** refreshes from `GET /api/sdk/client-context`, which overlays the
+   RevTurbine-authoritative trial / billing-health / plan fields. Best-effort and
+   never throwing, exactly as before; a no-op when no client-session minter is
+   configured.
+
+Optimistic-first because billing truth arrives by Stripe webhook: a
+`client-context` read that races the webhook still reports the OLD plan, and
+waiting for it would leave the upgrade prompt up at the exact moment the user
+paid. For the same reason, while a conversion is pending a server plan **equal to
+the plan converted away from** is dropped (plan fields only — trial and
+billing-health always apply). Any other value clears the pending state and
+applies, so the suppression cannot outlive the lag it covers.
+
+Mounted `PlacementController`s re-decide and mounted `EntitlementGate`s re-check
+through `watchUserContext()`. The React bindings attach it for you
+(`usePlacement`, and so every surface slot built on it; `useEntitlement` /
+`useCan` already did), and `SdkSession.placement()` / `.entitlement()` attach it
+for headless consumers. `dispose()` drops it. `PlacementController.ctaComplete()`
+is unchanged.
+
+**What did NOT change.** `convert()`'s signature. Conversion still writes no
+suppression and no retirement: back on the old plan, the placement is eligible
+again. The optimistic plan move is a session-local overlay, not a new source of
+plan truth — a host that re-declares `plan_handle` on mount wins, and that is the
+intended precedence.
+
+**Landed in.** `0.11.6` (BL-0004; refs BL-0177, BL-0179 for the re-decide
+mechanism this reuses).
+
+**Fail-closed in.** `0.11.6` — same version. Nothing was silently tolerated
+before: the old behaviour was a placement that stayed visible, which is why the
+limitation was documented rather than dated.
+
+**Proving test.** `web-sdk/convert-reloads-user-context.test.ts` (headless: the
+mounted controller's decision goes invisible, a failed conversion moves nothing,
+a CTA with no plan still notifies, and the stale-server-plan guard both
+suppresses and releases); `web-sdk/react/convert-reloads-user-context.test.tsx`
+(a mounted `usePlacement` banner disappears in place and a mounted `useCan` gate
+flips denied → granted, with no remount); `e2e/journey.spec.ts` BL-0004 legs (a
+real browser: the converted placement leaves the screen with **no** page
+refresh, and the optimistic overlay does not outrank the host's declaration).
+
+**Ports.** No change. The Python and Rust SDKs are synchronous-with-config and
+have no mounted surfaces to notify; they expose no `convert()` and no
+UserContext-reload API, so there is no port-side behaviour to match. The
+decision-level contract they do share — a context carrying the new plan yields
+decisions for that plan — is unchanged, so no parity fixture moves.
+
+---
+## 0.11.5
+
+### `registerSurfaceSlot()` no longer writes to the control plane (BL-0197)
+
+**What changed.** Outside `local_only`, `registerSurfaceSlot()` used to mirror
+every slot to the server: `upsertSurfaceSlot()` PUT a legacy surface-slot body
+(`{name, slug, slot_type, status, targeting_rules, content, priority,
+metadata}`) to `/api/placements/<slot id>`, then POSTed it to `/api/placements`
+on the 404. `/api/placements` is RevTurbine's **authored-config** CRUD; it
+validates against `PlacementSchema`, which requires `handle` and `category`, so
+that body could only ever be rejected. In production every non-`local_only`
+slot registration failed with `surface_slot_create_failed:422` and the React
+runtime turned the rejection into a `slot_error`
+(`dogfood_event_explorer`, 2026-09-24 18:36 UTC, request
+`030ccf51-d74b-4d55-bf4e-2a929a4ab297`).
+
+The write was also wrong in principle. On a same-origin integration the
+signed-in user's session cookie authenticates the request, so a body the route
+*did* accept would have created a draft placement in the tenant's Playbook just
+from loading a gated page. Only the 422 prevented that.
+
+`registerSurfaceSlot()` is now **client-local**: it records the slot in the
+in-process registry and resolves, with no network write of any kind. A write
+happens only when you configure `endpointOverrides.surfaceSlots` (or
+`custom_endpoints.surfaceSlots`) to point at a slot-inventory service you run —
+the same shape `persistPlacementTypes()` already uses. There is **no fallback
+to `/api/placements`** under any configuration.
+
+Nothing is lost by removing it. Surface-slot discovery is **ingestion-driven**:
+the SDK already emits `slot_evaluated` / `slot_filled` / `slot_empty` /
+`slot_suppressed` / `slot_error` and the `placement_*` lifecycle through
+`/api/track`, carrying `surface_slot_id`, `slot_name`, `template_ids`,
+`surface_type`, `category`, `decision_source` and `reason_codes`, and the
+pipeline derives discovered slots from that telemetry. `SurfaceSlotSchema` is a
+runtime-source (DISCOVERED) schema with `first_seen` / `last_seen` — it was
+never meant to be written by a browser.
+
+**Landed in.** `0.11.5` (BL-0197).
+
+**Fail-closed in.** `0.11.5` — same version. The removed path had no silent
+mode: before this release it threw `surface_slot_create_failed:<status>` on
+every default-transport registration, so there is no window where the old
+behaviour was quietly tolerated. An integration that genuinely relied on the
+write must set `endpointOverrides.surfaceSlots`; one that did not was already
+seeing `slot_error`.
+
+**Proving test.** `web-sdk/surface-slot-registration-no-write.test.ts` — the
+default transport performs zero writes (fetch spy, no `/api/placements` call)
+and resolves even when the route replays the production 404/422; the override
+path still PUTs, and falls back to POST on the override base, never on
+`/api/placements`. `e2e/journey.transport.spec.ts` no longer stubs
+`/api/placements` with a 200 (the stub that hid this): it records and aborts,
+and `assertNoPlacementWrites()` fails the test if anything calls it.
+
+**Ports.** No change — the Python and Rust SDKs never had a slot-registration
+write.
+
+---
 ## 0.11.4
 
 ### The treatment-interaction wire record now carries `rule_handle` (BL-0200)

package/dist/headless.d.ts

@@ -17171,11 +17171,14 @@ interface RevTurbineTreatmentInteractionInput {
      * `PlacementOutput.rule_id` — projected onto the `placement_interaction`
      * clickstream payload as `rule_handle` (BL-0182).
      *
-     * Unlike its neighbours this does NOT reach the wire
-     * `TreatmentInteractionInputSchema` / `placement_presentations`: that path is
-     * column-shaped and would need a datasource migration. The clickstream
-     * carries payload fields inside a JSON column, so the rule slice for
-     * interactions is readable the moment producers send it.
+     * It reaches the wire `TreatmentInteractionInputSchema` too, as of BL-0200.
+     * It deliberately did not under BL-0182: that path is column-shaped and the
+     * rule would have needed a datasource migration, while the clickstream
+     * carries payload fields inside a JSON column and was readable at once.
+     * `placement_exposure_attribution.rule_handle` exists now (web ledger 015),
+     * so the base exposure row records the rule the exposure was DECIDED by
+     * rather than waiting for attribution to reconstruct one when a conversion
+     * lands — which is what makes presentation-grain rule cuts servable.
      *
      * Omitted, never sent empty, when no decision is in scope — a bare
      * `trackTreatmentInteraction` caller supplies no rule, and absence is what
@@ -20481,6 +20484,16 @@ interface RevTurbineEndpointOverrides {
      */
     legacyInteractions?: string;
     placementTypes: string;
+    /**
+     * Optional sink for registered surface slots.
+     *
+     * RevTurbine hosts **no default route** for this verb (BL-0197). Slot
+     * registration is client-local and discovery is ingestion-driven — the
+     * pipeline derives discovered slots from the `slot_*` telemetry the SDK
+     * already emits through `/api/track`. Set this only when you run your own
+     * slot-inventory service; unset, `registerSurfaceSlot()` performs no
+     * network write.
+     */
     surfaceSlots: string;
 }
 /** Client-side clickstream batching policy (plan 95 TASK-6). */
@@ -21137,6 +21150,12 @@ declare class RevTurbineCustomerSdk {
      * redundant segment re-evaluation.
      */
     private lastServerContextHash?;
+    /**
+     * The plan move an optimistic `convert()` made ahead of the server (BL-0004),
+     * held only until a `client-context` read stops reporting the old plan. See
+     * {@link dropStalePostConversionPlan}.
+     */
+    private pendingConversionPlan?;
     private usageBalances;
     private localDecisionsByPlacementId;
     private localPlacementsByLookupKey;
@@ -21934,6 +21953,30 @@ declare class RevTurbineCustomerSdk {
      * @public
      */
     registerPlacement(config: RevTurbinePlacementConfig): Promise<string>;
+    /**
+     * Mirror a registered surface slot to an explicitly configured backend.
+     *
+     * **Requires an explicit `surfaceSlots` endpoint override** (BL-0197).
+     * There is no default route for this verb and there never was a correct
+     * one: the previous default pointed at `/api/placements`, RevTurbine's
+     * *authored-config* CRUD. That route validates against `PlacementSchema`
+     * (which requires `handle` and `category`), so the legacy surface-slot body
+     * this method sends could only ever be rejected — in production every
+     * non-`local_only` registration failed with
+     * `surface_slot_create_failed:422` and the React runtime turned that into a
+     * `slot_error`.
+     *
+     * It was also wrong in principle. On a same-origin integration the signed-in
+     * user's session cookie authenticates the request, so a body the route *did*
+     * accept would have let merely loading a gated page create a draft placement
+     * in the tenant's Playbook. Only the 422 prevented that.
+     *
+     * Surface-slot **discovery is ingestion-driven**: the SDK emits its
+     * `slot_*` / `placement_*` telemetry through `/api/track` and the pipeline
+     * derives discovered slots from it. Registration itself is client-local.
+     *
+     * @internal
+     */
     private upsertSurfaceSlot;
     /**
      * Build the internal placement record for a surface-slot config.
@@ -21956,6 +21999,18 @@ declare class RevTurbineCustomerSdk {
      * @internal
      */
     private commitSurfaceSlotRecord;
+    /**
+     * Register a surface slot with the local runtime and return its placement id.
+     *
+     * **Client-local by default** (BL-0197): this performs no network write. The
+     * slot is recorded in the in-process registry, and the pipeline discovers it
+     * from the `slot_*` / `placement_*` telemetry the SDK emits through
+     * `/api/track`. A write happens only when `custom_endpoints.surfaceSlots`
+     * points at a slot-inventory service you run; there is no fallback to
+     * `/api/placements`.
+     *
+     * @public
+     */
     registerSurfaceSlot(config: RevTurbineSurfaceSlotConfig): Promise<string>;
     /**
      * Persist authored placement types to a configured backend.
@@ -22245,12 +22300,16 @@ declare class RevTurbineCustomerSdk {
     /** Map the client-safe context response into a UserContext patch (plan 157). */
     private mapClientSafeContext;
     /**
-     * Apply a server-derived UserContext patch (plan 157) — mirrors setUserContext
-     * but accepts a partial. The patch's RevTurbine-authoritative fields (trial,
-     * billing signals) overlay the held context; undefined fields are skipped by
-     * the merge, so app-set values are never nulled.
+     * Apply a UserContext patch — mirrors setUserContext but accepts a partial.
+     * RevTurbine-authoritative fields (trial, billing signals, server plan)
+     * overlay the held context; undefined fields are skipped by the merge, so
+     * app-set values are never nulled.
+     *
+     * Two callers: the server client-context fetch (plan 157) and the optimistic
+     * post-conversion plan move (BL-0004). Both notify subscribers, which is what
+     * makes mounted slots and gates re-resolve.
      */
-    private applyServerContextPatch;
+    private applyUserContextPatch;
     /**
      * Record that a placement was rendered to the user. Plan 43 TASK-9.
      *
@@ -22427,13 +22486,73 @@ declare class RevTurbineCustomerSdk {
      */
     snooze(outputId: string, seconds?: number): Promise<void>;
     /**
-     * Record a confirmed CTA completion and retire the decision's placement
-     * permanently — future calls to `getPlacementDecision` for it will not
-     * return it again.
+     * Record a confirmed CTA completion, then reload the UserContext so every
+     * mounted surface re-decides against the plan the user just converted to.
+     *
+     * Conversion is **not** a suppression: it writes no cooldown and no permanent
+     * retirement (spec §"interaction" table; Kent's plan 254 D-9 ruling). What
+     * makes a converted upgrade banner leave the screen is the user no longer
+     * matching it — so a conversion that did not refresh the context left the
+     * placement mounted until something else happened to re-resolve it. Kent,
+     * 2026-09-25 (BL-0004): *"Converting should trigger a reloading of UserContext
+     * with the new plan/billing state the user has converted to."*
+     *
+     * Ordering, and why it is this way round:
+     *
+     * 1. The interaction is recorded (analytics + attribution), as before.
+     * 2. **Optimistically**, locally: when the converted output's CTA names a
+     *    target plan (`cta_path.plan_handle`), the held context moves to that plan
+     *    immediately. Billing truth arrives by Stripe webhook, so
+     *    `GET /api/sdk/client-context` can still report the OLD plan for seconds
+     *    after a successful checkout — waiting for it would leave the upgrade
+     *    prompt on screen exactly when the user has just paid.
+     * 3. Subscribers are notified either way — a conversion whose CTA names no
+     *    plan still re-decides mounted slots and re-checks mounted gates, which is
+     *    what turns a plan change the host applied itself into a re-render.
+     * 4. **Then** the server refresh (`fetchClientContext()`), which overlays the
+     *    RevTurbine-authoritative trial / billing-health / plan fields and
+     *    notifies again if it changed anything. It is best-effort and never
+     *    throws, so awaiting it cannot fail a conversion; with no client-session
+     *    minter configured it is a no-op and the optimistic state stands.
+     *
+     * Mounted `PlacementController`s re-decide and mounted `EntitlementGate`s
+     * re-check through their `watchUserContext()` subscriptions — which the React
+     * bindings attach for you. Re-resolution emits the normal lifecycle events
+     * once per final decision; the transient states emit nothing.
+     * `PlacementController.ctaComplete()` is unchanged and remains the
+     * component-level path.
      *
      * @public
      */
     convert(outputId: string): Promise<void>;
+    /**
+     * The BL-0004 post-conversion context reload: optimistic local plan move,
+     * then the server refresh. See {@link convert} for the ordering rationale.
+     */
+    private reloadUserContextAfterConversion;
+    /**
+     * Keep a stale server plan from undoing an optimistic conversion (BL-0004).
+     *
+     * Billing truth arrives by Stripe webhook, so a `client-context` read that
+     * races the webhook reports the PRE-conversion plan — and the server plan
+     * deliberately overlays the app-supplied one (plan 179 TASK-1), so applying
+     * that read verbatim would put the upgrade prompt straight back on screen
+     * seconds after the user paid.
+     *
+     * So while a conversion is pending, a server plan equal to the plan converted
+     * AWAY from is dropped — only the plan fields, never the trial or billing-health
+     * signals, which are authoritative regardless. Any other value (the new plan,
+     * or a third one the user was moved to out-of-band) clears the pending state
+     * and applies, so this can suppress at most the one value it was created for
+     * and cannot outlive the lag it exists to cover.
+     */
+    private dropStalePostConversionPlan;
+    /**
+     * The display name the loaded Playbook gives a plan handle, else the handle.
+     * Keeps an optimistic plan move from putting a raw handle in front of a user
+     * when the Playbook already knows the plan's name.
+     */
+    private planNameForHandle;
     /**
      * Emit a canonical trigger event. There is no in-SDK consumer that matches
      * on trigger names — the shipped behavior is ingest to `events_clickstream`
@@ -22897,12 +23016,41 @@ declare class PlacementController {
     private _awaitingConfig;
     private _configRetries;
     private _playbookUnsubscribe;
+    private _userContextUnsubscribe;
     constructor(sdk: RevTurbineCustomerSdk, options: PlacementControllerOptions);
     /**
-     * Stop listening for Playbook loads. Idempotent; call it when the owning
-     * component unmounts (`usePlacement` does).
+     * Stop listening for Playbook loads and user-context changes. Idempotent; call
+     * it when the owning component unmounts (`usePlacement` does).
      */
     dispose(): void;
+    /**
+     * Drop only the Playbook-load subscription — the within-load-cycle teardown
+     * (BL-0177). A mounted controller keeps watching the user context (BL-0004).
+     */
+    private unsubscribePlaybook;
+    /**
+     * Re-decide whenever the user context changes (BL-0004).
+     *
+     * The counterpart to {@link EntitlementGate.watchUserContext}, and the reason
+     * `sdk.convert()` now removes a converted placement in place: conversion writes
+     * no suppression — eligibility is a function of the user's CURRENT plan and
+     * targeting — so the only thing that can take a converted upgrade banner off
+     * screen is a re-decide against the reloaded context. Without this the
+     * placement stayed mounted until something else happened to re-resolve it, and
+     * the host had to call `refresh()` itself or use the component's
+     * `ctaComplete()` (the limitation plan 236 TASK-13 recorded).
+     *
+     * Only re-decides a controller that has already resolved something: before the
+     * first `load()` there is nothing on screen to be stale, and firing then would
+     * turn every startup `identify()` into a duplicate decision.
+     *
+     * Calls `load()` rather than `refresh()` on purpose — `refresh()` clears
+     * impression/exposure tracking, so a context change would re-credit a
+     * presentation the user never saw again.
+     *
+     * Returns an unsubscribe function; {@link dispose} also drops it.
+     */
+    watchUserContext(): () => void;
     /**
      * Is this decision a race against a Playbook load rather than a verdict?
      *
@@ -23120,12 +23268,18 @@ declare class EntitlementGate {
     private _awaitedResult;
     private _configRetries;
     private _playbookUnsubscribe;
+    private _userContextUnsubscribe;
     constructor(sdk: RevTurbineCustomerSdk, options: EntitlementGateOptions);
     /**
-     * Stop listening for Playbook loads. Idempotent; call it when the owning
-     * component unmounts (`useEntitlement` does).
+     * Stop listening for Playbook loads and user-context changes. Idempotent; call
+     * it when the owning component unmounts (`useEntitlement` does).
      */
     dispose(): void;
+    /**
+     * Drop only the Playbook-load subscription — the within-check-cycle teardown
+     * (BL-0179). A mounted gate keeps watching the user context (BL-0004).
+     */
+    private unsubscribePlaybook;
     /** Current state snapshot. */
     get state(): EntitlementGateState;
     /** Convenience: `true` when the entitlement is allowed. */
@@ -23225,8 +23379,13 @@ declare class EntitlementGate {
      * `check()` there is nothing on screen to be stale, and firing then would
      * turn every `identify()` at startup into a redundant evaluation.
      *
+     * `sdk.convert()` reloads the UserContext (BL-0004), so this is also what
+     * flips a mounted `useCan` gate to allowed after a conversion.
+     *
      * Returns an unsubscribe function. Call it when the gate is discarded —
      * without that, a gate outlives its consumer and keeps re-checking.
+     * Idempotent: a second call returns the first subscription rather than
+     * orphaning it, and {@link dispose} drops it too.
      */
     watchUserContext(): () => void;
     private notify;