@revturbine/sdk 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -22,12 +22,19 @@ A change whose "Fail-closed in" is later than its "Landed in" had a window where
 the old shape was accepted and did nothing. Those windows are the expensive ones.
 
 > **What this file is not yet.** A CI guard fails any PR that changes a
-> `@public`-tagged export signature without touching this file. That tagging is
-> thin: as of `0.8.0` it covers **4** methods on `RevTurbineCustomerSdk`, which
-> declares roughly **73**. `can()`, `getPlacementDecision()`, `identify()` and
-> `dismiss()` are among the untagged, so a breaking change to one of them will
-> not be caught automatically — it depends on whoever writes the PR. Entries here
-> are reliable; the absence of an entry is not yet proof that nothing changed.
+> `@public`-tagged export signature without touching this file. That tagging
+> was thin (4 of ~73 methods) until BL-0005 (2026-09-22, no release — TSDoc
+> and snapshot only) widened it to **34** of `RevTurbineCustomerSdk`'s **67**
+> non-private methods, plus 5 provider/hook entry points
+> (`initRevTurbine`, `RevTurbineProvider`, `useCan`, `useEntitlement`,
+> `useGatedAction`) — every method a customer-facing guide, skill, the
+> starter, or a demo app calls directly. The remaining ~33 methods are
+> internal-only paths (called only by the SDK's own placement components,
+> React bindings, or other internal packages) and stay untagged, so a
+> breaking change to one of *those* still will not be caught automatically —
+> it depends on whoever writes the PR. Entries here are reliable; the absence
+> of an entry for a currently-untagged method is not yet proof that nothing
+> changed.
 
 > **Note on 0.x.** These packages are pre-1.0, so breaking changes ship in the
 > **minor** position (`0.6.0` → `0.7.0`), not the major. `npm`'s caret on a `0.x`
@@ -40,6 +47,93 @@ also require a changelog entry.
 
 ---
 
+## 0.10.2
+
+### Local mode resolves placements by slot id (BL-0119)
+
+**What changed.** In `local_only` mode the browser SDK now resolves a placement
+request against the Playbook's authored `placement_slots[]` registry.
+`getPlacement({ slotId })` — with or without a `componentType` — previously
+returned `null` for a slot the Playbook declared, and a controller/`usePlacement`
+mount of that slot resolved to `placement_not_found`. Looking the same placement
+up by **name** worked, which is what made this look like a config problem rather
+than an SDK one.
+
+Two things were missing, and both are now in place:
+
+- **`registerSurfaceSlot()` adopts the declared template.** `surface_template_ids`
+  on the registered record is what puts the shared resolver on its slot branch,
+  where `trigger.slot_id` is matched. Without it the resolver fell back to direct
+  lookup, which is keyed by placement **name**/id and therefore can never match a
+  slot id — hence `placement_not_found`. An id passed explicitly at the call site
+  still wins; the mounting code knows what it renders.
+- **`getPlacement()` falls through to the slot registry.** The local placement
+  cache only holds slots a decision has already run through, so a cold lookup
+  found nothing and stopped. It now derives the record from `placement_slots`,
+  matching on `id` and falling back to `surface_type` when only a component type
+  is given — the same derivation scaffold's headless
+  `LocalRuntime.slotRecordForConfig` has always performed. Registration on this
+  path is local only: reading a placement never writes a surface slot back to the
+  control plane.
+
+This closes a browser-versus-headless divergence: the same Playbook decided
+differently depending on which runtime read it. No public API change — no
+signature moved, and nothing new is asked of the caller. A slot id that no
+`placement_slots` entry declares still resolves to `null`, unchanged.
+
+**Landed in** `0.10.2`. **Fail-closed in** n/a — a previously-`null` lookup now
+returns the placement the Playbook authored.
+
+**Proving test:** `web-sdk/local-slot-id-lookup.test.ts` — by-slot-id and
+by-slot-id-plus-component-type both resolve, the controller path no longer
+reports `placement_not_found`, an undeclared slot id still returns `null` and
+gains no invented template, an explicit `surfaceTemplateIds` still wins, and the
+by-name lookup that always worked keeps working (the positive control).
+
+---
+
+## 0.10.1
+
+### Treatment interactions carry the identified `account_id`
+
+**What changed.** Every treatment interaction the SDK sends to
+`/api/events/interactions` — the impression that writes a
+`placement_presentations` row, plus dismiss / click / conversion — now carries
+`account_id`, taken from the account the integration identified
+(`identify(userId, { account_id })` / `setUserContext`). It was never sent at
+all, so the ingest route's `account_id ?? user_id` fallback stamped a **user**
+id into an **account** column. `placement_presentations.account_id` is a join
+key, not a label: `monetization_funnel` matches it against account ids from
+`events_clickstream` / `events_billing`, and every experiment summary pipe
+reads it when `analysis_unit='account'`. Those joins therefore matched only
+where a user id happened to equal an account id — and an account-grain
+experiment readout returned the user-grain n while looking perfectly valid.
+
+Two details make it a usable key. The value is PII-redacted **identically to
+`/api/track`**, so an email-shaped account id becomes the same hash in
+`placement_presentations` and in `events_clickstream` and the funnel actually
+joins. And when no account was identified the field is **omitted**, never set
+to the user id — the route keeps its own fallback for SDKs that have not
+upgraded, but a wrong join key is worse than a missing one.
+
+No public API change: nothing new is asked of the caller, and
+`RevTurbineTreatmentInteractionInput` is unchanged. Integrations that already
+pass `account_id` to `identify()` get correct account-grain analytics with no
+code change; integrations that never identify an account are unaffected on the
+wire and see the same route-side fallback as before.
+
+**Landed in** `0.10.1`. **Fail-closed in** n/a — additive; nothing old is
+rejected.
+
+**Proving test:** `web-sdk/interaction-wire-contract.test.ts` — "the account
+identity the analytics joins key on": the identified account reaches the wire
+distinct from `user_id`, an unidentified one is omitted rather than copied from
+`user_id`, an email-shaped account id matches the `/api/track` lane
+byte-for-byte, and a re-queued batch keeps the account that was acting when
+each interaction happened.
+
+---
+
 ## 0.10.0
 
 ### `publicKey` is the browser credential; `apiKey` is the server key