@revturbine/sdk 0.11.10 → 0.11.12

package/CHANGELOG.md

@@ -47,6 +47,95 @@ also require a changelog entry.
 
 ---
 
+## 0.11.12
+
+### `builtin_dimensions` now reaches the browser SDK from the client-context fetch (BL-0312, plan 279 TASK-5)
+
+**What changed.** `0.11.11` (BL-0310/BL-0311) taught the shared evaluator to
+stamp `rt_<dimension>` segment traits from a `builtin_dimensions` object on the
+user context, but nothing yet delivered that object into `web-sdk`'s held
+context. `fetchClientContext` (`GET /api/sdk/client-context`) now maps the
+response's `builtin_dimensions` onto `RevTurbineUserContext.builtin_dimensions`,
+overlaying per leaf the same way it overlays `plan_handle`: a leaf the server
+evaluated on this fetch replaces the held value; a leaf it did not evaluate
+leaves whatever the app (or a prior fetch) had set untouched. A leaf absent on
+both sides stays absent — unknown is trait absence (plan 255), never a
+sentinel.
+
+The hash-skip that decides whether a fetch actually changed anything and
+should re-apply (and so re-evaluate segments) now accounts for
+`builtin_dimensions`. This surfaced a real gap: the shared
+`computeUserContextHash` helper re-projects its input to a fixed key set
+(`plan_handle`, `plan`, `usage`, `custom`, `trial`, `instances`) and silently
+drops anything outside it, so simply adding `builtin_dimensions` to the object
+passed to it was a no-op. `builtin_dimensions` is folded into the skip key as
+a literal suffix instead — the same technique already used for the coarse
+`payment_at_risk` signal, which has the identical problem.
+
+**Landed in:** 0.11.12 (`web-sdk` only; `server-python`/`server-rust` bumped
+in lockstep with no behavior change — the ports have no client-context fetch
+of their own and resolve built-ins only from an app-supplied
+`builtin_dimensions`, per plan 279's TASK-17 backlog note).
+**Fail-closed in:** 0.11.12. Before this release, a client-context response
+that changed only `builtin_dimensions` was hash-skipped and segments never
+re-evaluated against the new value.
+**Proving test:** `web-sdk/customer-side-client-context.test.ts`, describe
+block `builtin_dimensions (plan 279 AC-4)` — server-overlays-app, an
+unevaluated leaf survives, a changed value re-applies (new context object),
+an unchanged value does not.
+
+## 0.11.11
+
+### Built-in segment dimensions: reserved `rt_*` segment traits (BL-0310/BL-0311, plan 279 TASK-3/TASK-4)
+
+**What changed.** The user context gains an optional `builtin_dimensions` object with the
+built-in segment dimension values: `activity_level`, `subscription_state`, `trial_type`,
+`seat_type`, `buyer_role`, `email_type`, `billing_health`, `region` and `device_type`.
+Targeting-state derivation (`buildTargetingState`, Python `build_targeting_state`, Rust
+`build_targeting_state`) now:
+
+- always stamps `rt_registration_state`: `registered` when the context has a non-empty
+  `id`, otherwise `unregistered`;
+- stamps each other `rt_<dimension>` segment trait **only** from an in-vocabulary
+  `builtin_dimensions` value. An absent or unknown value stamps nothing, so every
+  built-in segment of that dimension fails closed;
+- **deletes** any `rt_*` key that arrives through `custom`, `entitlements`, usage
+  entries or usage overrides. `rt_` is now a reserved trait-key prefix, like
+  `plan_handle`.
+
+Before this release, an app trait named `rt_<anything>` reached segment evaluation. It is
+now removed. Python and Rust also export the new helpers: `derive_builtin_dimension_traits`,
+`is_reserved_trait_key`, `BUILTIN_DIMENSION_VOCABULARIES` and `BUILTIN_TRAIT_KEY_PREFIX`.
+Contract: targeting-studio-ui.md §4.1 "Built-in segment resolution contract".
+
+**Landed in:** 0.11.11 (all three ports, `@revt-eng/core` 0.1.359).
+**Fail-closed in:** 0.11.11. A custom `rt_*` trait is dropped from the first version that
+reserves the prefix.
+**Proving test:** parity fixture `tests/parity/fixtures/builtin_dimension_traits.json`
+(ts == py == rs) with `tests/parity/builtin-dimension-chain.test.ts`, plus
+`server-python/tests/test_builtin_dimension_traits.py` and the
+`user_context::builtin_dimension_tests` Rust module.
+
+## Unreleased (no version bump — docs and TSDoc only)
+
+### `RevTurbineServer` documents `apiKey` as the server key (BL-0107, plan 256 TASK-4)
+
+**What changed.** The control plane's `POST /api/sdk/client-sessions` now accepts
+the customer's **server key** (`rtk_…`, type `server`) as the minting authority;
+the separate `rt_secret_` mint secret it used to require was never issuable and
+is retired (revturbine-web, plan 256 TASK-2/3). `RevTurbineServer`'s TSDoc,
+`server-node/README.md` and the `@revt-eng/sdk/server` example now say so: pass
+the server key as `apiKey`, read from `REVTURBINE_API_KEY` (was
+`REVTURBINE_SECRET_KEY`). The examples also now call
+`createClientSession({ subject })` and read `client_token` — the shapes the
+method has always had (the old examples passed `userId` and read `token`).
+
+**Landed in:** no release — no signature changed; the `apiKey` option already
+existed and already sent the server key as the Bearer.
+**Fail-closed in:** n/a — no customer-visible behaviour changed in this package.
+**Proving test:** `tests/server-node-client-sessions.test.ts` (mints via the
+endpoint with the key as Bearer; the key never reaches errors or the console).
+
 ## 0.11.9
 
 ### The SDK can record app-owned trial revisions and evidenced account creation (BL-0237, plan 276 TASK-13)

package/dist/growthbook.d.ts

@@ -212,10 +212,73 @@ declare const UserPlanContextSchema: z.ZodObject<{
         none: "none";
     }>>;
 }, z.core.$strip>;
