# Froomle JavaScript SDK changelog

Customer-facing release notes for the `@froomle/frontend-sdk` npm package.

This changelog focuses on shipped SDK behavior, public APIs, and integration capabilities. It intentionally leaves out test-only, CI-only, and internal refactor details unless they changed runtime behavior.

## Unreleased

## 0.10.0 - 2026-09-10

- Automatic DOM and React page tracking now resumes after consent elevation without requiring an extra `trackCurrentPage()` call. Upgrading from anonymous tracking (level 1) to identified tracking (level 2) deliberately sends a new current-page observation. Repeated callbacks share delivery, manual integrations retain explicit page tracking, and consent changes never refetch or reprocess recommendation placements.
- Added `diagnostics.currentPageTracking` to inspect automatic tracking ownership, pending work, delivery status, consent and the latest consent transition.
- Integration note: automatic DOM/React integrations that send raw manual page events through `sendEvent(...)` after consent grant should remove that workaround or use `trackCurrentPage()` to avoid duplicate page events. The explicit helper shares deduplication with automatic tracking; arbitrary manual events do not.

## 0.9.0 - 2026-08-24

- Added opt-in selector-based identity resolution for declarative DOM benchmark control content. Script-tag integrations can read stable IDs and item types from existing CMS markup, while module integrations can configure one or more typed selector sources through `setBenchmarkControlIdentity(...)`. Existing `data-froomle-id` and `data-froomle-item-type` values remain authoritative, selector fallback runs only on resolved control branches, and missing or ambiguous identities fail closed with runtime diagnostics.

## 0.8.0 - 2026-08-16

- Added `trackCurrentPage()` for integrations whose consent state resolves after initial browser initialization. The explicit, idempotent helper sends the current `page_visit` or `detail_pageview` once after consent permits events, coalesces concurrent calls, remains retryable after blocked or failed attempts, and never reprocesses recommendation placements.

## 0.7.2 - 2026-08-12

- Fixed Froomle-managed benchmark attribution so recommendation requests and SDK-owned recommendation events omit `user_group` consistently, including anonymous consent levels `0` and `1`. The resolved response group remains available for rendering and diagnostics while Froomle assigns the version and group server-side.

## 0.7.1 - 2026-07-22
- No customer-facing SDK runtime or API changes in this release.

## 0.7.0 - 2026-07-22
- Added first-class `sendStartSubscription(...)` and `sendCancelSubscription(...)` helpers for npm/JS, React, and script-tag integrations. The helpers reuse SDK page, identity, consent, and navigation-safe event transport state; both infer configured item context when available while explicit extras remain authoritative.
- Fixed generic `sendEvent(...)` support for itemless `user_interaction`, `start_subscription`, `cancel_subscription`, and `batch_open` events. Item-bearing event contracts still require an explicit item, recommendation source, or configured context item.

## 0.6.4 - 2026-07-15
- Fixed browser recommendation requests so customer-domain and same-origin cookies are never sent to the Froomle API. Explicit recommendation bearer authentication remains supported and is only attached when configured.

## 0.6.3 - 2026-06-23
- Fixed declarative DOM/script-tag integrations so raw customer-authored `data-froomle-id` page content is no longer automatically sent as behavioral `histories.pageviews` on recommendation requests. Use `addHistories(...)` when pageview histories are intentional; use `addExclusions(...)`, request-level exclusions, or opt-in auto-exclusions for same-page recommendation deduplication.

## 0.6.2 - 2026-06-19
- No customer-facing SDK runtime or API changes in this release.

## 0.6.1 - 2026-06-19
- Added browser page/referrer source tracking for Events API payloads across script-tag/DOM, programmatic JS, React, manual event helpers, retail event helpers, and email campaign attribution. The SDK reads `window.location.href` with the URL fragment removed and the widely supported `document.referrer`, sends `page_url`, `referrer_url`, `referrer_type`, `referrer_origin`, and `referrer_domain` fields on Events API payloads only, keeps explicit event payload values authoritative, exposes `setReferrerTrackingEnabled(...)` / `data-froomle-referrer-tracking="false"` opt-outs, and surfaces state in `window.FroomleFrontendSdkRuntime.diagnostics.referrerTracking`.

