@revturbine/sdk 0.11.12 → 0.11.16

package/CHANGELOG.md

@@ -47,6 +47,554 @@ also require a changelog entry.
 
 ---
 
+## 0.11.16
+
+### Build fix, part two: the npm declaration build resolves `openapi-fetch` too (no API change)
+
+**What changed.** 0.11.15 fixed the bundle step, but the public npm publish
+then failed one command later, in the declaration emit
+(`tsc -p tsconfig.build.json`). It reported
+`../server-node/client.ts(29,43): error TS2307: Cannot find module 'openapi-fetch'`,
+for the same reason as before: TypeScript resolves the bare import by walking
+up from `server-node/`, and the public repo installs the package only under
+`web-sdk/`. `web-sdk/tsconfig.build.json` now maps `openapi-fetch` to
+`./node_modules/openapi-fetch`.
+
+**npm users:** the 0.11.14 changes first reach npm in 0.11.16. Neither 0.11.14
+nor 0.11.15 was published to npm (both are on GitHub Packages, PyPI and
+crates.io). There is no behavior change across 0.11.14 through 0.11.16.
+
+**Landed in:** 0.11.16.
+**Fail-closed in:** n/a (build only).
+**Proving test:** the public repo's `release-npm.yml` build step for
+`v0.11.16`. It was reproduced locally by hiding the root `openapi-fetch` link
+to match the public layout: the declaration emit failed with the same TS2307
+before this change, and tsup, the declaration emit and rollup dts all pass
+after it.
+
+## 0.11.15
+
+### Build fix: the npm package publishes again (no API change)
+
+**What changed.** 0.11.14 was published to GitHub Packages, PyPI and
+crates.io, but the public npm publish of `@revturbine/sdk` failed at the bundle
+step: `Could not resolve "openapi-fetch"` from `server-node/client.ts`, which
+the `headless` entry re-exports. `openapi-fetch` has been bundled since BL-0354
+(0.11.14 was the first release to carry it). A bare import resolves by walking
+up from the importing file, so from `server-node/` it never reached
+`web-sdk/node_modules`, which is the only place the public repo installs it.
+`web-sdk/tsup.config.ts` now gives esbuild `web-sdk/node_modules` as a fallback
+`nodePaths` entry, so every file the SDK bundles resolves the SDK's own
+dependencies.
+
+**npm users:** everything listed under 0.11.14 below first reaches npm in
+0.11.15. There is no behavior change between 0.11.14 and 0.11.15. PyPI and
+crates.io get 0.11.15 in lockstep, with no change.
+
+**Landed in:** 0.11.15.
+**Fail-closed in:** n/a (build only).
+**Proving test:** the public repo's `release-npm.yml` bundle step (tsup +
+declarations) for `v0.11.15`. Locally, `web-sdk/tsup.config.ts` builds the
+bundle, and an esbuild probe confirms `nodePaths` resolves a bare import from a
+sibling directory that has no `node_modules` of its own.
+
+## 0.11.14
+
+This release carries the BL-0335 change below plus every entry that main held
+under "Unreleased" since 0.11.13 (BL-0381, BL-0382, BL-0366, BL-0375, BL-0369,
+BL-0352, BL-0354 and BL-0351).
+
+### `tenantId` is optional on a browser init with a `publicKey`; the key is the sole arbiter of the tenant (BL-0335, D-49)
+
+**What changed.** Before, a browser init needed both a `tenantId` and a
+`publicKey`. The public key is bound to exactly one tenant, and the control
+plane already resolved the tenant from the key alone, so the id was redundant
+configuration, and a wrong one was silently ignored. Now:
+
+- `RevTurbineInitOptions.tenantId` is **optional**. The minimal hosted init is
+  `{ publicKey, endpoint }`.
+- A key-only integration sends **no** `x-tenant-id`. It reads the tenant from
+  the key-authenticated Playbook delivery: the signed manifest's `tenant_id`
+  and the Playbook's own `tenant_id`. Until the first Playbook loads, the
+  tenant is unknown, so `getUserContext().tenant_id` and the event envelope's
+  `tenant_id` read `''` and the `/api/track` row omits `tenant_id`. The
+  control plane stamps the key's tenant regardless.
+- A **configured** `tenantId` that matches the key's tenant behaves exactly as
+  before: it is still sent, and every locally persisted key (anonymous id,
+  decision cache, caps, interaction state) is unchanged.
+- A **configured** `tenantId` that does **not** match the key's tenant is no
+  longer silently ignored, and it is not refused either (D-49). When the
+  key-authenticated delivery names another tenant, the SDK logs one warning
+  per init and adopts the key's tenant:
+
+  ```
+  [RevTurbine] tenantId <configured> does not match the key's tenant <key tenant>; using <key tenant>
+  ```
+
+  The signed manifest is activated (before, a manifest whose tenant differed
+  from the configured one was refused and the SDK fell back to the legacy
+  config fetch). After adoption, `getUserContext().tenant_id`, event envelopes
+  and the `x-tenant-id` the SDK still sends all carry the key's tenant. Local
+  storage keys stay namespaced by the configured id, so nothing persisted is
+  lost.
+- A key-only integration keys local state by a short hash of the public key
+  (`revturbine:pk-…:`), so rotating the key starts a fresh local namespace,
+  just as changing `tenantId` always did.
+- The theme loader (`fetchThemeOverride`) no longer sends the `'local'`
+  placeholder as a tenant header. `ThemeLoaderOptions.tenantId` is optional,
+  and the new `storageScope` option keeps the persisted-theme key.
+- `ConfigTargetDefaults.tenantId` is optional. Without it, the artifact's own
+  `tenant_id` is used.
+- Init now fails loudly when no tenant can be identified. It throws when
+  neither `publicKey` nor `tenantId` is present, and when a `local_only` init
+  has no `tenantId` and no `localRuntime.playbook`. With a local Playbook,
+  `local_only` still defaults the tenant to `'local'`, and a local Playbook's
+  `tenant_id` stays a guard behind the init option (plan 233 REQ-2): there is
+  no key there to arbitrate.
+
+**Server side (web #927).** The control plane uses the key's tenant
+unconditionally on every public-key lane. A tenant id that IS sent, whether as
+a header or as `tenant_id` in an event or interaction body, is diagnostic only:
+a mismatch is logged server-side and ignored. No request is refused for it.
+
+**Landed in:** 0.11.14 (`web-sdk` only; `server-python`/`server-rust` bumped
+in lockstep with no behavior change: the server ports authenticate with the
+server key and build a per-request context with a `tenant_id`, and they have
+no browser `publicKey` init option to relax).
+**Fail-closed in:** 0.11.14. An init with no identifiable tenant throws;
+before, it was a type error only, and JS callers got `undefined`. A mismatching
+configured tenant warns from 0.11.14; before, it was silent.
+**Proving test:**
+- `web-sdk/customer-side-tenant-optional.test.ts`: key-only init on both
+  delivery lanes (no tenant header; tenant adopted from the manifest and
+  Playbook), configured matching tenant unchanged (header sent, storage keys
+  byte-identical), a mismatching configured tenant warned once and the key's
+  tenant adopted on both lanes, the key-hash namespace, the init guards, and
+  the theme loader.
+- `web-sdk/init-options-exactness.test-d.ts`: a key-only init compiles.
+
+### server-node `setBuiltinDimensions()` — your backend sets built-in dimension values, with an `override` flag (BL-0382, rulings D-46 / D-47)
+
+**What changed.** Additive. The customer's backend can now SET built-in
+segment dimension values for a user, not just read the control plane's
+(D-46: "the customer's backend calling revturbine to set the dimension").
+
+- **server-node** — `RevTurbineServer.setBuiltinDimensions(userId, dimensions,
+  { override })` calls the widened `upsertServerUserContext`
+  (`POST /api/sdk/user-contexts`) with `{ user_id, builtin_dimensions,
+  override }` and the server key. Settable: `subscription_state`,
+  `trial_type`, `billing_health`, `activity_level`, `buyer_role`,
+  `email_type`, `region`, `device_type` (typed as
+  `ServerBuiltinDimensionsWrite`, each a closed vocabulary; `null` clears a
+  dimension). `seat_type` stays `assignSeatType`. It resolves to the stored
+  state — `seat_type_handle`, the customer-set `builtin_dimensions`, the
+  pinned `overrides`, `updated_at`. A refusal throws the new
+  `RevTurbineDimensionWriteError` (`status`, `requestId`, machine `code`,
+  typed `reason`: `invalid_request` / `unauthorized` / `forbidden` /
+  `unknown_dimension_value` / `request_failed`); it never carries the key.
+- **`override` (D-47).** `false` (default) is an UPDATE: the value is delivered
+  until a newer RevTurbine enrichment change supersedes it (last writer wins,
+  enrichment included), and writing a pinned dimension without the flag
+  unpins it. `true` is an OVERRIDE: the dimension is pinned and enrichment
+  never replaces it until you write it again without the flag or clear it.
+  The control plane applies this before delivery, so the browser SDK's client
+  context and `getBuiltinDimensions()` both return the result; the SDK
+  delivery rule and the parity goldens are unchanged.
+- **`assignSeatType(userId, handle, { builtinDimensions, override })`** can
+  write dimension values in the same upsert. Its `SeatAssignmentErrorReason`
+  gains `unknown_dimension_value` (a 422 with code `UNKNOWN_DIMENSION_VALUE`).
+  Its response now also carries `builtin_dimensions` and `overrides`.
+- **Python and Rust get no HTTP client** (unchanged: neither port has a
+  server-key transport). A backend on those stacks calls the endpoint itself.
+- Browser input types are untouched: `builtin_dimensions` is never a browser
+  write path.
+
+The `@revt-eng/*` pins move to `0.1.374`, which widens the operation
+(scaffold #431).
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** n/a (additive).
+**Proving test:** `tests/server-node-set-builtin-dimensions.test.ts`,
+`tests/server-node-assign-seat-type.test.ts`.
+
+### Behaviour change: the browser SDK ignores app-set `builtin_dimensions` (BL-0381, ruling D-46)
+
+**What changed.** Trust in a built-in dimension value is decided by *party*
+(Kent, D-46): the browser client never asserts one, the customer's server may,
+and RevTurbine's own enrichment is optional. `builtin_dimensions` therefore
+joins `seat_type_handle`, `activity_score` and `activity_score_computed_at`
+as a server-assigned key in the browser SDK.
+
+- **Types.** `builtin_dimensions` is omitted from `RevTurbineUserContext`,
+  `RevTurbineUpdateInput` and `IdentifyContextInput`, so
+  `update({ builtin_dimensions })`, `setUserContext({ builtin_dimensions })`,
+  `identify(id, { builtin_dimensions })` and `user: { builtin_dimensions }`
+  no longer compile.
+- **Runtime.** Every browser entry point drops the key and warns with the
+  server-assigned diagnostic (`update()`, `identify()`, `setUserContext()`,
+  the `user` init option). A persisted `local_only` state blob that carries it
+  is purged on restore, and a server-action result that echoes it is stripped
+  silently. Before this change, 0.11.12 and 0.11.13 merged an app-set value
+  through `setUserContext()` and the `user` option. An app could then claim
+  any built-in segment (for example `rt.subscription_state.paid`) from the
+  browser.
+- **The one browser source** is the authenticated
+  `GET /api/sdk/client-context` delivery (`fetchClientContext`, or a
+  `clientSession` minter). Its values overlay per leaf exactly as before.
+  `getUserContext()` still returns the held value.
+- **`local_only`.** Built-in segment *definitions* are still synthesized for
+  a local Playbook (BL-0365), so chips and rules naming `rt.*` segments stay
+  valid. Their *values* no longer come from the app: **a browser `local_only`
+  app can no longer target built-ins unless a server-provided context
+  delivers them.** With no delivery every `rt_*` trait is absent and the
+  built-in segments fail closed (PD-4). `rt.registration_state.*` still
+  resolves from the identified id alone.
+- **Unchanged: server SDKs.** They are the customer's server. Their overlay
+  inputs stay: server-node's `createStaticProviders({ userContext:
+  { builtin_dimensions }, serverBuiltinDimensions })`, Python's
+  `builtin_dimensions` / `server_builtin_dimensions` and Rust's
+  `builtin_dimensions` / `server_builtin_dimensions`. Parity goldens are
+  unchanged.
+
+This supersedes the part of BL-0352 (below) that made `update()` apply
+`builtin_dimensions`. That change never shipped.
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** the same release. The compile-time omission and the
+runtime drop ship together.
+**Proving test:**
+- `web-sdk/update-keys-exhaustiveness.test-d.ts` (`pnpm check:types:exact`):
+  `builtin_dimensions` is in the server-assigned set.
+- `web-sdk/identify-guardrails.test.ts`: describe block
+  `builtin_dimensions never enters the browser context from the app`.
+- `web-sdk/local-builtin-segments.test.ts`: `chip … with app-set … fails
+  closed` (and the delivered cases still match).
+- `web-sdk/customer-side-rt-entitlement-gate.test.ts`: `denies when the app
+  sets builtin_dimensions itself via update()`.
+- `web-sdk/customer-side-client-context.test.ts`: `holds exactly the
+  delivered value; an app-set value never reaches the context`.
+
+### Server SDKs get the control plane's built-in dimensions: `getBuiltinDimensions()` + a server overlay (BL-0366, plan 279 PD-3)
+
+**What changed.** Additive. Before this, a server-side decision never saw the
+control plane's Subscription State, Trial Type, Activity State, Seat Type or
+Buyer Role. The Python and Rust ports stamped `rt_*` traits only from the
+app-supplied `builtin_dimensions`, and the fetch that delivers the server's
+values existed only in the browser SDK's client-context lane.
+
+- **server-node** — `RevTurbineServer.getBuiltinDimensions(userId)` calls
+  `getServerUserBuiltinDimensions`
+  (`GET /api/sdk/user-contexts/{userId}/builtin-dimensions`) through the
+  generated typed client with the server key the client already holds. It
+  resolves to `{ tenant_id, user_id, builtin_dimensions, resolved_at }`
+  (re-exported as `ServerUserBuiltinDimensions`). The tenant comes from the
+  key: it is not a parameter, and no tenant header is sent. A refusal throws
+  the new `RevTurbineBuiltinDimensionsError` (`status`, `requestId`, machine
+  `code`, typed `reason`: `invalid_request` / `unauthorized` / `forbidden` /
+  `request_failed`). It never carries the key.
+- **The overlay (all three ports).** `createStaticProviders` takes
+  `serverBuiltinDimensions` (from `@revt-eng/core`, re-exported by server-node
+  together with `applyServerBuiltinDimensions`). Python's
+  `create_static_providers(server_builtin_dimensions=…)` and the
+  `RevTurbineCustomerSdk` user context key `server_builtin_dimensions` take
+  the same object. So do Rust's `StaticProviderOptions::server_builtin_dimensions`
+  and `sdk::UserContext::server_builtin_dimensions`, plus the
+  `apply_server_builtin_dimensions` helper in both ports. The object is
+  overlaid per key on the app-set `builtin_dimensions` before segment
+  membership is evaluated. A delivered leaf wins over the app's value (PD-3),
+  and an app-set leaf the server did not deliver is kept. This is the overlay
+  the browser SDK already applies to a client-context delivery. Without a user
+  context it is ignored, because nothing is evaluated then.
+- **Python and Rust get no HTTP client.** Neither port has a transport or a
+  server-key client (BL-0354), and this change does not add one. The app's
+  backend reads the endpoint itself (or through server-node) and passes the
+  response's `builtin_dimensions` in.
+
+Rust callers that build `StaticProviderOptions` or `sdk::UserContext` as a
+full struct literal without `..Default::default()` must add the new field.
+
+The `@revt-eng/*` pins move to `0.1.373`, which adds the operation and the
+core overlay (scaffold #430).
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** n/a (additive).
+**Proving test:** `tests/server-node-get-builtin-dimensions.test.ts`,
+`server-python/tests/adapters/test_static.py`,
+`server-rust/tests/static_providers.rs`, and the parity fixtures
+`segment_membership_server_overlay_wins` / `segment_membership_server_overlay_demotes`.
+
+### `RevTurbineProvider` disposes the previous SDK instance on an `options` change (BL-0375)
+
+**What changed.** `RevTurbineProvider`'s init effect creates a new SDK instance
+whenever the `options` prop (or `bootstrapPlacements`) changes identity, but its
+cleanup previously only flipped an internal `mounted` flag — it never called
+`dispose()` on the instance it was replacing. A host that rebuilds `options` on
+every render (an unmemoized `options={{ ... }}` literal, or an object built in
+an un-annotated `useMemo` with an unstable dependency — the shape web's dogfood
+provider had until web #944) therefore re-initialized on every render and
+leaked every earlier instance's flush-interval timer, `pagehide` /
+`visibilitychange` listeners, and any buffered telemetry.
+
+The cleanup now calls the previous instance's existing `dispose()` (flushes
+pending telemetry, detaches its listeners and timer) before the next render's
+instance is constructed. The re-init contract is unchanged: a new `options`
+object identity — even one with identical content — still creates a new SDK
+instance; that documented behavior was never the bug, the leak was. When a new
+`options` object is recreated with the same content as the previous one, the
+provider now also logs a one-time (per mounted provider lifetime) development
+warning pointing integrators at memoizing `options`, in addition to the
+existing every-time identity-change warning.
+
+**Landed in:** no release — no signature changed; `dispose()` on
+`RevTurbineCustomerSdk` already existed (documented for manual SPA-unmount
+teardown) and is now also called automatically by the provider.
+**Fail-closed in:** n/a — purely a leak fix; no customer-visible API changed.
+**Proving test:**
+`web-sdk/react/RevTurbineProvider.dispose-on-options-change.test.tsx`.
+
+### Behaviour fix: server SDKs stop serving segment-chipped payloads to every user (BL-0369)
+
+**What changed.** On the server lanes, every configured Playbook segment
+counted as a segment the user was in. That covered the Python and Rust
+`RevTurbineCustomerSdk`, `LocalRuntime`, and server-node's
+`LocalEvaluationServer` fed by `createStaticProviders`. So a payload chipped
+to any segment was shown to every user, and an entitlement rule targeted at
+any segment granted to every user on the plan. This included the generated
+built-in segments (`rt.<dimension>.<value>`, e.g.
+`rt.subscription_state.paid`) that hosted Playbooks now export. The browser
+SDK was not affected.
+
+A user is now in a segment only when one of these is true, the same rule the
+browser SDK applies:
+
+- your app passed its handle in `segment_ids` (Python / Rust) or
+  `segmentIds` (`createStaticProviders`), or
+- its predicates match the user's targeting traits. Those traits are built
+  from `custom`, the plan, and the reserved `rt_<dimension>` traits.
+  `rt_<dimension>` traits come **only** from `builtin_dimensions`, which the
+  server sets (plan 279 PD-3). For experiment segments, the user's
+  `experiments` assignments decide enrollment.
+
+Anything else fails closed. An unset dimension, a trait the user doesn't
+carry, or a chip that names an unknown segment serves nothing (PD-4).
+
+New inputs (all additive): `custom`, `builtin_dimensions` and `experiments`
+on the Python `UserContext` and the Rust `UserContext` struct. `segment_ids`
+now also drives chips and rules, not just the catalog helpers.
+`createStaticProviders` gets `segmentIds` and `userContext` from
+`@revt-eng/core`. A side fix: the Python and Rust rules providers now carry
+`segment_dimensions` and the Playbook's `format_version`, like TypeScript.
+Without `segment_dimensions`, a rule targeted at segments in two dimensions
+would have matched on either one once membership became real.
+
+**Impact on existing integrations.** This is a correctness fix, but you may
+notice it. If a server-side integration shows segment-chipped payloads or
+grants segment-targeted entitlements, and it passes none of the inputs
+above, those payloads now **stop showing** and those rules **stop
+granting**. They were being over-served before. To keep serving users who
+really are in the segment, pass `segment_ids` for segments your app
+resolves, and `builtin_dimensions` / `custom` for predicate and built-in
+segments. The Rust `UserContext` struct gains three fields. A struct literal
+that does not end in `..Default::default()` needs them added.
+
+The `@revt-eng/*` pins move to `0.1.372`: scaffold #429 is the BL-0369 core
+fix, and it carries scaffold #428 (0.1.371: the `billing_health`
+built-in dimension leaf, BL-0317, and `seat_type_handle` becoming
+required-nullable on `ServerUserContextUpsert`, BL-0367). The vendored port
+types follow: in Python, `ServerUserContextUpsert.seat_type_handle` loses its
+default; in Rust, `ClientContextBuiltinDimensionsBillingHealth` is added.
+
+**Landed in:** 0.11.14 (`@revt-eng/core` 0.1.372 carries
+the scaffold BL-0369 fix).
+**Fail-closed in:** the same release.
+**Proving test:**
+- `tests/parity/fixtures/segment_membership_{no_inputs,builtin_and_traits,explicit_ids}.json`
+  (TS == Python == Rust).
+- `server-python/tests/adapters/test_static.py` and
+  `server-rust/tests/static_providers.rs` (segment membership tests).
+- `tests/server-node-local-segment-membership.test.ts`.
+
+### `update()` carries `experiments` and `builtin_dimensions`; server-computed keys are dropped at every browser entry point (BL-0352, ruling D-36)
+
+**What changed.** `update()`'s exhaustiveness check never ran. It was an
+`expectTypeOf` inside a vitest `.test.ts`, and vitest does not typecheck. Four
+fields had reached `RevTurbineUpdateInput` without reaching
+`RECOGNIZED_UPDATE_KEYS`, so `update()` accepted them at compile time and
+silently dropped them at runtime. Each one now has an explicit disposition:
+
+- *(`builtin_dimensions` superseded by BL-0381 above: it is server-assigned
+  and dropped.)* `experiments` and `builtin_dimensions` are **now applied**
+  by `update()`.
+  The app may supply experiment assignments it already knows
+  (`runtime/experiment-assignment.md` §3, plan 183), and it may seed built-in
+  dimensions, for example in `local_only` mode. The client-context overlay
+  still wins when it is present (`targeting-studio-ui.md` §4.1). Before this
+  change, `update({ experiments })` compiled and did nothing.
+- `activity_score` and `activity_score_computed_at` are **server-computed**.
+  The control plane's hourly activity-score refresh writes them (plan 180),
+  and the browser receives only the derived `activity_level` dimension. Like
+  `seat_type_handle` (BL-0351), they are now omitted from
+  `RevTurbineUserContext`, `RevTurbineUpdateInput` and `IdentifyContextInput`.
+- `setUserContext()` and the `user` init option now **drop server-assigned
+  keys at runtime** (`seat_type_handle`, `activity_score`,
+  `activity_score_computed_at`) and report them. `identify()` and `update()`
+  already dropped them, and now report them with a server-assigned warning
+  that names the backend as the writer, not the "pass it under `custom`"
+  hint. Before this change, a plain-JS `setUserContext({ seat_type_handle })`
+  merged the key into the held context, and local mode persisted it. A state
+  blob persisted before this change is purged of those keys when it is
+  restored. A server-action result that echoes them back is stripped without
+  a warning.
+- New exported types `RecognizedUpdateKey` and `RecognizedIdentifyKey`
+  (additive) back a real compile-time derivation in
+  `web-sdk/update-keys-exhaustiveness.test-d.ts`, which
+  `pnpm check:types:exact` compiles. A future `UserContext` field fails the
+  build until it is added to the runtime list or omitted as server-assigned.
+
+**Deferred to `0.12.0`:** `setUserContext()` still takes
+`RevTurbineUserContext` without `Exact<>`, so other undeclared keys that
+arrive through a variable are not rejected at compile time. Adding `Exact<>`
+would break callers that pass a wider object today. `IdentifyContextInput`
+also still declares 11 keys that `identify()` drops with a warning (`trial`,
+`tiers`, `experiments`, …). The type-test pins that list, so it cannot grow
+silently. Narrowing the type is a breaking change and waits for the minor.
+
+The `@revt-eng/*` pins move to `0.1.370` (scaffold #427: discovery-owned
+`SurfaceSlotSchema.slot_name`). That field now appears in the generated client
+types and the vendored Python and Rust port types. The SDK does not write it.
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** the same release. The compile-time omission and the
+runtime drop at all four entry points both ship in it.
+**Proving test:**
+- `web-sdk/update-keys-exhaustiveness.test-d.ts` (`pnpm check:types:exact`).
+- `web-sdk/identify-guardrails.test.ts`: describe blocks
+  `server-computed keys never enter the browser context`,
+  `setUserContext() drops server-assigned keys at its runtime boundary` and
+  `update() carries app-owned experiments` (renamed by BL-0381).
+
+### server-node `assignSeatType()` writes a user's seat type (BL-0354, plan 279 TASK-16a, ruling D-36)
+
+**What changed.** Additive. `RevTurbineServer` (server-node) gains
+`assignSeatType(userId: string, seatTypeHandle: string | null)`. It calls
+`upsertServerUserContext` (`POST /api/sdk/user-contexts`) through the generated
+typed client with the server key the client already holds. The request body is
+exactly `{ user_id, seat_type_handle }`. `null` clears the assignment. The
+tenant comes from the key: it is not a parameter, and no tenant header is sent.
+It resolves to the stored assignment
+`{ tenant_id, user_id, updated_at, seat_type_handle }` (re-exported as
+`ServerUserContextAssignment`).
+
+A refusal throws the new `RevTurbineSeatAssignmentError`. It carries `status`,
+`requestId`, the control plane's machine `code` when present, and a typed
+`reason`: `unknown_seat_type` (422: the handle is not one of the tenant's seat
+types), `forbidden` (403: the credential is not a server key), `unauthorized`
+(401), `invalid_request` (400) or `request_failed`. Like
+`RevTurbineClientSessionError`, it never carries the key or the free-text
+response message.
+
+Per D-36 the seat assignment is server-written only, so there is no browser SDK
+surface for this. The Python and Rust ports have no HTTP client or server-key
+client, only the vendored `ServerUserContextUpsert` / `ServerUserContextAssignment`
+models, so they gain no helper.
+
+The `@revt-eng/*` pins move to `0.1.369`, which adds that operation to the
+external contract (scaffold #425).
+
+**Landed in:** 0.11.14.
+**Fail-closed in:** n/a (additive).
+**Proving test:** `tests/server-node-assign-seat-type.test.ts`.
+
+### `seat_type_handle` is server-assigned and never a browser input (BL-0351, plan 279 TASK-16a, ruling D-36)
+
+**What changed.** Scaffold `0.1.368` adds `UserContextSchema.seat_type_handle`,
+the user's persisted seat-type assignment. Per D-36 it has exactly two writers:
+the tenant's backend (a server-key user-context upsert) and RevTurbine's own
+server-side enrichment in hosted mode. The browser never writes it. Without a
+change here the new field would have flowed into the browser input types
+through `UserContextInput`. Instead:
+
+- `RevTurbineUserContext` omits `seat_type_handle`. So do
+  `RevTurbineUpdateInput`, which derives from it, and `IdentifyContextInput`.
+  `identify()`, `update()` and the `user` init option reject the key at compile
+  time, including when it arrives through a variable (`Exact<…>`).
+  `setUserContext()` rejects it in an object literal.
+- The key stays out of the runtime recognized-key lists, so a plain-JS caller's
+  `seat_type_handle` is dropped at the `identify()`/`update()` boundary and
+  reported by the existing unrecognized-key warning. It is never merged into the
+  held context.
+- The browser receives the **resolved** seat type as
+  `builtin_dimensions.seat_type` / `builtin_dimensions.buyer_role` from the
+  client-context fetch (plan 279 TASK-16, web), unchanged here.
+
+No released SDK type ever carried `seat_type_handle`, so nothing an
+integration compiles today stops compiling. The `@revt-eng/*` pins move to
+`0.1.368`. That version also adds `SeatTypeSchema.is_buyer` (default `false`),
+which now appears in the vendored Python and Rust port types.
+
+A server-node `assignSeatType(userId, handle | null)` helper was **not** in this
+change, because the server-key operation it wraps (`upsertServerUserContext`,
+`POST /api/sdk/user-contexts`, plan 279 TASK-15a) was not yet in the published
+external contract. It shipped with scaffold `0.1.369` (see the BL-0354 entry
+above).
+
+**Landed in:** 0.11.14. This PR bumps pins only.
+**Fail-closed in:** the same release (compile-time rejection; runtime drop).
+**Proving test:**
+- `web-sdk/user-context-exactness.test-d.ts`: the `@ts-expect-error` block
+  "Server-assigned fields" (`pnpm check:types:exact`).
+- `web-sdk/identify-guardrails.test.ts`: describe block
+  `seat_type_handle never enters the browser context`.
+
+## 0.11.13
+
+### Slot lifecycle events carry the slot's `route` (BL-0207, ruling D-30)
+
+**What changed.** Every slot lifecycle event (`slot_evaluated`, `slot_filled`,
+`slot_empty`, `slot_suppressed`, `slot_error`) now carries `route`: the app
+route the slot rendered on. Ingestion-driven surface-slot discovery reads it
+and persists it on the discovered slot. There is no SDK write to any CRUD
+route. The field is additive and optional in the scaffold contract
+(`slotContextBase.route`).
+
+A route is a **path, never a URL**. It has no origin, query string or
+fragment. The React layer computes it at emission time:
+
+- **Default:** `window.location.pathname`, with identifier-like segments
+  templated to `:id`. That covers numbers, UUIDs, long hex, prefixed ids like
+  `cus_…`, long opaque tokens and email-shaped values, raw or
+  percent-encoded. For example, `/accounts/4821/billing?coupon=X` reports
+  `/accounts/:id/billing`.
+- **`<RevTurbineRoute route={…}>`** (new, renderless) declares the framework
+  route pattern for its subtree, and the innermost boundary wins.
+- **Next.js App Router:** build the pattern with the new pure helper
+  `routePatternFromParams(usePathname(), useParams())`, which gives
+  `/projects/[projectId]/settings`. The SDK does not import `next/navigation`.
+
+Also new:
+
+- **Headless exports:** `normalizeSlotRoute`, `routePatternFromParams`,
+  `currentBrowserRoute`, `isIdentifierLikeSegment` and `SLOT_ROUTE_MAX_LENGTH`
+  (512).
+- **React hook:** `useSlotRoute()`.
+- **Headless controller option:** `PlacementControllerOptions.route` accepts a
+  string or a getter. When it is omitted, a headless controller emits
+  `route: null`.
+
+**Landed in:** 0.11.13 (`web-sdk` only; `server-python`/`server-rust` bumped
+in lockstep with no behavior change — no port emits slot events). The
+`@revt-eng/*` pins move to `0.1.366` (the scaffold contract: `slotContextBase.route`,
+`SurfaceSlotSchema.route`, and the `SurfaceSlotStatus` = `live | idle`
+vocabulary), and the vendored port types are re-synced — `SurfaceSlot.status`
+is now `SurfaceSlotStatus` (`live`/`idle`, default `idle`) in both ports.
+**Fail-closed in:** n/a (additive telemetry field).
+**Proving test:**
+- `web-sdk/slot-route.test.ts`: normalization, PII/query stripping, the
+  Next.js params recipe, and controller emission including the
+  throwing-getter case.
+- `web-sdk/react/usePlacement.route.test.tsx`: the plain-DOM pathname case and
+  the `<RevTurbineRoute>` Next.js pattern case.
+
 ## 0.11.12
 
 ### `builtin_dimensions` now reaches the browser SDK from the client-context fetch (BL-0312, plan 279 TASK-5)

package/dist/growthbook.d.ts

@@ -226,11 +226,11 @@ declare const UserPlanContextSchema: z.ZodObject<{
  */
 declare const UserBuiltinDimensionsSchema: z.ZodObject<{
     activity_level: z.ZodOptional<z.ZodEnum<{
-        inactive: "inactive";
         new: "new";
         high: "high";
         medium: "medium";
         low: "low";
+        inactive: "inactive";
     }>>;
     subscription_state: z.ZodOptional<z.ZodEnum<{
         trial: "trial";