+/**
+ * Server-evaluated built-in segment dimension values for the user (plan 279
+ * PD-3). `buildTargetingState` stamps each present, in-vocabulary leaf onto
+ * the reserved `rt_<dimension>` segment trait; nothing else may set an `rt_*`
+ * trait (PD-1). An ABSENT leaf means "not evaluated" and stamps nothing, so
+ * every built-in of that dimension fails closed (PD-4, unknown is absence);
+ * when the control plane evaluated a dimension and found no classification it
+ * delivers the dimension's explicit fallback value instead.
+ *
+ * Assembled at retrieval — never persisted as a blob; the sources keep their
+ * own columns.
+ */
+declare const UserBuiltinDimensionsSchema: z.ZodObject<{
+    activity_level: z.ZodOptional<z.ZodEnum<{
+        inactive: "inactive";
+        new: "new";
+        high: "high";
+        medium: "medium";
+        low: "low";
+    }>>;
+    subscription_state: z.ZodOptional<z.ZodEnum<{
+        trial: "trial";
+        none: "none";
+        paid: "paid";
+        cancelled: "cancelled";
+    }>>;
+    trial_type: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        free_trial: "free_trial";
+        reverse_trial: "reverse_trial";
+    }>>;
+    seat_type: z.ZodOptional<z.ZodString>;
+    buyer_role: z.ZodOptional<z.ZodEnum<{
+        buyer: "buyer";
+        non_buyer: "non_buyer";
+    }>>;
+    email_type: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        business: "business";
+        personal: "personal";
+    }>>;
+    billing_health: z.ZodOptional<z.ZodEnum<{
+        payment_failed: "payment_failed";
+        payment_method_missing: "payment_method_missing";
+        cancelled: "cancelled";
+        no_billing: "no_billing";
+        good_standing: "good_standing";
+        trial_payment_method_attached: "trial_payment_method_attached";
+        payment_overdue: "payment_overdue";
+    }>>;
+    region: z.ZodOptional<z.ZodEnum<{
+        us_canada: "us_canada";
+        europe: "europe";
+        rest_of_world: "rest_of_world";
+    }>>;
+    device_type: z.ZodOptional<z.ZodEnum<{
+        unknown: "unknown";
+        desktop: "desktop";
+        mobile: "mobile";
+        tablet: "tablet";
+    }>>;
+}, z.core.$strip>;
 
 // AUTO-GENERATED by scripts/generate-zod-outputs.ts - do not edit.
 
 
+type UserBuiltinDimensions = z.infer<typeof UserBuiltinDimensionsSchema>;
 type UserPlanContext = z.infer<typeof UserPlanContextSchema>;
 type UserUsageEntry = z.infer<typeof UserUsageEntrySchema>;
 
@@ -257,6 +320,15 @@ interface UserContextSnapshot {
     personalization?: Record<string, JsonValue>;
     /** Canonical experiment-handle to variant-handle assignments. */
     experiments?: Record<string, string>;
+    /**
+     * Built-in segment dimension values (plan 279 PD-3; targeting-studio-ui.md
+     * §4.1 "Built-in segment resolution contract"). The ONLY source of the
+     * reserved `rt_<dimension>` segment traits: `buildTargetingState` stamps
+     * each present, in-vocabulary value and ignores the rest. Delivered by the
+     * control plane's client context, or set by the app itself in `local_only`
+     * mode and on the server ports — a server-delivered value wins.
+     */
+    builtin_dimensions?: UserBuiltinDimensions;
 }
 
 /**