@traffical/js-client 0.17.0 → 0.19.0

package/README.md

@@ -29,7 +29,7 @@ const traffical = await createTrafficalClient({
   orgId: 'org_xxx',
   projectId: 'proj_xxx',
   env: 'production',
-  apiKey: 'pk_xxx',
+  apiKey: 'traffical_pk_…',
 });
 
 // Get parameters
@@ -67,7 +67,7 @@ traffical.track('checkout_complete', { value: 1 }, { decisionId: decision.decisi
     orgId: 'org_xxx',
     projectId: 'proj_xxx',
     env: 'production',
-    apiKey: 'pk_xxx',
+    apiKey: 'traffical_pk_…',
   }).then(function(traffical) {
     var params = traffical.getParams({
       context: { userId: 'user_123' },
@@ -167,7 +167,7 @@ The Traffical DevTools debug plugin uses these methods to let developers force p
 ## Features
 
 - **Error Boundary** - SDK errors never crash your app
-- **Exposure Deduplication** - Same user/variant = 1 exposure per session
+- **Exposure Deduplication** - Same user/allocation = 1 exposure event per session
 - **Smart Batching** - Events batched and flushed efficiently
 - **Beacon on Unload** - Events sent reliably on page close
 - **Auto Stable ID** - Anonymous user identification via localStorage/cookie
@@ -187,7 +187,7 @@ const traffical = await createTrafficalClient({
   orgId: 'org_xxx',
   projectId: 'proj_xxx',
   env: 'production',
-  apiKey: 'pk_xxx',
+  apiKey: 'traffical_pk_…',
   plugins: [
     createDOMBindingPlugin({
       observeMutations: true,  // Watch for DOM changes (SPA support)
@@ -218,7 +218,7 @@ The plugin:
 
 ### Redirect Plugin
 
-Run URL split tests (redirect experiments) where visitors are redirected to different landing page variants. The redirect plugin automatically triggers a decision on init, performs the redirect, and sets an attribution cookie. The attribution plugin ensures conversions on the variant page are attributed back to the experiment.
+Run URL split tests (redirect policies) where visitors are redirected to different landing page allocations. The redirect plugin automatically triggers a decision on init, performs the redirect, and sets an attribution cookie. The attribution plugin ensures conversions on the destination page are attributed back to the policy.
 
 ```typescript
 import {
@@ -231,7 +231,7 @@ const traffical = await createTrafficalClient({
   orgId: 'org_xxx',
   projectId: 'proj_xxx',
   env: 'production',
-  apiKey: 'pk_xxx',
+  apiKey: 'traffical_pk_…',
   plugins: [
     createRedirectPlugin(),
     createRedirectAttributionPlugin(),
@@ -242,7 +242,7 @@ const traffical = await createTrafficalClient({
 // On entry pages, it redirects. On other pages, it's a no-op.
 
 // Track goals as usual — the attribution plugin injects
-// redirect experiment metadata into every track() call.
+// redirect policy metadata into every track() call.
 traffical.track('add_to_cart', { value: 29.99 });
 ```
 
@@ -281,9 +281,9 @@ Track goal events from a separate GTM tag (e.g., triggered on "Add to Cart" clic
 
 1. **Init** — The redirect plugin's `onInitialize` hook receives the client and calls `decide()` automatically.
 
-2. **Entry page** — `onBeforeDecision` injects `url.pathname` into the context. The policy condition (e.g., `url.pathname startsWith /products/pillow`) matches, `redirect.url` resolves to the variant URL. `onDecision` writes an attribution cookie (`traffical_rdr`) and calls `window.location.replace()`.
+2. **Entry page** — `onBeforeDecision` injects `url.pathname` into the context. The policy condition (e.g., `url.pathname startsWith /products/pillow`) matches, `redirect.url` resolves to the allocation's URL. `onDecision` writes an attribution cookie (`traffical_rdr`) and calls `window.location.replace()`.
 
-3. **Variant page** — The SDK loads again, `decide()` runs, but the policy condition doesn't match the new URL, so `redirect.url` stays empty and no redirect happens. The redirect-attribution plugin reads the `traffical_rdr` cookie and injects the experiment metadata into every `track()` call.
+3. **Destination page** — The SDK loads again, `decide()` runs, but the policy condition doesn't match the new URL, so `redirect.url` stays empty and no redirect happens. The redirect-attribution plugin reads the `traffical_rdr` cookie and injects the policy metadata into every `track()` call.
 
 #### Configuration
 
@@ -310,6 +310,62 @@ The redirect plugin automatically adds these context fields:
 
 Use `url.pathname` in policy conditions to target specific pages.
 
+### Auto Attributes Plugin
+
+Opt-in plugin that derives browser, page, UTM and locale attributes and injects them into every decision context via `onBeforeDecision` (the same hook the redirect plugin uses). All keys live in the reserved `$` namespace so they never collide with your own context keys. The dashboard registers them as **system attributes** (`managedBy: system`, source `plugin:web`), so they appear in the condition editor's key picker as soon as the plugin is in use.
+
+```typescript
+import { createTrafficalClient, autoAttributesPlugin } from '@traffical/js-client';
+
+const traffical = await createTrafficalClient({
+  orgId: 'org_xxx',
+  projectId: 'proj_xxx',
+  env: 'production',
+  apiKey: 'traffical_pk_…',
+  plugins: [autoAttributesPlugin()],
+});
+```
+
+Via the CDN build: `Traffical.autoAttributesPlugin()` (`Traffical.createAutoAttributesPlugin` is an alias).
+
+#### Keys
+
+| Key | Type | Values / source |
+|-----|------|-----------------|
+| `$browser` | enum | `chrome`, `edge`, `firefox`, `safari`, `other` — UA class only, no versions |
+| `$os` | enum | `ios`, `android`, `macos`, `windows`, `linux`, `other` — UA class; iPadOS desktop UAs are detected via touch points |
+| `$device_type` | enum | `mobile`, `tablet`, `desktop` — UA class first; desktop-class UAs with a coarse pointer fall back to width (`< 768` mobile, `< 1024` tablet) |
+| `$url` | string (url) | `location.href` |
+| `$host` | string | `location.host` |
+| `$path` | string | `location.pathname` |
+| `$query` | string | `location.search` without the leading `?`; omitted when empty |
+| `$referrer` | string | `document.referrer`; omitted when empty |
+| `$page_title` | string | `document.title`; omitted when empty |
+| `$utm_source`, `$utm_medium`, `$utm_campaign`, `$utm_term`, `$utm_content` | string | From the query string; persisted in `sessionStorage` (`traffical:utm`) and re-read on later pages of the session whose URL has none |
+| `$locale` | string | `navigator.language` (BCP 47, e.g. `en-GB`) |
+| `$timezone` | string | `Intl.DateTimeFormat().resolvedOptions().timeZone` (IANA, e.g. `Europe/Berlin`) |
+
+Rules:
+
+- **Caller wins.** Context you pass to `decide()` / `getParams()` overrides any derived key of the same name.
+- **Nothing empty.** A key that cannot be derived is omitted, never sent as `""`.
+- **Re-derived on every decision**, so SPA navigation is covered without patching `history`.
+- **SSR-safe.** Without a `window` the context passes through untouched.
+
+#### Configuration
+
+```typescript
+autoAttributesPlugin({
+  include?: AutoAttributeKey[],  // only derive these keys (default: all)
+  exclude?: AutoAttributeKey[],  // never derive these keys (applied after include)
+  persistUtm?: boolean,          // default true — sessionStorage-backed utm persistence
+});
+```
+
+`AUTO_ATTRIBUTE_KEYS` (the full key list) and the `AutoAttributeKey` type are exported for building `include` / `exclude` lists.
+
+Mobile SDKs emit the same `$` keys from their device-info providers (`$os`, `$os_version`, `$app_version`, `$locale`, `$timezone`, `$device_model`, `$device_type`): `DefaultDeviceInfoProvider` on iOS and `defaultDeviceInfoProvider` in `@traffical/react-native`.
+
 ## Type-Safe Event Tracking
 
 Use `@traffical/cli generate-types` to generate TypeScript interfaces for your event schemas. This lets you create a strictly typed `track` function that catches invalid event names and properties at compile time.

package/dist/client.d.ts

@@ -151,7 +151,7 @@ export interface TrafficalClientOptions {
     disableCloudEvents?: boolean;
     /**
      * When true, assignment logger calls are deduplicated per session
-     * (same unit+policy+variant won't fire again). Default: true.
+     * (same unit+policy+allocation won't fire again). Default: true.
      */
     deduplicateAssignmentLogger?: boolean;
     /**
@@ -275,7 +275,7 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
     decide<T extends Record<string, ParameterValue>>(options: DecideOptions<T>): DecisionResult;
     /**
      * Tracks an exposure event.
-     * Automatically deduplicates exposures for the same user/variant.
+     * Automatically deduplicates exposure events for the same user/allocation.
      *
      * Skips layers marked `attributionOnly` — those were resolved for
      * attribution/assignment purposes only (no parameters were requested
@@ -419,7 +419,7 @@ export declare class TrafficalClient<TEvents extends TrackEventMap = TrackEventM
      * - "cumulative": Collects layers from ALL cached decisions for this unit,
      *   deduplicated by layerId:policyId (last-write-wins). This ensures cross-page
      *   funnels (e.g., catalog -> PDP -> checkout) attribute correctly to all
-     *   experiments the user is exposed to. For per-entity dynamic allocation
+     *   policies the user is exposed to. For per-entity dynamic allocation
      *   policies, only the most recent allocation is kept to avoid attributing
      *   rewards to allocations from other entities (e.g., different products).
      *

package/dist/client.js

@@ -464,7 +464,7 @@ export class TrafficalClient {
     // ===========================================================================
     /**
      * Tracks an exposure event.
-     * Automatically deduplicates exposures for the same user/variant.
+     * Automatically deduplicates exposure events for the same user/allocation.
      *
      * Skips layers marked `attributionOnly` — those were resolved for
      * attribution/assignment purposes only (no parameters were requested
@@ -1065,7 +1065,7 @@ export class TrafficalClient {
      * - "cumulative": Collects layers from ALL cached decisions for this unit,
      *   deduplicated by layerId:policyId (last-write-wins). This ensures cross-page
      *   funnels (e.g., catalog -> PDP -> checkout) attribute correctly to all
-     *   experiments the user is exposed to. For per-entity dynamic allocation
+     *   policies the user is exposed to. For per-entity dynamic allocation
      *   policies, only the most recent allocation is kept to avoid attributing
      *   rewards to allocations from other entities (e.g., different products).
      *

package/dist/exposure-dedup.d.ts

@@ -1,7 +1,7 @@
 /**
  * ExposureDeduplicator - Prevents duplicate exposure events.
  *
- * Same user seeing same variant should only count as 1 exposure.
+ * Same user seeing the same allocation should only count as 1 exposure.
  * Uses session-based deduplication with localStorage persistence.
  */
 import type { StorageProvider } from "./storage.js";

package/dist/exposure-dedup.js

@@ -1,7 +1,7 @@
 /**
  * ExposureDeduplicator - Prevents duplicate exposure events.
  *
- * Same user seeing same variant should only count as 1 exposure.
+ * Same user seeing the same allocation should only count as 1 exposure.
  * Uses session-based deduplication with localStorage persistence.
  */
 const STORAGE_KEY = "exposure_dedup";

package/dist/global.d.ts

@@ -18,6 +18,7 @@ import { createDOMBindingPlugin, type DOMBindingPlugin, type DOMBindingPluginOpt
 import { createRedirectPlugin, type RedirectPluginOptions } from "./plugins/redirect.js";
 import { createRedirectAttributionPlugin, type RedirectAttributionPluginOptions } from "./plugins/redirect-attribution.js";
 import { createDebugPlugin, type DebugPluginOptions } from "./plugins/debug.js";
+import { autoAttributesPlugin, createAutoAttributesPlugin, AUTO_ATTRIBUTE_KEYS, type AutoAttributeKey, type AutoAttributesPluginOptions } from "./plugins/auto-attributes.js";
 /**
  * Initialize the Traffical client (async).
  * Returns the client instance.
@@ -37,5 +38,5 @@ declare function instance(): TrafficalClient | null;
  * Destroy the singleton instance.
  */
 declare function destroy(): void;
-export { init, initSync, instance, destroy, TrafficalClient, type TrafficalClientOptions, type TrafficalPlugin, createDOMBindingPlugin, type DOMBindingPlugin, type DOMBindingPluginOptions, createRedirectPlugin, type RedirectPluginOptions, createRedirectAttributionPlugin, type RedirectAttributionPluginOptions, createDebugPlugin, type DebugPluginOptions, };
+export { init, initSync, instance, destroy, TrafficalClient, type TrafficalClientOptions, type TrafficalPlugin, createDOMBindingPlugin, type DOMBindingPlugin, type DOMBindingPluginOptions, createRedirectPlugin, type RedirectPluginOptions, createRedirectAttributionPlugin, type RedirectAttributionPluginOptions, createDebugPlugin, type DebugPluginOptions, autoAttributesPlugin, createAutoAttributesPlugin, AUTO_ATTRIBUTE_KEYS, type AutoAttributeKey, type AutoAttributesPluginOptions, };
 //# sourceMappingURL=global.d.ts.map

package/dist/global.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EAGf,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,+BAA+B,EAC/B,KAAK,gCAAgC,EACtC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAK5B;;;GAGG;AACH,iBAAe,IAAI,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAQ7E;AAED;;;GAGG;AACH,iBAAS,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAclE;AAED;;;GAGG;AACH,iBAAS,QAAQ,IAAI,eAAe,GAAG,IAAI,CAE1C;AAED;;GAEG;AACH,iBAAS,OAAO,IAAI,IAAI,CAKvB;AAGD,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EAEpB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAE5B,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,+BAA+B,EAC/B,KAAK,gCAAgC,EAErC,iBAAiB,EACjB,KAAK,kBAAkB,GACxB,CAAC"}
+{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EAGf,KAAK,sBAAsB,EAC5B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC7B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,EACpB,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,+BAA+B,EAC/B,KAAK,gCAAgC,EACtC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EACjC,MAAM,8BAA8B,CAAC;AAKtC;;;GAGG;AACH,iBAAe,IAAI,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAQ7E;AAED;;;GAGG;AACH,iBAAS,QAAQ,CAAC,OAAO,EAAE,sBAAsB,GAAG,eAAe,CAclE;AAED;;;GAGG;AACH,iBAAS,QAAQ,IAAI,eAAe,GAAG,IAAI,CAE1C;AAED;;GAEG;AACH,iBAAS,OAAO,IAAI,IAAI,CAKvB;AAGD,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EAEpB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAE5B,oBAAoB,EACpB,KAAK,qBAAqB,EAC1B,+BAA+B,EAC/B,KAAK,gCAAgC,EAErC,iBAAiB,EACjB,KAAK,kBAAkB,EAEvB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,GACjC,CAAC"}

package/dist/global.js

@@ -17,6 +17,7 @@ import { createDOMBindingPlugin, } from "./plugins/dom-binding.js";
 import { createRedirectPlugin, } from "./plugins/redirect.js";
 import { createRedirectAttributionPlugin, } from "./plugins/redirect-attribution.js";
 import { createDebugPlugin, } from "./plugins/debug.js";
+import { autoAttributesPlugin, createAutoAttributesPlugin, AUTO_ATTRIBUTE_KEYS, } from "./plugins/auto-attributes.js";
 // Global state for singleton pattern
 let _instance = null;
 /**
@@ -70,5 +71,7 @@ createDOMBindingPlugin,
 // Redirect plugins
 createRedirectPlugin, createRedirectAttributionPlugin, 
 // Debug plugin
-createDebugPlugin, };
+createDebugPlugin, 
+// Auto attributes plugin
+autoAttributesPlugin, createAutoAttributesPlugin, AUTO_ATTRIBUTE_KEYS, };
 //# sourceMappingURL=global.js.map

package/dist/global.js.map

@@ -1 +1 @@
-{"version":3,"file":"global.js","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,GAE1B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,sBAAsB,GAGvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,GAErB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,+BAA+B,GAEhC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,GAElB,MAAM,oBAAoB,CAAC;AAE5B,qCAAqC;AACrC,IAAI,SAAS,GAA2B,IAAI,CAAC;AAE7C;;;GAGG;AACH,KAAK,UAAU,IAAI,CAAC,OAA+B;IACjD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CAAC,IAAI,CAAC,sEAAsE,CAAC,CAAC;QACrF,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,SAAS,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CAAC,OAA+B;IAC/C,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CAAC,IAAI,CAAC,sEAAsE,CAAC,CAAC;QACrF,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,SAAS,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAC;IAE/C,2CAA2C;IAC3C,SAAS,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACrC,OAAO,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ;IACf,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAS,OAAO;IACd,IAAI,SAAS,EAAE,CAAC;QACd,SAAS,CAAC,OAAO,EAAE,CAAC;QACpB,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;AACH,CAAC;AAED,qCAAqC;AACrC,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,eAAe;AAGf,qBAAqB;AACrB,sBAAsB;AAGtB,mBAAmB;AACnB,oBAAoB,EAEpB,+BAA+B;AAE/B,eAAe;AACf,iBAAiB,GAElB,CAAC"}
+{"version":3,"file":"global.js","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,GAE1B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,sBAAsB,GAGvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,oBAAoB,GAErB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,+BAA+B,GAEhC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EACL,iBAAiB,GAElB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,GAGpB,MAAM,8BAA8B,CAAC;AAEtC,qCAAqC;AACrC,IAAI,SAAS,GAA2B,IAAI,CAAC;AAE7C;;;GAGG;AACH,KAAK,UAAU,IAAI,CAAC,OAA+B;IACjD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CAAC,IAAI,CAAC,sEAAsE,CAAC,CAAC;QACrF,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,SAAS,GAAG,MAAM,qBAAqB,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CAAC,OAA+B;IAC/C,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CAAC,IAAI,CAAC,sEAAsE,CAAC,CAAC;QACrF,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,SAAS,GAAG,yBAAyB,CAAC,OAAO,CAAC,CAAC;IAE/C,2CAA2C;IAC3C,SAAS,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACrC,OAAO,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ;IACf,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,SAAS,OAAO;IACd,IAAI,SAAS,EAAE,CAAC;QACd,SAAS,CAAC,OAAO,EAAE,CAAC;QACpB,SAAS,GAAG,IAAI,CAAC;IACnB,CAAC;AACH,CAAC;AAED,qCAAqC;AACrC,OAAO,EACL,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,eAAe;AAGf,qBAAqB;AACrB,sBAAsB;AAGtB,mBAAmB;AACnB,oBAAoB,EAEpB,+BAA+B;AAE/B,eAAe;AACf,iBAAiB;AAEjB,yBAAyB;AACzB,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,GAGpB,CAAC"}

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  *
  * Features:
  * - Error boundary wrapping (P0) - SDK errors never crash your app
- * - Exposure deduplication (P0) - Same user/variant = 1 exposure
+ * - Exposure deduplication (P0) - Same user/allocation = 1 exposure event
  * - Smart event batching (P1) - Batches events, uses sendBeacon on unload
  * - Plugin system (P2) - Extensible via plugins
  * - DOM binding plugin - Auto-apply parameters to DOM elements
@@ -46,5 +46,6 @@ export { type LifecycleProvider, type VisibilityState, type VisibilityCallback,
 export { PluginManager, type TrafficalPlugin, type PluginOptions } from "./plugins/index.js";
 export { createDOMBindingPlugin, type DOMBindingPlugin, type DOMBindingPluginOptions, } from "./plugins/dom-binding.js";
 export { createWarehouseNativeLoggerPlugin, createWarehouseNativeLogger, type WarehouseNativeLoggerOptions, type JitsuDestination, type AnalyticsLike, } from "./plugins/warehouse-native-logger.js";
+export { autoAttributesPlugin, createAutoAttributesPlugin, AUTO_ATTRIBUTE_KEYS, type AutoAttributeKey, type AutoAttributesPluginOptions, type AutoBrowser, type AutoOS, type AutoDeviceType, } from "./plugins/auto-attributes.js";
 export { createDebugPlugin, type DebugPluginOptions, type TrafficalDebugRegistry, type TrafficalDebugInstance, type DebugState, type DebugEvent, type RegistryEvent, } from "./plugins/debug.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,cAAc,iBAAiB,CAAC;AAGhC,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AAGrB;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG7F,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,iCAAiC,EACjC,2BAA2B,EAC3B,KAAK,4BAA4B,EACjC,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,cAAc,iBAAiB,CAAC;AAGhC,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,EACzB,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC;AAGrB;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAGtB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG7F,OAAO,EACL,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EACL,iCAAiC,EACjC,2BAA2B,EAC3B,KAAK,4BAA4B,EACjC,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,EACnB,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAChC,KAAK,WAAW,EAChB,KAAK,MAAM,EACX,KAAK,cAAc,GACpB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,GACnB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -5,7 +5,7 @@
  *
  * Features:
  * - Error boundary wrapping (P0) - SDK errors never crash your app
- * - Exposure deduplication (P0) - Same user/variant = 1 exposure
+ * - Exposure deduplication (P0) - Same user/allocation = 1 exposure event
  * - Smart event batching (P1) - Batches events, uses sendBeacon on unload
  * - Plugin system (P2) - Extensible via plugins
  * - DOM binding plugin - Auto-apply parameters to DOM elements
@@ -54,6 +54,8 @@ export { PluginManager } from "./plugins/index.js";
 export { createDOMBindingPlugin, } from "./plugins/dom-binding.js";
 // Export warehouse-native logger
 export { createWarehouseNativeLoggerPlugin, createWarehouseNativeLogger, } from "./plugins/warehouse-native-logger.js";
+// Export auto-attributes plugin ($-prefixed web context keys)
+export { autoAttributesPlugin, createAutoAttributesPlugin, AUTO_ATTRIBUTE_KEYS, } from "./plugins/auto-attributes.js";
 // Export debug plugin
 export { createDebugPlugin, } from "./plugins/debug.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,iCAAiC;AACjC,cAAc,iBAAiB,CAAC;AAEhC,6CAA6C;AAC7C,cAAc,oBAAoB,CAAC;AAEnC,gBAAgB;AAChB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,GAE1B,MAAM,aAAa,CAAC;AAErB,uCAAuC;AACvC;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAoC,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAgC,MAAM,gBAAgB,CAAC;AAChF,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GAEtB,MAAM,cAAc,CAAC;AAEtB,+BAA+B;AAC/B,OAAO,EAIL,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC;AAExB,uBAAuB;AACvB,OAAO,EAAE,aAAa,EAA4C,MAAM,oBAAoB,CAAC;AAE7F,4BAA4B;AAC5B,OAAO,EACL,sBAAsB,GAGvB,MAAM,0BAA0B,CAAC;AAElC,iCAAiC;AACjC,OAAO,EACL,iCAAiC,EACjC,2BAA2B,GAI5B,MAAM,sCAAsC,CAAC;AAE9C,sBAAsB;AACtB,OAAO,EACL,iBAAiB,GAOlB,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,iCAAiC;AACjC,cAAc,iBAAiB,CAAC;AAEhC,6CAA6C;AAC7C,cAAc,oBAAoB,CAAC;AAEnC,gBAAgB;AAChB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,yBAAyB,GAE1B,MAAM,aAAa,CAAC;AAErB,uCAAuC;AACvC;;;;GAIG;AACH,OAAO,EAAE,aAAa,EAA6B,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAoC,MAAM,qBAAqB,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAgC,MAAM,gBAAgB,CAAC;AAChF,OAAO,EACL,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GAEtB,MAAM,cAAc,CAAC;AAEtB,+BAA+B;AAC/B,OAAO,EAIL,8BAA8B,GAC/B,MAAM,gBAAgB,CAAC;AAExB,uBAAuB;AACvB,OAAO,EAAE,aAAa,EAA4C,MAAM,oBAAoB,CAAC;AAE7F,4BAA4B;AAC5B,OAAO,EACL,sBAAsB,GAGvB,MAAM,0BAA0B,CAAC;AAElC,iCAAiC;AACjC,OAAO,EACL,iCAAiC,EACjC,2BAA2B,GAI5B,MAAM,sCAAsC,CAAC;AAE9C,8DAA8D;AAC9D,OAAO,EACL,oBAAoB,EACpB,0BAA0B,EAC1B,mBAAmB,GAMpB,MAAM,8BAA8B,CAAC;AAEtC,sBAAsB;AACtB,OAAO,EACL,iBAAiB,GAOlB,MAAM,oBAAoB,CAAC"}

package/dist/plugins/auto-attributes.d.ts

@@ -0,0 +1,51 @@
+import type { TrafficalPlugin } from "./types.js";
+/**
+ * Every context key the auto-attributes plugin can derive. All keys live in the
+ * reserved `$` namespace so they never collide with customer keys; the
+ * dashboard registers them as system attributes (`managedBy: system`,
+ * `source: plugin:web`).
+ */
+export declare const AUTO_ATTRIBUTE_KEYS: readonly ["$browser", "$os", "$device_type", "$url", "$host", "$path", "$query", "$referrer", "$page_title", "$utm_source", "$utm_medium", "$utm_campaign", "$utm_term", "$utm_content", "$locale", "$timezone"];
+export type AutoAttributeKey = (typeof AUTO_ATTRIBUTE_KEYS)[number];
+export type AutoBrowser = "chrome" | "edge" | "firefox" | "safari" | "other";
+export type AutoOS = "ios" | "android" | "macos" | "windows" | "linux" | "other";
+export type AutoDeviceType = "mobile" | "tablet" | "desktop";
+export interface AutoAttributesPluginOptions {
+    /** Only derive these keys. Default: every key in `AUTO_ATTRIBUTE_KEYS`. */
+    include?: AutoAttributeKey[];
+    /** Never derive these keys. Applied after `include`. */
+    exclude?: AutoAttributeKey[];
+    /**
+     * Persist `$utm_*` values in `sessionStorage` (key `traffical:utm`) when the
+     * landing URL carries them, and re-read them on later pages of the same
+     * session whose URL has none. Default: true.
+     */
+    persistUtm?: boolean;
+}
+export declare function classifyBrowser(ua: string): AutoBrowser;
+export declare function classifyOS(ua: string, maxTouchPoints?: number): AutoOS;
+export declare function classifyDeviceType(ua: string, opts: {
+    coarsePointer: boolean;
+    width: number;
+    maxTouchPoints?: number;
+}): AutoDeviceType;
+/**
+ * Auto-collected web attributes. Injects `$`-prefixed browser/page/UTM/locale
+ * keys into every decision context via `onBeforeDecision` (same hook as the
+ * redirect plugin). Caller-supplied context always wins; keys that cannot be
+ * derived are omitted rather than sent empty. Re-derived on every decision so
+ * SPA navigation is covered without patching `history`. SSR-safe: without a
+ * `window` the context passes through untouched.
+ *
+ * @example
+ * ```ts
+ * const client = await createTrafficalClient({
+ *   …,
+ *   plugins: [autoAttributesPlugin({ exclude: ["$page_title"] })],
+ * });
+ * ```
+ */
+export declare function autoAttributesPlugin(options?: AutoAttributesPluginOptions): TrafficalPlugin;
+/** Alias with the `create*Plugin` naming used by the other bundled plugins. */
+export declare const createAutoAttributesPlugin: typeof autoAttributesPlugin;
+//# sourceMappingURL=auto-attributes.d.ts.map

package/dist/plugins/auto-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-attributes.d.ts","sourceRoot":"","sources":["../../src/plugins/auto-attributes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,kNAiBtB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAC7E,MAAM,MAAM,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,CAAC;AACjF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE7D,MAAM,WAAW,2BAA2B;IAC1C,2EAA2E;IAC3E,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,wDAAwD;IACxD,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAiBD,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAOvD;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,SAAI,GAAG,MAAM,CASjE;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;IAAE,aAAa,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE,cAAc,CAWhB;AA0GD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,2BAAgC,GAAG,eAAe,CA2B/F;AAED,+EAA+E;AAC/E,eAAO,MAAM,0BAA0B,6BAAuB,CAAC"}

package/dist/plugins/auto-attributes.js

@@ -0,0 +1,234 @@
+/**
+ * Every context key the auto-attributes plugin can derive. All keys live in the
+ * reserved `$` namespace so they never collide with customer keys; the
+ * dashboard registers them as system attributes (`managedBy: system`,
+ * `source: plugin:web`).
+ */
+export const AUTO_ATTRIBUTE_KEYS = [
+    "$browser",
+    "$os",
+    "$device_type",
+    "$url",
+    "$host",
+    "$path",
+    "$query",
+    "$referrer",
+    "$page_title",
+    "$utm_source",
+    "$utm_medium",
+    "$utm_campaign",
+    "$utm_term",
+    "$utm_content",
+    "$locale",
+    "$timezone",
+];
+const UTM_STORAGE_KEY = "traffical:utm";
+const UTM_KEYS = [
+    "$utm_source",
+    "$utm_medium",
+    "$utm_campaign",
+    "$utm_term",
+    "$utm_content",
+];
+/* ------------------------------------------------------------------ */
+/* UA classification — deliberately coarse; UA-class only, no versions */
+/* ------------------------------------------------------------------ */
+export function classifyBrowser(ua) {
+    if (/\bEdg(?:e|A|iOS)?\//.test(ua))
+        return "edge";
+    if (/\bOPR\/|\bOpera\b/.test(ua))
+        return "other";
+    if (/\bFirefox\/|\bFxiOS\//.test(ua))
+        return "firefox";
+    if (/\bChrome\/|\bCriOS\/|\bChromium\//.test(ua))
+        return "chrome";
+    if (/\bSafari\//.test(ua) && /\bVersion\/|\bMobile\//.test(ua))
+        return "safari";
+    return "other";
+}
+export function classifyOS(ua, maxTouchPoints = 0) {
+    if (/\b(?:iPhone|iPad|iPod)\b/.test(ua))
+        return "ios";
+    // iPadOS 13+ reports a desktop Macintosh UA but is the only "Mac" with touch.
+    if (/\bMacintosh\b/.test(ua) && maxTouchPoints > 1)
+        return "ios";
+    if (/\bAndroid\b/.test(ua))
+        return "android";
+    if (/\bWindows\b/.test(ua))
+        return "windows";
+    if (/\bMac OS X\b|\bMacintosh\b/.test(ua))
+        return "macos";
+    if (/\bCrOS\b|\bLinux\b|\bX11\b/.test(ua))
+        return "linux";
+    return "other";
+}
+export function classifyDeviceType(ua, opts) {
+    if (/\biPad\b/.test(ua))
+        return "tablet";
+    if (/\bMacintosh\b/.test(ua) && (opts.maxTouchPoints ?? 0) > 1)
+        return "tablet";
+    if (/\biPhone\b|\biPod\b/.test(ua))
+        return "mobile";
+    if (/\bAndroid\b/.test(ua))
+        return /\bMobile\b/.test(ua) ? "mobile" : "tablet";
+    if (/\bMobi\b/.test(ua))
+        return "mobile";
+    if (opts.coarsePointer) {
+        if (opts.width < 768)
+            return "mobile";
+        if (opts.width < 1024)
+            return "tablet";
+    }
+    return "desktop";
+}
+/* ------------------------------------------------------------------ */
+function readStoredUtm(win) {
+    try {
+        const raw = win.sessionStorage?.getItem(UTM_STORAGE_KEY);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        const out = {};
+        for (const k of UTM_KEYS) {
+            const v = parsed[k];
+            if (typeof v === "string" && v)
+                out[k] = v;
+        }
+        return Object.keys(out).length ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeStoredUtm(win, utm) {
+    try {
+        win.sessionStorage?.setItem(UTM_STORAGE_KEY, JSON.stringify(utm));
+    }
+    catch {
+        // storage may be unavailable (private mode, quota, disabled)
+    }
+}
+function utmFromSearch(search) {
+    const out = {};
+    let params;
+    try {
+        params = new URLSearchParams(search);
+    }
+    catch {
+        return out;
+    }
+    for (const k of UTM_KEYS) {
+        const v = params.get(k.slice(1)); // "$utm_source" → "utm_source"
+        if (v)
+            out[k] = v;
+    }
+    return out;
+}
+function deriveAll(win, persistUtm) {
+    const nav = win.navigator;
+    const loc = win.location;
+    const doc = win.document;
+    const ua = nav?.userAgent ?? "";
+    const maxTouchPoints = typeof nav?.maxTouchPoints === "number" ? nav.maxTouchPoints : 0;
+    let coarsePointer = false;
+    try {
+        coarsePointer = typeof win.matchMedia === "function" && win.matchMedia("(pointer: coarse)").matches;
+    }
+    catch {
+        // matchMedia may throw in exotic embeddings
+    }
+    const width = typeof win.innerWidth === "number" && win.innerWidth > 0 ? win.innerWidth : 1024;
+    const search = loc?.search ?? "";
+    let utm = utmFromSearch(search);
+    if (persistUtm) {
+        if (Object.keys(utm).length) {
+            writeStoredUtm(win, utm);
+        }
+        else {
+            utm = readStoredUtm(win) ?? {};
+        }
+    }
+    let locale = nav?.language || undefined;
+    let timezone;
+    try {
+        timezone = Intl.DateTimeFormat().resolvedOptions().timeZone || undefined;
+    }
+    catch {
+        timezone = undefined;
+    }
+    if (locale === undefined) {
+        try {
+            locale = Intl.DateTimeFormat().resolvedOptions().locale || undefined;
+        }
+        catch {
+            locale = undefined;
+        }
+    }
+    const query = search.startsWith("?") ? search.slice(1) : search;
+    return {
+        $browser: classifyBrowser(ua),
+        $os: classifyOS(ua, maxTouchPoints),
+        $device_type: classifyDeviceType(ua, { coarsePointer, width, maxTouchPoints }),
+        $url: loc?.href || undefined,
+        $host: loc?.host || undefined,
+        $path: loc?.pathname || undefined,
+        $query: query || undefined,
+        $referrer: doc?.referrer || undefined,
+        $page_title: doc?.title || undefined,
+        $utm_source: utm.$utm_source,
+        $utm_medium: utm.$utm_medium,
+        $utm_campaign: utm.$utm_campaign,
+        $utm_term: utm.$utm_term,
+        $utm_content: utm.$utm_content,
+        $locale: locale,
+        $timezone: timezone,
+    };
+}
+/**
+ * Auto-collected web attributes. Injects `$`-prefixed browser/page/UTM/locale
+ * keys into every decision context via `onBeforeDecision` (same hook as the
+ * redirect plugin). Caller-supplied context always wins; keys that cannot be
+ * derived are omitted rather than sent empty. Re-derived on every decision so
+ * SPA navigation is covered without patching `history`. SSR-safe: without a
+ * `window` the context passes through untouched.
+ *
+ * @example
+ * ```ts
+ * const client = await createTrafficalClient({
+ *   …,
+ *   plugins: [autoAttributesPlugin({ exclude: ["$page_title"] })],
+ * });
+ * ```
+ */
+export function autoAttributesPlugin(options = {}) {
+    const persistUtm = options.persistUtm ?? true;
+    const active = new Set(options.include ? options.include.filter((k) => AUTO_ATTRIBUTE_KEYS.includes(k)) : AUTO_ATTRIBUTE_KEYS);
+    for (const k of options.exclude ?? [])
+        active.delete(k);
+    return {
+        name: "auto-attributes",
+        onBeforeDecision(context) {
+            if (typeof window === "undefined")
+                return context;
+            let derived;
+            try {
+                derived = deriveAll(window, persistUtm);
+            }
+            catch {
+                return context;
+            }
+            const out = {};
+            for (const k of active) {
+                const v = derived[k];
+                if (v !== undefined)
+                    out[k] = v;
+            }
+            return { ...out, ...context };
+        },
+    };
+}
+/** Alias with the `create*Plugin` naming used by the other bundled plugins. */
+export const createAutoAttributesPlugin = autoAttributesPlugin;
+//# sourceMappingURL=auto-attributes.js.map

package/dist/plugins/auto-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-attributes.js","sourceRoot":"","sources":["../../src/plugins/auto-attributes.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,UAAU;IACV,KAAK;IACL,cAAc;IACd,MAAM;IACN,OAAO;IACP,OAAO;IACP,QAAQ;IACR,WAAW;IACX,aAAa;IACb,aAAa;IACb,aAAa;IACb,eAAe;IACf,WAAW;IACX,cAAc;IACd,SAAS;IACT,WAAW;CACH,CAAC;AAqBX,MAAM,eAAe,GAAG,eAAe,CAAC;AACxC,MAAM,QAAQ,GAAG;IACf,aAAa;IACb,aAAa;IACb,eAAe;IACf,WAAW;IACX,cAAc;CACgC,CAAC;AAIjD,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AAExE,MAAM,UAAU,eAAe,CAAC,EAAU;IACxC,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,MAAM,CAAC;IAClD,IAAI,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,OAAO,CAAC;IACjD,IAAI,uBAAuB,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACvD,IAAI,mCAAmC,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IAClE,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChF,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,EAAU,EAAE,cAAc,GAAG,CAAC;IACvD,IAAI,0BAA0B,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,8EAA8E;IAC9E,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,cAAc,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACjE,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC7C,IAAI,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1D,IAAI,4BAA4B,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1D,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,EAAU,EACV,IAAwE;IAExE,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzC,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,CAAC,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IAChF,IAAI,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IACpD,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC/E,IAAI,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,QAAQ,CAAC;IACzC,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,KAAK,GAAG,GAAG;YAAE,OAAO,QAAQ,CAAC;QACtC,IAAI,IAAI,CAAC,KAAK,GAAG,IAAI;YAAE,OAAO,QAAQ,CAAC;IACzC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,wEAAwE;AAExE,SAAS,aAAa,CAAC,GAAW;IAChC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;QACzD,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACvD,MAAM,GAAG,GAAc,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;YACzB,MAAM,CAAC,GAAI,MAAkC,CAAC,CAAC,CAAC,CAAC;YACjD,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC;gBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,GAAW,EAAE,GAAc;IACjD,IAAI,CAAC;QACH,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;IAC/D,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,MAAM,GAAG,GAAc,EAAE,CAAC;IAC1B,IAAI,MAAuB,CAAC;IAC5B,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,GAAG,CAAC;IACb,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,+BAA+B;QACjE,IAAI,CAAC;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACpB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,SAAS,CAAC,GAAW,EAAE,UAAmB;IACjD,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC;IAC1B,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC;IACzB,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,CAAC;IACzB,MAAM,EAAE,GAAG,GAAG,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC,MAAM,cAAc,GAAG,OAAO,GAAG,EAAE,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;IAExF,IAAI,aAAa,GAAG,KAAK,CAAC;IAC1B,IAAI,CAAC;QACH,aAAa,GAAG,OAAO,GAAG,CAAC,UAAU,KAAK,UAAU,IAAI,GAAG,CAAC,UAAU,CAAC,mBAAmB,CAAC,CAAC,OAAO,CAAC;IACtG,CAAC;IAAC,MAAM,CAAC;QACP,4CAA4C;IAC9C,CAAC;IACD,MAAM,KAAK,GAAG,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,IAAI,GAAG,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;IAE/F,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,EAAE,CAAC;IACjC,IAAI,GAAG,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,UAAU,EAAE,CAAC;QACf,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC;YAC5B,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC;aAAM,CAAC;YACN,GAAG,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACjC,CAAC;IACH,CAAC;IAED,IAAI,MAAM,GAAuB,GAAG,EAAE,QAAQ,IAAI,SAAS,CAAC;IAC5D,IAAI,QAA4B,CAAC;IACjC,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,eAAe,EAAE,CAAC,QAAQ,IAAI,SAAS,CAAC;IAC3E,CAAC;IAAC,MAAM,CAAC;QACP,QAAQ,GAAG,SAAS,CAAC;IACvB,CAAC;IACD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,eAAe,EAAE,CAAC,MAAM,IAAI,SAAS,CAAC;QACvE,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,SAAS,CAAC;QACrB,CAAC;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IAEhE,OAAO;QACL,QAAQ,EAAE,eAAe,CAAC,EAAE,CAAC;QAC7B,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,cAAc,CAAC;QACnC,YAAY,EAAE,kBAAkB,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC;QAC9E,IAAI,EAAE,GAAG,EAAE,IAAI,IAAI,SAAS;QAC5B,KAAK,EAAE,GAAG,EAAE,IAAI,IAAI,SAAS;QAC7B,KAAK,EAAE,GAAG,EAAE,QAAQ,IAAI,SAAS;QACjC,MAAM,EAAE,KAAK,IAAI,SAAS;QAC1B,SAAS,EAAE,GAAG,EAAE,QAAQ,IAAI,SAAS;QACrC,WAAW,EAAE,GAAG,EAAE,KAAK,IAAI,SAAS;QACpC,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,aAAa,EAAE,GAAG,CAAC,aAAa;QAChC,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,YAAY,EAAE,GAAG,CAAC,YAAY;QAC9B,OAAO,EAAE,MAAM;QACf,SAAS,EAAE,QAAQ;KACpB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAuC,EAAE;IAC5E,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;IAE9C,MAAM,MAAM,GAAG,IAAI,GAAG,CACpB,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAE,mBAAyC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,mBAAmB,CAC9H,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,IAAI,EAAE;QAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAExD,OAAO;QACL,IAAI,EAAE,iBAAiB;QAEvB,gBAAgB,CAAC,OAAgB;YAC/B,IAAI,OAAO,MAAM,KAAK,WAAW;gBAAE,OAAO,OAAO,CAAC;YAClD,IAAI,OAAqD,CAAC;YAC1D,IAAI,CAAC;gBACH,OAAO,GAAG,SAAS,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;YAC1C,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,OAAO,CAAC;YACjB,CAAC;YACD,MAAM,GAAG,GAAY,EAAE,CAAC;YACxB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;gBACvB,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;gBACrB,IAAI,CAAC,KAAK,SAAS;oBAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAClC,CAAC;YACD,OAAO,EAAE,GAAG,GAAG,EAAE,GAAG,OAAO,EAAE,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,MAAM,0BAA0B,GAAG,oBAAoB,CAAC"}

package/dist/plugins/debug.d.ts

@@ -53,6 +53,18 @@ export interface DebugState {
     lastDecisionId: string | null;
     /** Parameter overrides currently applied by the debug plugin. */
     overrides: Record<string, unknown>;
+    /**
+     * Context attributes the debug plugin merges into every decision's context
+     * (on top of whatever the host app passes). Lets an inspector satisfy
+     * targeting conditions the app itself never sets, e.g. `testMode exists`.
+     */
+    contextOverrides: Record<string, unknown>;
+    /**
+     * The context of the last real decision, as the app passed it (after the
+     * client's unit-key enrichment, before context overrides). `null` until the
+     * app has decided at least once.
+     */
+    lastContext: Record<string, unknown> | null;
 }
 export interface TrafficalDebugInstance {
     readonly id: string;
@@ -72,6 +84,18 @@ export interface TrafficalDebugInstance {
     clearOverride(key: string): void;
     clearAllOverrides(): void;
     getOverrides(): Record<string, unknown>;
+    /**
+     * Replace the context attributes merged into every decision. Re-decides
+     * immediately. Pass `{}` to clear.
+     */
+    setContextOverrides(context: Record<string, unknown>): void;
+    getContextOverrides(): Record<string, unknown>;
+    /**
+     * Re-run the app's last decision (same context and parameter set) so the
+     * inspector shows what the app would resolve right now. If the page uses
+     * the OpenFeature provider, the OpenFeature context is re-set so hooks
+     * bound to `PROVIDER_CONTEXT_CHANGED` re-render too.
+     */
     reDecide(): void;
     refresh(): Promise<void>;
 }