## 0.6.0 - 2026-06-18
- Added first-class recommendation filter maps across programmatic `getRecommendations(...)`, `smartSort(...)`, `proxyReco(...)`, React hooks, and declarative HTML filters. Standard item metadata filters such as `item_type`, `categories`, `tags`, `access_type`, `flags`, inverse `not_*` filters, and backend-configured custom fields are now documented and covered while preserving the existing tuple and `data-froomle-reco-filter-*` forms.
- Added `site_context` support for Events API payloads across script-tag/DOM, programmatic JS, React, manual event helpers, retail event helpers, and email campaign attribution. Browser integrations now default it to `window.location.hostname` when available; integrations can override it with `setSiteContext(...)` or `data-froomle-site-context`, clear it with `setSiteContext("")`, and manual event extras can still override it per event.
- Added `subscription_level` support for Events API payloads across script-tag/DOM, programmatic JS, React, manual event helpers, retail event helpers, and email campaign attribution. Integrations can configure it with `setSubscriptionLevel(...)` or `data-froomle-subscription-level`; accepted values are `NONE`, `REGISTERED`, `TRIAL`, and `SUBSCRIPTION`, and recommendation request payloads remain unchanged.
- Added browser UTM tracking for Events API payloads across script-tag/DOM, programmatic JS, React, manual event helpers, retail event helpers, and email campaign attribution. The SDK reads standard UTM parameters from the current URL at event-send time, never adds them to recommendation requests, keeps explicit event payload values authoritative, exposes `setUtmTrackingEnabled(...)` / `data-froomle-utm-tracking="false"` opt-outs, and surfaces state in `window.FroomleFrontendSdkRuntime.diagnostics.utmTracking`.
- Fixed React list-based benchmark treatment tracking for `useRecoList(...).items`. When returned list items are rendered with `FroomleReco reco={item}`, automatic recommendation `impression` and `click_on_recommendation` events now keep the resolved recommendation attribution while omitting the treatment/Froomle `user_group` as intended.
- Fixed benchmark runtime diagnostics for treatment placements in React and declarative DOM integrations. Placements that render returned Froomle recommendation content now report `usedReturnedRecommendationContent: true` instead of incorrectly reporting `false`.

## 0.5.0 - 2026-05-18
- Added first-class smart sorting/reranking support for browser integrations. Programmatic JS can now call `smartSort(...)`, React can use `useSmartSort(...)`, and declarative DOM integrations can mark candidate containers with `data-froomle-smart-sort` so the SDK sends `list_content` candidate lists, maps returned Froomle items back to customer candidates, and keeps recommendation attribution metadata available for tracking.
- Smart sorting now participates in benchmark and exclusion contracts. Customer-managed control branches keep the original customer candidate order while preserving matched request attribution, treatment branches use the Froomle-returned order, and request-local/automatic exclusions are sent with smart-sort recommendation requests.
- Raw `getRecommendations(...)` continues to support explicit `list_content` lists for integrations that want to own response mapping themselves.
- Expanded browser runtime diagnostics with `window.FroomleFrontendSdkRuntime.diagnostics.smartSorting` so support can inspect the last smart-sorting surface, list name, candidate count, fixed-rank count, response count, unmatched candidate count, and related warnings.
- Added email campaign recommendation attribution for browser SDK integrations. Email links can carry Selligent/email-platform-friendly query parameters (`froomle_email_campaign_id`, `froomle_email_list_name`, `froomle_email_request_id`) or a compact `froomle_email_reco` payload; the SDK infers the clicked item from the landing page context and sends the Events API `batch_click_on_recommendation` event without bypassing the configured consent level.
- Added programmatic email campaign attribution helpers for SPA/router integrations: `trackEmailCampaignRecommendationClick(...)` and `trackEmailCampaignRecommendationClickFromUrl(...)`. The helpers support optional item/type/channel overrides, queue until page context is ready, deduplicate within the current tab session, and keep normal landing-page `detail_pageview` tracking separate.
- Expanded browser runtime diagnostics with `window.FroomleFrontendSdkRuntime.diagnostics.emailCampaignAttribution` so support can inspect detected payloads, pending/blocked/invalid/dispatched status, validation errors, duplicate suppression, and dispatch timing.

