@revturbine/sdk 0.11.4 → 0.11.6

package/dist/index.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
@@ -20673,6 +20676,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). */
@@ -21329,6 +21342,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;
@@ -22126,6 +22145,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.
@@ -22148,6 +22191,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.
@@ -22437,12 +22492,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.
      *
@@ -22619,13 +22678,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`
@@ -23089,12 +23208,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?
      *
@@ -23312,12 +23460,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. */
@@ -23417,8 +23571,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;