@revturbine/sdk 0.11.16 → 0.11.17

package/CHANGELOG.md

@@ -47,6 +47,188 @@ also require a changelog entry.
 
 ---
 
+## 0.11.17
+
+### Checkout metadata helper, `checkout_started`, and decision context on interactions (plan 282 TASK-9, BL-0432)
+
+**What changed.** Three additive changes to the browser SDK (`@revturbine/sdk`);
+no existing signature narrows.
+
+- **`checkoutMetadata(outputId)`** (new, `@public`) returns the Stripe Checkout
+  `revturbine_*` metadata bag for an output this SDK decided — user, account,
+  placement, decision, output, rule and target plan — plus
+  `client_reference_id` (the user id). Pass `metadata` as both the session's
+  `metadata` and `subscription_data.metadata`; the mirror is what reaches each
+  invoice's `parent.subscription_details.metadata`. A key the SDK does not hold
+  is absent, never empty; `null` for an output this SDK did not decide. New
+  types `RevTurbineCheckoutMetadata` and `RevTurbineCheckoutMetadataBag`.
+- **`checkout_started`** (taxonomy v6, `@revt-eng/schema` 0.1.381) is emitted on
+  a `cta_clicked` whose CTA opens a plan picker or pricing page
+  (`CHECKOUT_STARTED_CTA_ACTION_TYPES`: `navigate_to_plans`, `view_plans`) with
+  `{ placement_id, payload_id, decision_id, plan_handle, rule_handle }`. Never
+  for `open_checkout_modal` — that CTA opens checkout directly ("on click"), so
+  its started count is its clicked count.
+- **`trackTreatmentInteraction`** accepts optional `decisionId`,
+  `segmentHandles` and `segmentIds` (`RevTurbineTreatmentInteractionDecisionContext`;
+  the parameter type is now `RevTurbineTreatmentInteractionRequest`, a
+  superset of the previous `RevTurbineTreatmentInteractionInput`) and sends
+  them as `decision_id` / `segment_handles` / `segment_ids`. Segments are
+  handles: `segment_handles` is the effective set scaffold's `evaluateSegments`
+  built plus any hosted-resolved slugs — the analytics join key — and
+  `segment_ids` carries only the minted ids a hosted context supplied
+  (telemetry; omitted entirely in local mode). When not given, they are filled
+  from the output this SDK indexed for `payloadId`; a caller that gives none
+  and names no indexed output sends exactly the row it sent before. The React
+  controller's clicks and the output-addressed `convert()` / `dismiss()` /
+  `snooze()` carry them.
+
+**Landed in** 0.11.17. **Fail-closed in** n/a — additive. The headless ports
+(Python, Rust, `server-node`) carry only the re-vendored generated types for
+the 0.1.381 pin; the cross-language parity corpus is untouched.
+
+**Docs.** `guides/billing.mdx` "Where checkout fits" now documents the bag, the
+`subscription_data.metadata` mirror, `client_reference_id`, and that Customer
+metadata cannot be set from Checkout.
+
+**Proving tests.** `web-sdk/checkout-metadata.test.ts`,
+`web-sdk/checkout-started-emit.test.ts`,
+`web-sdk/interaction-decision-context.test.ts`.
+
+### `update({ usage })` now reaches usage and credit threshold placements and their usage tokens (BL-0402, BL-0409)
+
+**What changed.** A behaviour fix in the browser SDK (`@revturbine/sdk`); no
+signature changes. `update({ usage })` / `updateUsage()` wrote only the SDK's
+private usage balances. `can()` and `getUsage()` read those balances, but the
+placement resolver built its usage state from the user context's `usage`
+entries alone, and took each entry's `limit` only from a per-entry field
+(default `0`). The shared threshold gate fails closed on a missing or zero
+limit. So `usage_threshold` and `credit_threshold` placements (the 80% usage
+banner, the low-credits warning) never fired for app-reported usage, and
+`{{usage_current}}` / `{{usage_limit}}` / `{{usage_remaining}}` /
+`{{usage_percent}}` stayed stale or unresolved, while the gate and the meter
+moved.
+
+Placements now read one usage view, the same one `getUsage()` reports:
+
+- **Used**: the balance the app reported through `update({ usage })` /
+  `updateUsage()` / `identify(…, { usage })` wins (the most recent write),
+  else the context entry's `amount`.
+- **Limit**: the context entry's own `limit` wins, else the Playbook
+  allowance for the user's **current plan** (the plan-scoped `usage_limit`
+  rule's `limit_value` or `credits` rule's `allowance_value`, which is the
+  `limit` `getUsage()` already returned). An `unlimited` or absent allowance
+  means no threshold: the placement does not fire.
+- **Tokens**: the SDK now fills the usage token family in decision content
+  from the same view. It fills `{{usage_current}}` whenever usage is known.
+  It fills `{{usage_limit}}`, `{{usage_remaining}}` and `{{usage_percent}}`
+  only when a positive limit is known, so an unlimited allowance leaves
+  those tokens untouched instead of rendering `0`. The `<unit>_usage_*`
+  forms and the aliases (`current_usage`, `current_limit`,
+  `remaining_usage`) are filled too. A registered entitlements provider
+  still supplies its own usage state, as before.
+
+`can()` and `getUsage()` are unchanged. The headless server ports (Python,
+Rust, `server-node`) take usage counters from the caller and are unaffected;
+the cross-language parity corpus is untouched.
+
+**Docs.** `tutorials/usage-quota-meter.mdx` and
+`tutorials/low-credits-warning.mdx` now use the canonical flat Playbook rule
+shape (`kind` + `limit_value` / `allowance_value`, handle-valued ids). The
+old nested `type_fields` shape resolved no allowance, so neither tutorial's
+banner could fire. The expected-behaviour table now matches what the SDK
+does: the banner shows from 80%, and at 100% `can('api_calls')` denies.
+
+**Proving test.** `web-sdk/usage-reaches-placements.test.ts`.
+
+### App-supplied trial context now reaches trial placements, trial tokens and reverse-trial grants (BL-0403)
+
+**What changed.** A behaviour fix in the browser SDK (`@revturbine/sdk`); no
+signature changes. `user.trial` at init, `update({ trial })`,
+`setUserContext({ trial })` and a server action's `userContext` result all
+merged into the user context's `trial`, but neither trial reader looked there.
+The placement resolver's plan state (which gates `trial_started`,
+`trial_progress`, `trial_ending`, `trial_ended` and `trial_converted`
+placements) and the reverse-trial entitlement grants read only the SDK's own
+trial status, written by `localRuntime.initialData.trialStatus`, `hydrate()`,
+`getTrialStatus()` and `setTrialInstances()`. So an app that supplied its
+trial saw no trial placement fire, no reverse-trial grant apply, and
+`{{trial_days_remaining}}` stay raw.
+
+Both readers now use one trial view:
+
+- **Sources.** The user context's `trial` (what the app supplies, plus the
+  authenticated client-context delivery, which merges its trial into the same
+  field) and the SDK trial status (`initialData.trialStatus`, `hydrate()`,
+  `getTrialStatus()`, `setTrialInstances()`).
+- **Precedence: the most recent change wins**, the same rule the usage view
+  applies to reported balances (BL-0402). A server-delivered or hydrated
+  status wins when it arrives after the app's trial (an
+  `initialData.trialStatus` passed alongside init `user.trial` counts as
+  later). An app `update({ trial })` made after it wins over it. Re-sending
+  an unchanged trial is not a newer write, so passing the same trial on every
+  render never displaces a fresher server status. A source that was never
+  supplied does not compete.
+- **Tokens.** The SDK now fills `{{trial_days_remaining}}` and
+  `{{trial_days_total}}` in decision content from the same plan state the
+  trial gate read. A token whose value is unknown is left untouched.
+- **`getTrialStatus()`** in `local_only` mode with no `getTrialStatus`
+  resolver returns this trial view, the app-supplied trial included.
+
+**React.** `<RevTurbineProvider>` no longer reports `trial`, `tiers`,
+`payment_failed`, `payment_at_risk`, `instances`, `experiments`, `email_type`,
+`derived_config_version`, `context_hash` or `derived_computed_at` in
+`options.user` as "dropped unrecognized user-context key(s)" on mount. The SDK
+constructor already merges them from `options.user`; the provider now forwards
+only the identity fields `identify()` merges. Unknown keys and server-assigned
+keys are still reported.
+
+The headless server ports (Python, Rust, `server-node`) take an
+already-derived trial status and are unaffected; the cross-language parity
+corpus is untouched.
+
+**Proving tests.** `web-sdk/trial-reaches-placements.test.ts`,
+`web-sdk/react/RevTurbineProvider.identify-context.test.tsx`.
+
+### Trial state no longer leaks across users; app-supplied trials fire lifecycle triggers; `getUserContext()` reports trial and billing fields (BL-0417)
+
+**What changed.** Behaviour fixes in the browser SDK (`@revturbine/sdk`)
+that follow up BL-0403. No signature changes.
+
+- **Reset and user switch.** `resetIdentity()` / `resetUserContext()`
+  cleared the user context but kept the SDK trial status (from
+  `initialData.trialStatus`, `hydrate()`, `getTrialStatus()` or
+  `setTrialInstances()`). They also kept which trial source was newest and
+  the last lifecycle stage. So the next user saw the previous user's trial
+  placements, reverse-trial grants and `{{trial_days_*}}` tokens, and a
+  trial-less next user could emit `trial_expired`. A reset now clears all of
+  that, and the next user starts with no trial. Identifying a **different**
+  user without a reset (`identify()`, `setUserContext({ id })`, or a
+  `hydrate()` payload for another user) now drops the previous user's trial
+  (both sources) and usage (reported balances and context `usage`) before
+  merging the new user's values. The new user's own values still apply. Going
+  from anonymous to identified, or re-identifying the same user, keeps what
+  is held. Reported usage was already cleared on reset; only the
+  switch-without-reset path leaked it.
+- **Lifecycle triggers.** `trial_midpoint`, `trial_expiring` and
+  `trial_expired` fired only from `getTrialStatus()` and
+  `setTrialInstances()`. The SDK now also runs the lifecycle evaluation
+  against the resolved trial view after every change that can move it:
+  `user.trial` at init, `update({ trial })`, `setUserContext`, a server
+  action's context, the client-context delivery, `hydrate()`, a reset, and a
+  Playbook load that turns the triggers on. The dedupe has not changed: a
+  stage fires only when it differs from the last stage seen. So an unchanged
+  trial, or both sources reporting the same threshold, fires once.
+  `enableTrialAutoTriggers: false` still silences them.
+- **`getUserContext()`** now includes `trial` (the resolved trial view, the
+  one placements and grants decide with), `tiers`, `payment_failed`,
+  `payment_at_risk` and `instances` when they are held. The snapshot is a
+  copy, so changing it does not change SDK state.
+
+The headless server ports are unaffected, and the cross-language parity
+corpus is untouched.
+
+**Proving test.** `web-sdk/trial-reset-lifecycle.test.ts`.
+
 ## 0.11.16
 
 ### Build fix, part two: the npm declaration build resolves `openapi-fetch` too (no API change)