## 0.4.1 - 2026-05-05
- Fixed customer-managed benchmark `user_group` shaping for the control-vs-Froomle contract. Customer/control requests and recommendation events keep the configured control group, while treatment/Froomle requests and recommendation events omit `user_group` so backend version config can resolve treatment normally through `request_id` attribution.
- Fixed anonymous customer-managed benchmark treatment traffic so consent levels `0` and `1` keep `device_id: "no-consent"` and `version: "no-consent"` while omitting request-root `user_group` on the treatment/Froomle branch.
- Split anonymous-consent recommendation history handling: consent levels `0` and `1` still suppress behavioral pageview histories and raw custom `histories`, but request-local exclusions now continue to send `histories.exclude` entries with `reconsumable: false` for response deduplication, including automatic exclusions.
- Page-level events now use the global customer-managed benchmark group only for customer/control attribution and omit treatment/Froomle group attribution; per-placement React benchmark groups still stay scoped to recommendation-item events.

## 0.4.0 - 2026-04-30
- Added explicit in-page recommendation exclusion support for deduplication across mixed customer-rendered and Froomle-rendered page content. Public JS integrations can now use `addExclusions(...)`, `clearExclusions()`, and request-level `exclusions` to send `histories.exclude` entries with `reconsumable: false` on identified recommendation requests.
- Added opt-in automatic page exclusion collection for browser integrations. Script-tag/DOM, programmatic JS, and React `useRecoList(...)` / `useCreateReco(...)` / `useRecoEntry(...)` paths can collect stable page item IDs from configured selectors such as `data-froomle-id` and merge them into recommendation request exclusions.
- Added React `excludeItems` request adapters for `useRecoList(...)`, `useCreateReco(...)`, and `useRecoEntry(...)`. React/CMS integrations can pass their already-rendered item objects together with `getId(...)` and `itemType` / `getItemType(...)`; the SDK maps them to request-level exclusions without requiring DOM scanning.
- Expanded browser runtime diagnostics with `window.FroomleFrontendSdkRuntime.diagnostics.autoExclusions`, including the effective auto-exclusion config, request-batching split summaries, last collection surface/counts, last sent exclusions with diagnostics-only origin/source attribution, and auto-exclusion warnings. Auto-exclusions remain disabled by default and histories/exclusions are still suppressed under consent levels `0` and `1`.

## 0.3.0 - 2026-04-27
- Breaking React benchmark API change: replaced the short-lived top-level `control` / `controlItems` + `data` control shape with raw-item benchmark entries. React control-aware benchmarking now uses `benchmark.controlItem` / `benchmark.controlItems` adapters, `useRecoList(...).entries`, `useRecoEntry(...)`, and `FroomleReco entry={entry}` so applications can render their own CMS items unchanged while the SDK keeps recommendation attribution.
- Benchmark rendering now follows the resolved `user_group` strictly across DOM and React. Customer/control branches render provided customer content and ignore returned Froomle items by default; treatment/Froomle branches render returned Froomle items or empty responses.
- Existing non-benchmarked Froomle-only React rendering remains supported: `useRecoList(...).items`, `useCreateReco(...)`, and `FroomleReco reco={item}` keep their standard returned-recommendation behavior.

## 0.2.4 - 2026-04-23
- Fixed no-consent customer-managed benchmarking for recommendation requests. Under consent level `0` or `1`, customer-managed benchmark traffic now keeps the configured request-root `user_group` while recommendation identity stays anonymous (`device_id: "no-consent"`, `version: "no-consent"`, no `user_id`, no histories).
- Clarified the benchmark override and batching contract, including precedence between global defaults and per-request/per-block overrides plus the rule that different effective benchmark configs split into separate outgoing recommendation requests.

## 0.2.3 - 2026-04-20
- Expanded the browser runtime diagnostics config with the effective recommendation request endpoint. `window.FroomleFrontendSdkRuntime.diagnostics.config.requestDomain` now exposes the configured request host, and `window.FroomleFrontendSdkRuntime.diagnostics.config.requestOrigin` exposes the effective `http` or `https` origin derived from that host and the SDK transport mode.
- This makes custom-domain, proxy, and CNAME browser integrations easier to inspect and support without inferring the request target indirectly from page markup or network heuristics.

