@revturbine/sdk 0.11.13 → 0.11.17

package/dist/types/web-sdk/customer-side.d.ts

@@ -54,6 +54,22 @@ export type { ServerActionContext, ServerActionHandler, ServerActionMap, ServerA
 export type SdkMetadata = Record<string, JsonValue>;
 /** User-provided traits or custom context (inherently untyped from customer code). */
 export type SdkTraits = Record<string, JsonValue>;
+/**
+ * Top-level keys {@link RevTurbineCustomerSdk.identify} recognizes on a
+ * canonical user-context input. Anything else is dropped and reported
+ * (plan 168 REQ-3, plan 191 REQ-3). `satisfies` guards each entry against
+ * typos; `update-keys-exhaustiveness.test-d.ts` derives the reverse
+ * direction, so an {@link IdentifyContextInput} field identify() does not
+ * merge has to be acknowledged there (BL-0352).
+ */
+declare const RECOGNIZED_IDENTIFY_KEYS: readonly ["account_id", "email", "plan", "plan_handle", "usage", "entitlements", "custom", "personalization"];
+/**
+ * The top-level {@link IdentifyContextInput} keys
+ * {@link RevTurbineCustomerSdk.identify} merges into the held context (the
+ * entries of its recognized-key list). Exported for type-level
+ * exhaustiveness checks; it has no runtime value.
+ */
+export type RecognizedIdentifyKey = (typeof RECOGNIZED_IDENTIFY_KEYS)[number];
 /** Properties attached to analytics events. */
 export type SdkEventProperties = Record<string, JsonValue>;
 export interface RevTurbineSdkProvider {
@@ -187,13 +203,55 @@ import type { RevTurbineComponentType, RevTurbineSurfaceType } from '@revt-eng/c
  * ```
  */
 export type UserContextInput = Omit<UserContext, 'id' | 'tenant_id' | 'user_id' | 'created_at' | 'updated_at'>;
+/**
+ * User-context fields only the server may write, so the browser input types
+ * ({@link IdentifyContextInput}, {@link RevTurbineUserContext} and, through it,
+ * {@link RevTurbineUpdateInput}) omit them, and every browser entry point
+ * (`identify()`, `update()`, `setUserContext()`, the `user` init option)
+ * drops them at runtime for plain-JS callers (BL-0351, BL-0352, BL-0381).
+ *
+ * Trust is by party (D-46): the browser client never asserts these values;
+ * the customer's server may (a server-key user-context write, or a server
+ * SDK's overlay inputs), and RevTurbine's server may enrich them.
+ *
+ * - `seat_type_handle` — the user's seat-type assignment (plan 279, D-36).
+ *   It has exactly two writers: the tenant's backend, through a server-key
+ *   user-context upsert, and RevTurbine's own server-side enrichment in
+ *   hosted mode. It is never accepted from `identify()`, `update()` or any
+ *   credential the browser holds; the control plane resolves the delivered
+ *   `seat_type` / `buyer_role` built-in dimensions from it.
+ * - `activity_score` / `activity_score_computed_at` — computed by the
+ *   control plane's hourly activity-score refresh from the event stream and
+ *   persisted on `user_contexts` (plan 180; targeting-studio-ui.md §4.1,
+ *   Activity State). The browser receives the derived level through the
+ *   `activity_level` built-in dimension, never the score, and never writes
+ *   either field (D-36's principle).
+ * - `builtin_dimensions` — the resolved built-in segment dimensions that
+ *   stamp the reserved `rt_<dimension>` traits (plan 279 PD-3, as amended by
+ *   D-46; BL-0381). The only browser source is the authenticated
+ *   `GET /api/sdk/client-context` delivery, which the SDK merges into its
+ *   held context itself; an app-supplied value would let the browser claim
+ *   any built-in segment (e.g. `rt.subscription_state.paid`).
+ * - `customer_builtin_dimensions` — the customer-set built-in dimension
+ *   values and their per-key `override` pins (D-47; BL-0382). Written only by
+ *   the customer's server through the server-key `POST /api/sdk/user-contexts`
+ *   upsert (server-node `setBuiltinDimensions`); the control plane folds them
+ *   into `builtin_dimensions` before delivery.
+ */
+declare const SERVER_ASSIGNED_USER_CONTEXT_KEYS: readonly ["seat_type_handle", "activity_score", "activity_score_computed_at", "builtin_dimensions", "customer_builtin_dimensions"];
+type ServerAssignedUserContextKey = (typeof SERVER_ASSIGNED_USER_CONTEXT_KEYS)[number];
 /**
  * Input accepted by {@link RevTurbineCustomerSdk.identify} for the canonical
  * user-context shape (plan 191). `plan_handle` is THE plan matching
  * identity — the plan's `unique_handle`; the `plan` object is display
  * metadata (name/price/period) and never participates in matching.
+ *
+ * Server-assigned fields (`seat_type_handle`, `activity_score`,
+ * `activity_score_computed_at`, `builtin_dimensions`) are not accepted here
+ * (plan 279, D-36, D-46; BL-0352, BL-0381); the tenant's backend or
+ * RevTurbine's enrichment writes them.
  */
-export type IdentifyContextInput = Partial<UserContextInput> & {
+export type IdentifyContextInput = Partial<Omit<UserContextInput, ServerAssignedUserContextKey>> & {
     /** THE plan matching identity — the plan's `unique_handle` (e.g. `'pro'`). */
     plan_handle?: string;
 };
@@ -334,7 +392,11 @@ export type RevTurbineGateResult<T> = {
  * `{ plan }`) never clobbers other context. Patchable fields include `plan`,
  * `email`, `account_id`, `entitlements`, `custom`, `personalization`, `trial`,
  * the billing-recovery signals (`payment_failed` / `payment_at_risk`), `tiers`,
- * and `usage`.
+ * app-known experiment assignments (`experiments`, plan 183), and `usage`.
+ * Server-assigned fields (`seat_type_handle`, `activity_score`,
+ * `activity_score_computed_at`, `builtin_dimensions`) are not patchable
+ * (D-36, D-46; BL-0352, BL-0381): built-in dimension values reach the browser
+ * only from the authenticated client-context delivery.
  *
  * `usage` keeps its friendly `Record<string, number>` shape (absolute balances),
  * distinct from the richer per-entry `usage` on {@link RevTurbineUserContext}.
@@ -346,12 +408,21 @@ export type RevTurbineUpdateInput = Omit<RevTurbineUserContext, 'id' | 'usage'>
 /**
  * Runtime mirror of {@link RevTurbineUpdateInput}'s keys — the fields
  * `update()` patches. `satisfies` guards each entry against typos/renames;
- * the aliases test asserts exhaustiveness against the type, so a
- * schema-added context field fails the build until acknowledged here.
- * JS callers' keys outside this set are dropped with a dev warning rather
- * than merged into the context.
+ * `update-keys-exhaustiveness.test-d.ts` (compiled by
+ * `pnpm check:types:exact`) derives the reverse direction, so a
+ * schema-added context field fails the build until it is acknowledged here
+ * or omitted from the browser input types (BL-0352). JS callers' keys
+ * outside this set are dropped with a warning rather than merged into the
+ * context.
+ */
+export declare const RECOGNIZED_UPDATE_KEYS: readonly ["usage", "account_id", "email", "email_type", "plan_handle", "plan", "trial", "payment_failed", "payment_at_risk", "tiers", "entitlements", "instances", "custom", "personalization", "experiments", "derived_config_version", "context_hash", "derived_computed_at"];
+/**
+ * The top-level {@link RevTurbineUpdateInput} keys
+ * {@link RevTurbineCustomerSdk.update} patches (the entries of
+ * {@link RECOGNIZED_UPDATE_KEYS}). Exported for type-level exhaustiveness
+ * checks; it has no runtime value.
  */
-export declare const RECOGNIZED_UPDATE_KEYS: readonly ["usage", "account_id", "email", "email_type", "plan_handle", "plan", "trial", "payment_failed", "payment_at_risk", "tiers", "entitlements", "instances", "custom", "personalization", "derived_config_version", "context_hash", "derived_computed_at"];
+export type RecognizedUpdateKey = (typeof RECOGNIZED_UPDATE_KEYS)[number];
 /** Usage snapshot entry for a usage unit. */
 export interface RevTurbineUsageSnapshotEntry {
     /** Current consumed amount for the usage unit. */
@@ -404,8 +475,27 @@ export type ServerEvaluationHydrationPayload = GeneratedServerEvaluationPayload;
  * `custom` is widened to `Record<string, unknown>` at the SDK boundary
  * for customer convenience; values are narrowed to `TraitValue` when
  * persisted via the API.
- */
-export interface RevTurbineUserContext extends Omit<UserContextInput, 'custom' | 'entitlements' | 'usage' | 'personalization' | 'derived_computed_at' | 'context_hash'> {
+ *
+ * `seat_type_handle` is omitted on purpose (plan 279, D-36). A user's seat
+ * type is assigned only server-side: by the tenant's backend through a
+ * server-key user-context upsert, or by RevTurbine's enrichment in hosted
+ * mode. The browser never writes it, so neither `identify()`, `update()`,
+ * `setUserContext()` nor the `user` init option accepts it. The browser
+ * receives the resolved `seat_type` / `buyer_role` as built-in dimensions
+ * delivered by `GET /api/sdk/client-context` instead. The server-computed
+ * `activity_score` / `activity_score_computed_at` are omitted on the same
+ * principle (BL-0352); the browser receives the derived `activity_level`
+ * dimension.
+ *
+ * `builtin_dimensions` is omitted too (D-46, BL-0381): the browser never
+ * asserts a built-in dimension value. The SDK holds the values
+ * `fetchClientContext` delivers and stamps the reserved `rt_<dimension>`
+ * segment traits from them; read them back through
+ * {@link RevTurbineCustomerSdk.getUserContext getUserContext()}. A plain-JS
+ * caller that passes any of these keys has them dropped and reported at
+ * runtime.
+ */
+export interface RevTurbineUserContext extends Omit<UserContextInput, 'custom' | 'entitlements' | 'usage' | 'personalization' | 'derived_computed_at' | 'context_hash' | ServerAssignedUserContextKey> {
     /** Authenticated user identifier. When undefined, the SDK uses an anonymous ID. */
     id?: string;
     /**
@@ -434,25 +524,6 @@ export interface RevTurbineUserContext extends Omit<UserContextInput, 'custom' |
      * `string | number` when serialized.
      */
     personalization?: SdkTraits;
-    /**
-     * Server-evaluated built-in segment dimensions (plan 279 PD-3), one leaf
-     * per resolved dimension keyed by its dimension key (e.g.
-     * `subscription_state`, `region`) — see the built-in segment resolution
-     * contract in `targeting-studio-ui.md` §4.1 for the full vocabulary.
-     *
-     * `fetchClientContext` delivers this from `GET /api/sdk/client-context`
-     * and merges it the way it merges `plan_handle`: **server values overlay
-     * app-set values**, per leaf. A dimension the server did not evaluate on a
-     * given fetch leaves whatever the app (or a prior fetch) had set for that
-     * leaf untouched; a dimension is simply absent when neither side has ever
-     * set it (unknown is trait absence — plan 255).
-     *
-     * Feeds the reserved `rt_<dimension>` segment traits that built-in
-     * Playbook segments match on — never read or write those trait keys
-     * directly. Set this yourself only to seed `local_only` mode or a
-     * server-side port, which has no client-context fetch of its own.
-     */
-    builtin_dimensions?: UserContextInput['builtin_dimensions'];
 }
 /** Page-level context automatically inferred or manually set. */
 export interface RevTurbinePageContext {
@@ -647,8 +718,26 @@ export interface RevTurbineTelemetryOptions {
     consent?: TelemetryConsent;
 }
 export interface RevTurbineInitOptions {
-    /** Your RevTurbine tenant identifier. */
-    tenantId: string;
+    /**
+     * Your RevTurbine tenant identifier — **optional whenever a
+     * {@link publicKey} is supplied** (BL-0335, `0.11.14`).
+     *
+     * The public key is bound to exactly one tenant, so the control plane
+     * resolves the tenant from the key alone and the SDK reads it back from the
+     * launched Playbook it fetches (the signed manifest's and the Playbook's
+     * `tenant_id`). Passing a tenant id as well is still accepted, but the key
+     * is the sole arbiter of the tenant (D-49): when the key-authenticated
+     * delivery names a different tenant, the SDK warns once per init
+     * (`tenantId <x> does not match the key's tenant <y>; using <y>`) and adopts
+     * the key's tenant. The control plane likewise ignores a mismatching tenant
+     * id (with a server-side warning); it never refuses the request.
+     *
+     * Still required when there is no public key to identify the tenant — a
+     * `local_only` init without `localRuntime.playbook` (with one, the SDK
+     * defaults it to `'local'`), or a server-key (`apiKey`) headless init. The
+     * SDK throws a descriptive error at init when neither is present.
+     */
+    tenantId?: string;
     /**
      // @revturbine-graph configuration:revturbine-sdk-internal:web-sdk/customer-side.ts#RevTurbineInitOptions
      * Your **public key** — the browser credential.
@@ -1091,6 +1180,17 @@ export interface RevTurbineLocalRuntimeOptions {
      * './revturbine.playbook.json'` passes `tsc --strict` directly, no cast
      * needed; the SDK validates the shape at init and fails fast on a malformed
      * artifact.
+     *
+     * Built-in segments (`rt.<dimension>.<value>`) need no definitions in the
+     * file: the SDK adds them at load from RevTurbine's catalogue, with Seat Type
+     * values taken from the Playbook's own `seat_types`. An authored segment
+     * under the reserved `rt.` prefix is ignored.
+     *
+     * The definitions exist, but the values do not come from the app: the
+     * browser never sets built-in dimensions (D-46, BL-0381). They reach the
+     * SDK only from `GET /api/sdk/client-context` (a `clientSession` minter
+     * backed by your server), so without that delivery every built-in segment
+     * fails closed — a chip or rule naming one matches nobody.
      */
     playbook?: ConfigArtifact | UnvalidatedConfigArtifact;
     /**
@@ -1531,6 +1631,101 @@ export type RevTurbineTriggerPayload = TrialTriggerPayload | UsageTriggerPayload
  */
 export declare function createSemanticEvent(eventType: string, payload: SdkEventProperties, options?: RevTurbineEventOptions): RevTurbineSemanticEvent;
 export type { RevTurbineEventEnvelope } from '@revt-eng/core';
+/**
+ * The Stripe Checkout `revturbine_*` metadata bag for a rendered output
+ * (plan 282 REQ-5; research §6.2). String-valued and Stripe-shaped: spread it
+ * into a Checkout Session's `metadata` and `subscription_data.metadata` as-is.
+ *
+ * A key the SDK does not hold is ABSENT, never empty or a placeholder — Stripe
+ * reads an empty metadata value as an unset, and an invented id would be worse
+ * than a gap on the attribution side.
+ */
+export interface RevTurbineCheckoutMetadataBag {
+    /** `PlacementOutput.output_id` — the rendered payload / treatment. */
+    revturbine_output_id: string;
+    /** The placement whose CTA led to checkout — what confirms credit to it. */
+    revturbine_placement_id: string;
+    /**
+     * The id `identify()` set, as this SDK's own telemetry carries it: an
+     * email-shaped id is hashed the same way on every lane, so the purchase
+     * joins the presentation and click rows. Absent for an unidentified user.
+     */
+    revturbine_user_id?: string;
+    /**
+     * The identified account, redacted like the wire lanes. Absent when none was
+     * identified — never the user-derived fallback the interaction lane labels.
+     */
+    revturbine_account_id?: string;
+    /** `PlacementOutput.decision_id`. */
+    revturbine_decision_id?: string;
+    /** `PlacementOutput.rule_id` — the rule handle the interaction lanes stamp as `rule_handle`. */
+    revturbine_rule_id?: string;
+    /** The plan the CTA converts onto (`cta_path.plan_handle`), when it names one. */
+    revturbine_plan_handle?: string;
+}
+/**
+ * What {@link RevTurbineCustomerSdk.checkoutMetadata} returns: the bag to put
+ * on the Checkout Session and its subscription, plus Stripe's own caller-side
+ * session key.
+ */
+export interface RevTurbineCheckoutMetadata {
+    /**
+     * The user id, for the session's `client_reference_id` — Stripe's native
+     * caller-side key, which RevTurbine's identity bridge also reads. The same
+     * value as `metadata.revturbine_user_id`; absent for an unidentified user.
+     */
+    client_reference_id?: string;
+    /** Pass as BOTH `metadata` and `subscription_data.metadata`. */
+    metadata: RevTurbineCheckoutMetadataBag;
+}
+/**
+ * The decision context a treatment interaction joins on (plan 282 TASK-9),
+ * accepted alongside {@link RevTurbineTreatmentInteractionInput} by
+ * {@link RevTurbineCustomerSdk.trackTreatmentInteraction}. Both optional: a
+ * caller that supplies neither sends exactly the interaction it sent before,
+ * and the SDK fills them from its own output index when `payloadId` names an
+ * output this SDK decided.
+ */
+export interface RevTurbineTreatmentInteractionDecisionContext {
+    /**
+     * `PlacementOutput.decision_id` → wire `decision_id`, the key the
+     * presentation row, the clickstream and the Checkout metadata bag
+     * (`revturbine_decision_id`) share. Wins over the plan-144
+     * `metadata.decision_id` convention when both are given.
+     */
+    decisionId?: string;
+    /**
+     * The segment handles the user was in when the treatment was presented →
+     * wire `segment_handles`, the analytics join key. Handles, never minted
+     * ids: the SDK's effective set comes from scaffold's `evaluateSegments`
+     * plus any hosted-resolved slugs. `[]` is a real observation (segments
+     * resolved, none matched); omit it when no decision was in scope.
+     */
+    segmentHandles?: readonly string[];
+    /**
+     * Minted segment ids a hosted context supplied → wire `segment_ids`.
+     * Telemetry only, never the join key, and never the evaluated handles;
+     * omit it in local mode.
+     */
+    segmentIds?: readonly string[];
+}
+/** The full input {@link RevTurbineCustomerSdk.trackTreatmentInteraction} accepts. */
+export type RevTurbineTreatmentInteractionRequest = RevTurbineTreatmentInteractionInput & RevTurbineTreatmentInteractionDecisionContext;
+/**
+ * CTA actions that open a plan picker or pricing page rather than checkout
+ * itself. A `cta_clicked` on an output whose CTA is one of these emits
+ * `checkout_started` (plan 282 TASK-8/9) — the step between the click and
+ * checkout, so the placement chain can hold
+ * `success ≤ checkout_started ≤ clicked ≤ presented`.
+ *
+ * `open_checkout_modal` opens checkout directly ("on click") and is
+ * deliberately NOT listed: that placement has no separate step, so its started
+ * count equals its clicked count. `open_upgrade_modal` opens another placement
+ * whose own CTA then decides which of the two it is, so it is not listed
+ * either. `view_plans` is the authored alias the local resolver normalizes to
+ * `navigate_to_plans`; it is kept for an output built by hand.
+ */
+export declare const CHECKOUT_STARTED_CTA_ACTION_TYPES: readonly string[];
 /**
  * Every event name on the taxonomy's `control_plane` surface — emitted via
  * {@link RevTurbineCustomerSdk.trackControlPlaneEvent}, never the platform
@@ -1586,7 +1781,21 @@ export declare const EMITTABLE_PLATFORM_EVENT_NAMES: readonly string[];
  * ```
  */
 export declare class RevTurbineCustomerSdk {
-    private readonly tenantId;
+    /**
+     * The tenant the integration passed at init, if any. Optional since BL-0335:
+     * with a public key the tenant is read from the launched Playbook instead —
+     * see the `tenantId` getter.
+     */
+    private readonly configuredTenantId?;
+    /**
+     * Stable namespace for everything the SDK keys LOCALLY — storage keys,
+     * cache/cap keys, generated placement ids. It is the configured tenant id
+     * when one was passed (so existing integrations keep every persisted key
+     * byte-for-byte), else a hash of the public key. It never changes during a
+     * session, unlike `tenantId`, which a key-only integration learns only once
+     * the Playbook loads.
+     */
+    private readonly tenantNamespace;
     /** The browser credential — `publicKey`, the only name it arrives under. */
     private readonly publicKey;
     /**
@@ -1678,6 +1887,23 @@ export declare class RevTurbineCustomerSdk {
      * segment cuts read as-of-event truth instead of requiring a config join.
      */
     private lastEffectiveSegmentIds;
+    /**
+     * The effective segment HANDLES at the last resolution — the provider
+     * context's `segmentSlugs`: scaffold's `evaluateSegments` output plus any
+     * hosted-resolved slugs. The analytics join key the interaction lane sends
+     * as `segment_handles` (plan 282 TASK-9; Kent, 2026-09-29). Kept apart from
+     * `lastEffectiveSegmentIds`, which mixes minted ids into those handles and
+     * stamps the envelope's legacy `segment_ids` (BL-0462 owns that name).
+     */
+    private lastEffectiveSegmentHandles;
+    /**
+     * The minted segment ids a hosted context supplied at the last resolution
+     * (`resolved.segments.segmentIds`) and nothing else — never the evaluated
+     * handles. Telemetry only, sent as the interaction lane's `segment_ids`;
+     * `undefined` when no hosted context supplied any, so local mode omits the
+     * key entirely.
+     */
+    private lastHostedSegmentIds?;
     private pageContext;
     /**
      * Secure per-user client token (`rt_client_`, plan 157). Minted by the
@@ -1718,7 +1944,25 @@ export declare class RevTurbineCustomerSdk {
     private localPlacementsByLookupKey;
     private localEntitlementsByHandle;
     private localUserContextsByUserId;
+    /**
+     * The SDK-held trial status — written ONLY by the server-delivered /
+     * SDK-derived sources (`localRuntime.initialData.trialStatus`, `hydrate()`,
+     * `getTrialStatus()`, `setTrialInstances()`), always through
+     * {@link writeTrialStatus}. Readers never read it directly: they read
+     * {@link resolveTrialView}, which weighs it against the app-supplied
+     * `userContext.trial` (BL-0403).
+     */
     private localTrialStatus;
+    /**
+     * Trial write clock (BL-0403). Each source of trial state stamps the next
+     * tick when it changes the trial; {@link resolveTrialView} picks the
+     * source with the later stamp. `0` = that source has never written.
+     */
+    private trialWriteClock;
+    /** Tick of the last {@link localTrialStatus} write; `0` = never supplied. */
+    private trialStatusWrittenAt;
+    /** Tick of the last change to `userContext.trial`; `0` = never supplied. */
+    private contextTrialWrittenAt;
     private readonly presentationCapsByKey;
     private readonly usageLimitByEntitlement;
     private readonly usageTokenPrefixByEntitlement;
@@ -1744,6 +1988,21 @@ export declare class RevTurbineCustomerSdk {
     readonly impressionHistory: ImpressionHistory;
     constructor(options: RevTurbineInitOptions);
     private isLocalOnlyMode;
+    /**
+     * The tenant this SDK operates in: the key's tenant once a key-authenticated
+     * delivery named one that differs from the configured `tenantId` (D-49),
+     * else the configured `tenantId`, else the one the Playbook delivery named
+     * (BL-0335). `undefined` only between init and the first Playbook load of a
+     * key-only integration.
+     */
+    private get tenantId();
+    /**
+     * The tenant header for the SDK's direct control-plane calls: sent only when
+     * the integration CONFIGURED a tenant id — and then the key's tenant once it
+     * was adopted (D-49). The control plane ignores a mismatching value with a
+     * warning. A key-only integration sends none — the key names the tenant.
+     */
+    private tenantHeader;
     private resolveConfigProvider;
     private refreshPlaybookSnapshot;
     /**
@@ -1821,6 +2080,103 @@ export declare class RevTurbineCustomerSdk {
      * checkEntitlement contract.
      */
     private getOrBuildPlacementResolver;
+    /**
+     * The single usage view placements read (BL-0402): one entry per
+     * entitlement handle the SDK holds usage for, in the
+     * `EntitlementProviderState.usage` shape the shared threshold gate
+     * (`matchesThresholdTrigger`) and the placement token derivation consume.
+     *
+     * - **Which handles** — every object entry on `userContext.usage` (in
+     *   context order, so the first-entry shorthand tokens are unchanged), then
+     *   every handle reported only through `update({ usage })` /
+     *   `updateUsage()` / `identify(…, { usage })`.
+     * - **`used`** — the app-reported balance (`usageBalances`, the most recent
+     *   write) wins; else the context entry's `amount`; else `0`. This is the
+     *   precedence `getUsage()` and `can()` already apply, so the meter, the
+     *   gate, and the placement agree.
+     * - **`limit`** — the context entry's own `limit` wins; else the limit
+     *   `getUsage()` reports for the handle (the Playbook allowance for the
+     *   user's CURRENT plan: the plan-scoped `usage_limit` rule's `limit_value`
+     *   or `credits` rule's `allowance_value`); else `0`. `0` means "no
+     *   usable limit" (an `unlimited` or absent allowance): the threshold gate
+     *   fails closed on it, so no threshold placement fires.
+     * - **`remaining`** — `max(0, limit − used)` when a limit is known, else `0`.
+     */
+    private resolveUsageView;
+    /**
+     * The single trial view every trial reader shares (BL-0403): the placement
+     * resolver's `__providers.plan.trial*` fields (and so `trial_started` /
+     * `trial_progress` / `trial_ending` / `trial_ended` / `trial_converted`
+     * gating and the `{{trial_days_*}}` tokens), reverse-trial entitlement
+     * grants, and a `local_only` `getTrialStatus()` with no resolver.
+     *
+     * Two sources hold trial state:
+     *
+     * - **the user context's `trial`** — what the app supplies (`user.trial` at
+     *   init, `update({ trial })`, `setUserContext`, a server action's
+     *   `userContext` result) plus the authenticated client-context delivery,
+     *   which merges its trial into the same field;
+     * - **the SDK trial status** — `localRuntime.initialData.trialStatus`,
+     *   `hydrate()`'s `trial_status`, `getTrialStatus()`, `setTrialInstances()`.
+     *
+     * **Precedence: the most recent change wins** — the same rule the usage view
+     * applies to reported balances ({@link resolveUsageView}). A server-delivered
+     * or hydrated status therefore wins when it was supplied after the app's
+     * trial; an app `update({ trial })` made after it wins over it. A write that
+     * leaves the context trial unchanged is not a newer write, so re-sending the
+     * same trial every render never displaces a fresher server status. A source
+     * never supplied does not compete: with no SDK status, the context trial is
+     * used; with no context trial (or after it is cleared), the SDK status is.
+     */
+    private resolveTrialView;
+    /**
+     * Write the SDK trial status (server-delivered / SDK-derived — see
+     * {@link resolveTrialView}) and stamp it as the newest trial write.
+     */
+    private writeTrialStatus;
+    /**
+     * Forget the SDK-held trial state of the current user (BL-0417): the SDK
+     * trial status, both {@link resolveTrialView} source markers, and the
+     * lifecycle stage {@link evaluateTrialLifecycleTriggers} dedupes on — so the
+     * next user starts with no trial, and a trial-less next user is not read as
+     * "the trial just ended" (`trial_expired`). The context `trial` is cleared by
+     * the caller along with the rest of the user context.
+     */
+    private clearTrialState;
+    /**
+     * Whether `nextUserId` names a DIFFERENT identified user than the one the
+     * SDK currently holds (BL-0417). Anonymous → identified is not a switch: the
+     * anonymous visitor becomes that user, so what they accumulated is kept.
+     */
+    private isIdentifiedUserSwitch;
+    /**
+     * Drop the previous user's trial and usage state on a switch to a different
+     * identified user without an intervening reset (BL-0417): the SDK trial
+     * status and markers, the context `trial`, the reported usage balances and
+     * the context `usage`. Both feed decisions directly — the trial view and
+     * the usage view — so carrying them across the merge would decide the new
+     * user's trial placements, reverse-trial grants, `{{trial_days_*}}` /
+     * `{{usage_*}}` tokens and usage thresholds from the old user's state.
+     * The new identity's own values are merged in afterwards by the caller.
+     */
+    private dropPreviousUserTrialAndUsage;
+    /**
+     * Run the trial lifecycle evaluation against the resolved trial view
+     * (BL-0417). Called after every change that can move the view — the app's
+     * context trial (`user.trial` at init, `update({ trial })`,
+     * `setUserContext`, a server action's context, the client-context
+     * delivery), `hydrate()`, a reset or user switch, and a Playbook load that
+     * enables the triggers — so `trial_midpoint` / `trial_expiring` /
+     * `trial_expired` fire whichever source supplied the trial.
+     *
+     * The dedupe is the evaluator's own: a stage fires only when it differs
+     * from the last stage seen, so re-evaluating an unchanged view — or both
+     * sources reporting the same threshold — never fires twice. While the
+     * triggers are off (no Playbook loaded yet, or none authoring a `trials`
+     * placement) nothing is evaluated or recorded, so a trial supplied before
+     * the Playbook loads still fires once it does.
+     */
+    private syncTrialLifecycleWithView;
     /**
      * Build a minimal provider context from the SDK's user state when no
      * explicit domain providers are registered.  This allows the local
@@ -2042,12 +2398,46 @@ export declare class RevTurbineCustomerSdk {
      *
      * 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.
+     * host app — is the only thing that can fill them in.
+     *
+     * The usage family (`{{usage_current}}` / `{{usage_limit}}` /
+     * `{{usage_remaining}}` / `{{usage_percent}}` and their `<unit>_usage_*`
+     * forms) is filled here too, from the SAME provider usage view the
+     * threshold gate decided the placement with (BL-0402) — see
+     * {@link usageContentTokens}. So are `{{trial_days_remaining}}` and
+     * `{{trial_days_total}}`, from the same provider trial state the trial
+     * trigger gate read (BL-0403) — see {@link trialContentTokens}. Every other
+     * token in the studio table (seats) is resolved on the React render lane by
+     * `derivePlacementPersonalizationTokens`, which unknown tokens pass through
+     * untouched.
      */
     private derivedContentTokens;
+    /**
+     * Trial personalization tokens for decision content (BL-0403), read from the
+     * provider plan state the placement was decided against — the synthesized
+     * {@link resolveTrialView} projection unless a registered plan provider
+     * supplies its own. Mirrors `derivePlacementPersonalizationTokens`: each
+     * token is filled only when its value is a finite number, so an unknown
+     * trial length leaves the token untouched rather than rendering `0`.
+     */
+    private trialContentTokens;
+    /**
+     * Usage personalization tokens for decision content, read from the provider
+     * usage view the placement was decided against (BL-0402) — the synthesized
+     * {@link resolveUsageView} unless a registered entitlements provider
+     * supplies its own.
+     *
+     * Per entitlement: `<unit>_usage_current` always; `<unit>_usage_limit`,
+     * `<unit>_usage_remaining` and `<unit>_usage_percent` only when a positive
+     * limit is known (an unknown or unlimited allowance leaves those tokens
+     * untouched rather than rendering a misleading `0`). The unit prefix and the
+     * choice of entitlement for the unprefixed `usage_*` shorthand (and its
+     * `current_usage` / `current_limit` / `remaining_usage` aliases) follow
+     * `getPersonalizationTokens()`: handles in sorted order, the `core` unit
+     * first, else the first with a limit, else the first. Percent is rounded and
+     * capped at 100, as it is there.
+     */
+    private usageContentTokens;
     /**
      * Substitute the SDK-resolved plan/price/recommendation tokens into a
      * decision's content.
@@ -2417,9 +2807,19 @@ export declare class RevTurbineCustomerSdk {
      * upsert; an omitted field never clobbers a previously-set value. See the
      * advertised {@link update} alias for the full recognized-field contract.
      *
+     * Server-assigned fields (`seat_type_handle`, `activity_score`,
+     * `activity_score_computed_at`) are dropped and reported, never merged:
+     * they are written only by the tenant's backend or RevTurbine's
+     * enrichment (D-36, BL-0352). The parameter type does not yet reject other
+     * undeclared keys the way {@link identify} and {@link update} do; that
+     * `Exact<>` narrowing is deferred to `0.12.0` because it can break callers
+     * that pass a wider object today.
+     *
      * @public
      */
     setUserContext(userContext: RevTurbineUserContext): void;
+    /** {@link setUserContext}'s merge, on a patch already cleared of server-assigned keys. */
+    private mergeAcceptedUserContext;
     /**
      * Subscribe to user-context changes — `identify()`, `setUserContext()`,
      * `update()`, `updateUsage()`, and `resetIdentity()` (plan 194 REQ-3).
@@ -2721,9 +3121,21 @@ export declare class RevTurbineCustomerSdk {
      * lower-level counterpart to {@link dismiss}/{@link snooze}/{@link convert},
      * which key off a decision's `output_id` instead.
      *
+     * `decisionId`, `segmentHandles` and `segmentIds` (plan 282 TASK-9) ride
+     * the interaction onto the wire as `decision_id` / `segment_handles` /
+     * `segment_ids`. All optional: given, they win; otherwise the SDK fills
+     * them from the output it indexed for `payloadId` (`segment_ids` only when
+     * a hosted context supplied minted ids — never in local mode); a caller
+     * that supplies none and names no indexed output sends exactly what it
+     * sent before.
+     *
+     * A `cta_clicked` on an indexed output whose CTA opens a plan picker or
+     * pricing page ({@link CHECKOUT_STARTED_CTA_ACTION_TYPES}) also emits
+     * `checkout_started` — never for a CTA that opens checkout directly.
+     *
      * @public
      */
-    trackTreatmentInteraction(input: RevTurbineTreatmentInteractionInput): Promise<void>;
+    trackTreatmentInteraction(input: RevTurbineTreatmentInteractionRequest): Promise<void>;
     getPlacementContent(placementId: string, request?: JsonObject): Promise<RevTurbinePlacementContent>;
     /**
      * Report user-context keys the SDK does not recognize, then let the caller
@@ -2773,6 +3185,15 @@ export declare class RevTurbineCustomerSdk {
        */
     private rejectLegacyPlanId;
     private reportUnrecognizedContextKeys;
+    /**
+     * Report server-assigned keys a browser entry point dropped (D-36,
+     * BL-0351, BL-0352). Same once-per-session dedupe and anonymous
+     * `sdk_validation_warning` lane as {@link reportUnrecognizedContextKeys},
+     * with guidance that names the actual writer instead of pointing the caller
+     * at `custom` — moving a server-assigned value under `custom` would not make
+     * it any less browser-supplied.
+     */
+    private reportServerAssignedContextKeys;
     private normalizePlacementOutput;
     private validateTrialStatusShape;
     /**
@@ -2841,10 +3262,21 @@ export declare class RevTurbineCustomerSdk {
      * window, which trains people to ignore the warning.
      */
     private reportUnmatchedUsageKeys;
+    /**
+     * `getUserContext()`'s `trial` (BL-0417): the resolved trial view, copied,
+     * or nothing when neither trial source was ever supplied (the SDK's
+     * `{ in_trial: false }` default is not a fact about the user).
+     */
+    private userContextTrialProjection;
     /**
      * Build the full persistence-ready {@link UserContext} from the current
      * SDK state. Includes `tenant_id` and `user_id` required for API storage.
      *
+     * Also projects the decision-driving fields — `trial` (the resolved trial
+     * view), `tiers`, `payment_failed`, `payment_at_risk` and `instances` —
+     * when held. The snapshot is a copy: changing it changes nothing in the SDK;
+     * write through `update()` / `setUserContext()`.
+     *
      * @public
      */
     getUserContext(): UserContext;
@@ -3132,6 +3564,36 @@ export declare class RevTurbineCustomerSdk {
     private warnOnUiPathResolverCoverageGaps;
     /** Route output-addressed callbacks through the canonical interaction/analytics path. */
     private trackOutputInteraction;
+    /**
+     * The Stripe Checkout `revturbine_*` metadata bag for a rendered output
+     * (plan 282 REQ-5; research §6.2), keyed by the `output_id` of a decision
+     * this SDK produced — what the customer's server passes when it creates the
+     * Checkout Session the output's CTA leads to.
+     *
+     * Pass `metadata` as the session's `metadata` AND as
+     * `subscription_data.metadata`. The session copy is what
+     * `checkout.session.completed` carries; the subscription copy is what every
+     * later `customer.subscription.*` event carries and what each invoice
+     * snapshots under `parent.subscription_details.metadata`, so renewals,
+     * failures and recoveries stay attributable without a `customers` row. Pass
+     * `client_reference_id` as the session's `client_reference_id`, Stripe's own
+     * caller-side key, which the identity bridge also reads as the user id.
+     *
+     * Checkout cannot set Customer metadata inline: if you let Checkout create
+     * the Customer, follow up with `customers.update({ metadata })` — see the
+     * billing guide.
+     *
+     * Every value is one this SDK holds; nothing is minted. The user id is the
+     * one `identify()` set, as this SDK's own telemetry carries it (an
+     * email-shaped id is hashed the same way on every lane, so the purchase
+     * joins the click). The account id is present only when an account was
+     * identified — never the user-derived fallback. A key the SDK does not hold
+     * is absent, not empty.
+     *
+     * @returns `null` when no decision from this SDK produced `outputId`.
+     * @public
+     */
+    checkoutMetadata(outputId: string): RevTurbineCheckoutMetadata | null;
     /**
      * Suppress a decision's placement for its authored dismiss cooldown.
      * Terminal for the window: `getPlacementDecision` will not return it again