## 0.2.2 - 2026-04-18
- Script-tag/global integrations now keep the live SDK `<script>` element aligned with late setter calls for `consent`, `user_id`, and `channel`. This applies both in `froomle:before-init` and in later same-page updates, which makes support/debug inspection less misleading after runtime changes.
- Clarified the script-tag DOM contract for browser diagnostics. `window.FroomleFrontendSdkRuntime` remains the canonical live runtime state, while `data-froomle-device-id` stays an explicit customer override input and is not backfilled from SDK-managed browser identity.

## 0.2.1 - 2026-04-17
- Fixed benchmark request grouping for declarative DOM placements. Compatible multi-list benchmark placements now keep batching into a single outgoing recommendation request instead of being split into one request per list.
- Fixed automatic recommendation impression activation after benchmark/control rendering in React. Slot-based and list-based `FroomleReco` wrappers now keep sending automatic `impression` events correctly once resolved request metadata is stamped on the rendered item.

## 0.2.0 - 2026-04-17
- Expanded the browser runtime diagnostics contract. `window.FroomleFrontendSdkRuntime.integration` now keeps ordered observed `sources` together with `lastSource`, `window.FroomleFrontendSdkDiagnostics` aliases that integration state for faster support/debug inspection, and `window.FroomleFrontendSdkRuntime.diagnostics` now exposes effective config, device-id provenance/warnings, lifecycle support flags, and recent recommendation/event traffic state for supported DOM, React/framework, and public programmatic SDK usage.
- Added cross-page and cross-tab `device_id` continuity diagnostics to the browser runtime. `window.FroomleFrontendSdkRuntime.diagnostics.config.deviceIdContinuity` now reports whether the current identifier stayed stable, changed, or was re-created after an anonymous interval, including for customer-supplied device IDs that enter the SDK through supported public paths such as `setDeviceId(...)` or `data-froomle-device-id`. To make those comparisons possible across reloads and tabs, the SDK now stores a small diagnostics-only continuity snapshot in browser `localStorage`; it is not sent to the backend and is not used for recommendation or event tracking behavior.
- Clarified browser loading diagnostics so `inferredLoadingMode` now reports only real script/bootstrap modes (`blocking`, `defer`, `async`, `custom`). The `froomle:before-init` / `froomle:init` event-driven pattern remains supported, but is documented and tested as hook orchestration rather than as a separate loading mode.
- Fixed SDK-managed `device_id` continuity for JS/React integrations that apply consent through the public setters. When an existing `froomle_device_id` cookie is already present, reloading a consented page no longer rotates the identifier.
- Fixed consent-transition identity handling so dropping from consent level `2` to `0` or `1` returns the SDK to anonymous `no-consent` identity, and returning to consent level `2` after an anonymous interval creates a fresh identified `device_id` instead of silently reviving the previous one.
- Added first-class benchmark request configuration for JS, script-tag/DOM, and React integrations. Public SDK users can now configure benchmarking through `setBenchmark(...)`, `getBenchmark()`, `clearBenchmark()`, `getRecommendations(..., { benchmark })`, and the `benchmark` option on `useRecoList(...)` / `useCreateReco(...)`, with support for both `customer-managed` and `froomle-managed` split models plus configurable control/treatment group names.
- Benchmark context now participates in request shaping and grouping. `customer-managed` requests inject `user_group` at the request root, `froomle-managed` requests leave it out, and placements with different benchmark contexts no longer batch into the same outgoing recommendation request.
- Added benchmark-aware control/treatment rendering for DOM placeholders and React recommendation hooks. On the control branch, usable customer-provided content can stay in place; when configured control content is unusable, the SDK now fails open to returned Froomle recommendation items instead of blanking the slot.
- Automatic recommendation tracking is now activated only after the SDK stamps resolved request metadata onto a rendered item. Raw customer-authored `data-froomle-id` still works as generic item identity and history input, but it no longer triggers automatic recommendation `impression` / `click_on_recommendation` events by itself.
- `sendEvent(...)` now supports source-based recommendation attribution through `sendEvent(..., { source })`. When the source element is inside a rendered recommendation/control node, the SDK can infer `action_item`, `action_item_type`, `list_name`, `request_id`, and `user_group` automatically, while automatic page-level events still stay free of benchmark group attribution.

## 0.1.6 - 2026-04-13
- Added `window.FroomleFrontendSdkRuntime` as the public browser runtime object. It exposes integration ownership/observed usage (`primaryMode`, `observedModes`, `lastSource`) together with the scoped DOM init lifecycle (`status`, `trigger`, `error`, `ready`) in one place for support/debugging.
- `window.FroomleFrontendSdkReady` now maps directly to `window.FroomleFrontendSdkRuntime.init.ready`, so browser integrations have one consistent readiness source of truth while keeping the existing promise-based hook available.
- Fixed DOM/script-tag initialization on pages without any `data-froomle-reco` placeholders, so `froomle:init`, `FroomleFrontendSdkReady`, and manual `init()` no longer remain stuck pending in those no-placeholder flows.
- DOM initialization failures during recommendation loading now surface as `init.status = "failed"` with a populated runtime error and a rejected readiness promise instead of hanging indefinitely.

## 0.1.5 - 2026-04-09
- Restored manual `sendEvent(...)` support for page-level `page_visit` events without a `context_item`, so custom programmatic integrations can keep sending homepage/category page visits after only setting `page_type`.

## 0.1.4 - 2026-04-08
- Fixed repeated filter-key handling in grouped recommendation requests. When the same filter key is supplied multiple times through React hooks or grouped programmatic recommendation flows, the SDK now preserves all values in order instead of silently keeping only the last one.
- Clarified the request contract for multi-value inputs: repeated filter keys merge into arrays, while custom variables only become arrays when an explicit array value is passed.

## 0.1.3 - 2026-04-07
- Programmatic/manual event delivery now uses navigation-safe browser transport defaults (`keepalive` with beacon fallback), so custom `sendEvent(...)` usage and the dedicated retail helpers are less likely to be dropped during page navigation.

## 0.1.2 - 2026-04-02
- Added `asChild` support to `FroomleReco` so React integrations can preserve the child card/article root instead of inserting an extra wrapper `<div>` when the layout depends on that DOM structure.
- Automatic `impression` and `click_on_recommendation` tracking remains supported in this preserved-root mode, so layout-sensitive React integrations can stay seamless without giving up item-level tracking.

## 0.1.1 - 2026-03-30
- Added `useRecoList(...)` for parent-owned list rendering in React. This hook fetches one recommendation list per call, returns all resolved items together, and lets you keep automatic `impression` and `click_on_recommendation` tracking by wrapping each returned item in `FroomleReco`.

## 0.1.0 - 2026-03-27
- JS/TS module imports are now side-effect free. Module-based DOM placeholder integrations that rely on `data-froomle-*` attributes must now call `init()` explicitly after their SDK setters. Script-tag/global integrations keep their existing auto-init behavior.
- React integrations no longer trigger duplicate recommendation requests or duplicate automatic page-level events by overlapping with the declarative DOM integration path.
- Framework-managed recommendation wrappers now mark their own DOM ownership so declarative DOM filling ignores React-managed recommendation blocks instead of treating them as raw HTML placeholders.
- Removed the undocumented `RecoBackendV2` and `DomDomDom` exports from the shipped JS/global surfaces. Public integrations should use the documented root SDK APIs instead.
- Removed the undocumented `RecommendationList` and `Recommendations` constructors from the shipped root/global SDK surfaces. Use `getRecommendations(...)` directly and work with its returned object instead of importing SDK constructor names.

## 0.0.30 - 2026-03-25
- Improved compatibility for `@froomle/frontend-sdk/react` imports in older CommonJS and legacy TypeScript toolchains by adding a dedicated React compatibility entry alongside package exports.

## 0.0.29 - 2026-03-24
- Added the `defaultField(...)` HTML transform so placeholder bindings can fall back to another recommendation field when the primary value is empty.

## 0.0.28 - 2026-03-20
- Added manual retail event helpers for JS and React integrations: `sendItemInteraction`, `sendUserInteraction`, `sendAddToCart`, `sendRemoveFromCart`, and `sendPurchase`.
- These helpers reuse the current SDK context and consent rules so retail events can be sent without assembling raw event payloads by hand.

## 0.0.27 - 2026-03-12
- Added explicit click `action_item_type` overrides via `data-froomle-action-item-type`, so click events can report a different item type than the surrounding recommendation container.

## 0.0.26 - 2026-03-12
- Added the `X-Froomle-Client: frontend-sdk/<version>` header to outgoing recommendation and event requests.
- Unified event delivery through a shared transport layer so page visits, detail views, clicks, and impressions follow the same request behavior.

## 0.0.25 - 2026-03-11
- Added bearer-token support for recommendation requests through `setRecommendationsBearer(...)`, `clearRecommendationsBearer()`, `setRecommendationsBearerProvider(...)`, and `clearRecommendationsBearerProvider()`.
- Added token-provider refresh and retry support so protected recommendation APIs can recover from expired tokens.

## 0.0.24 - 2026-03-10
- HTML `data-froomle-reco-filter-*` and `data-froomle-variable-*` attributes can now carry array values via JSON or `;`-separated syntax.
- Single values now stay single values instead of being automatically coerced into arrays.

## 0.0.22 - 2026-03-08
- Added the `froomle:before-init` browser event for script-tag integrations.
- This event fires before auto-init work starts, so consent, user, and page-context setters can run before the first automatic request.

## 0.0.21 - 2026-03-08
- Added explicit and event-driven initialization for the script-tag SDK.
- Added `init()` for manual startup.
- Exposed post-init readiness through the `froomle:init` event and the global `FroomleFrontendSdkReady` promise, while preserving normal auto-init behavior.

## 0.0.20 - 2026-02-26
- Added inline expressions and template interpolation for HTML `data-froomle-param-*` bindings.
- Added built-in value transforms for HTML mappings, including `replace`, `prepend`, `append`, `default`, `trim`, `lower`, `upper`, and `urlencode`.

## 0.0.18 - 2026-02-25
- Improved asynchronous error handling so recommendation and order request failures can reject cleanly instead of leaving callers waiting indefinitely.
- React wrappers now keep their lifecycle moving even when recommendation resolution fails, which makes failure behavior more predictable.

## 0.0.17 - 2026-02-25
- `addHistories(...)` now accepts either plain item IDs or full history objects with explicit item types.
- Added a default item-type fallback so mixed history inputs can still be normalized into the request payload.

## 0.0.16 - 2026-02-24
- Added automatic filling and impression tracking for recommendation blocks inserted or updated after the initial page load.
- Removed the older `pageView` API path in favor of the newer page/context tracking model.

## 0.0.15 - 2026-02-23
- Introduced a 3-level consent model that separates no tracking, device-only tracking, and full tracking with user identity.
- Added configurable `channel` support across requests and events.
- Replaced the older detail-page `pageView` model with `context_item` and `context_item_type`.
- Improved page-visit, detail-view, and click event payloads so they respect consent and include richer context.

## 0.0.14 - 2026-02-23
- Standardized `user_group` propagation from recommendation responses into rendered items and follow-up events.
- Recommendation proxies and React wrappers now preserve `user_group` consistently, even when it is only returned at response level.

## 0.0.13 - 2026-02-23
- Added support for multiple filters per recommendation list.
- Added support for array-valued filters in recommendation requests.
- Added consent-aware event tracking and `user_group` propagation for page visits, detail views, impressions, and recommendation clicks across HTML and React integrations.
- Added `setPageView(...)` for detail-page tracking in this release line. This was later replaced by the context-item model introduced in `0.0.15` and finalized in `0.0.16`.

## 0.0.12 - 2026-02-19
- Added React 19 compatibility to the React package peer dependency range.

## 0.0.11 - 2026-02-18
- Introduced the first full public JS package structure with modular JS entrypoints.
- Added the framework-agnostic proxy recommendation flow built around `proxyReco(...)` and `fulfillRecommendations()`.
- Added the first full React helper layer with `FroomleSdkInit`, `FroomleReco`, `useReco`, and `useCreateReco`.
- Added custom-item and order helpers for React integrations.
- Added refreshed raw, HTML, and React sample apps.

## 0.0.9 - 2025-12-15
- Added script-tag generation helpers and channel support for server-rendered integrations.
- Improved legacy ordering and recommendation demo templates.

## 0.0.5 - 2025-12-01
- No customer-facing JavaScript SDK runtime or API changes in this release.

## 0.0.4 - 2025-12-01
- No customer-facing JavaScript SDK runtime or API changes in this release.

## v0.0.1-alpha.0 - 2025-12-01
- First alpha release of the new frontend SDK monorepo.
- Shipped the shared core with the initial JavaScript target.
- Added early recommendation filling, impression handling, history support,
  ordering support, and sample HTML and React Native integrations.