@walkeros/web-source-session 4.1.0-next-1778668930820 → 4.1.0

package/CHANGELOG.md

@@ -0,0 +1,435 @@
+# @walkeros/web-source-session
+
+## 4.1.0
+
+### Patch Changes
+
+- fd6076e: Walker commands `destination`, `hook`, and `on` now take a single
+  Init object: `elb('walker destination', { code, config })`,
+  `elb('walker hook', { name, fn })`, `elb('walker on', { type, rules })`. The
+  previous positional forms and the `{ push }` shorthand are removed; the
+  `options` argument is gone from `collector.command`, `addDestination`, and
+  `commonHandleCommand`.
+- Updated dependencies [e155ff8]
+- Updated dependencies [e800974]
+- Updated dependencies [e155ff8]
+- Updated dependencies [1a8f2d7]
+- Updated dependencies [1a8f2d7]
+- Updated dependencies [b276173]
+- Updated dependencies [dd9f5ad]
+- Updated dependencies [c60ef35]
+- Updated dependencies [adeebea]
+- Updated dependencies [13aaeaa]
+- Updated dependencies [e800974]
+- Updated dependencies [adeebea]
+- Updated dependencies [e800974]
+- Updated dependencies [e800974]
+- Updated dependencies [058f7ed]
+- Updated dependencies [28a8ac2]
+- Updated dependencies [fd6076e]
+  - @walkeros/core@4.1.0
+  - @walkeros/web-core@4.1.0
+
+## 4.0.2
+
+### Patch Changes
+
+- Updated dependencies [a6a0ea7]
+  - @walkeros/core@4.0.2
+  - @walkeros/web-core@4.0.2
+
+## 4.0.1
+
+### Patch Changes
+
+- Updated dependencies [381dfe7]
+- Updated dependencies [1524275]
+- Updated dependencies [03d7055]
+  - @walkeros/core@4.0.1
+  - @walkeros/web-core@4.0.1
+
+## 4.0.0
+
+### Major Changes
+
+- 93ea9c4: Event model v4: breaking changes to the `Event`, `Source`, and
+  `Entity` shapes.
+  - `event.id` is now a W3C span_id (16 lowercase hex chars), generated by the
+    collector. Reference: W3C Trace Context (W3C Recommendation, January 2020).
+  - `event.version`, `event.group`, `event.count` are removed.
+  - `source.type` is now the source kind (e.g. `browser`, `gtag`, `mcp`, `cli`).
+    New `source.platform` holds the runtime (`web` | `server` | `app` | ...).
+  - `source.id` and `source.previous_id` are removed.
+  - Browser source now sets `source.url` and `source.referrer`.
+  - MCP source sets `source.tool` per emission. CLI source sets
+    `source.command`.
+  - `Entity.nested` and `Entity.context` are now optional. Root `event.nested`
+    and `event.context` remain required.
+  - Each source self-registers via TypeScript module augmentation of `SourceMap`
+    in `@walkeros/core`.
+  - App-side coordination (`/workspaces/developer/app`) is a follow-up plan, not
+    part of this release. Telemetry from v4 CLI/MCP will not validate against
+    the existing app schema until that follow-up ships.
+  - `Mapping.Rule.skip` is renamed to `Mapping.Rule.silent`. Customer flow.json
+    configs using `skip: true` in mapping rules must rename to `silent: true`.
+    Hard cut: no legacy alias, the field is gone.
+
+- 1ef33d9: **BREAKING:** Unified callback signatures across mapping and on.\*
+  subscriptions.
+
+  Every callback in walkerOS now reads `(data, context) => result`. Sources,
+  transformers, destinations, and stores already conformed; mapping and on.\*
+  join the family in v4.1.
+
+  ### Mapping callbacks
+
+  `fn`, `condition`, and `validate` now share a single shape:
+
+  `(value, context: Mapping.Context) => result`
+
+  `Mapping.Options` is removed. Replaced by `Mapping.Context`:
+
+  ```ts
+  interface Context {
+    event: WalkerOS.DeepPartialEvent;
+    mapping: Value | Rule;
+    collector: Collector.Instance; // required
+    logger: Logger.Instance; // required
+    consent?: WalkerOS.Consent; // resolved consent
+  }
+  ```
+
+  Rule-level `condition` is now `(event, context) => boolean`.
+  `Mapping.Options.props` is removed (no production callers).
+
+  #### Mapping upgrade
+
+  ```ts
+  // before
+  const fn: Mapping.Fn = (value, mapping, options) => /* … */;
+  const cond: Mapping.Condition = (value, mapping, collector) => /* … */;
+  const val: Mapping.Validate = (value) => /* … */;
+
+  // after
+  const fn: Mapping.Fn = (value, context) => /* … */;
+  const cond: Mapping.Condition = (value, context) => /* … */;
+  const val: Mapping.Validate = (value, context) => /* … */;
+  ```
+
+  In `$code:` strings (flow.json):
+
+  ```json
+  // before
+  "fn": "$code:(value, mapping, options) => …"
+  "condition": "$code:(value, mapping, collector) => …"
+
+  // after
+  "fn": "$code:(value, context) => …"
+  "condition": "$code:(value, context) => …"
+  ```
+
+  `context.mapping` replaces the second positional arg; `context.collector`,
+  `context.logger`, and `context.consent` are all available.
+
+  One-arg callbacks like `(value) => value.toUpperCase()` continue to work
+  unchanged.
+
+  ### On.\* subscription callbacks
+
+  `walker.on('consent', …)`, `walker.on('ready', …)`, etc. now receive
+  `(data, context: On.Context) => void | Promise<void>`. The legacy `Context`
+  interface, `*Config` aliases, and `Options` discriminated union are removed.
+
+  ```ts
+  interface Context {
+    collector: Collector.Instance; // required
+    logger: Logger.Instance; // required
+  }
+
+  type Fn<TData = unknown> = (
+    data: TData,
+    context: Context,
+  ) => void | Promise<void>;
+
+  type ConsentFn = Fn<WalkerOS.Consent>;
+  type SessionFn = Fn<Collector.SessionData | undefined>;
+  type UserFn = Fn<WalkerOS.User>;
+  type ReadyFn = Fn<void>;
+  type RunFn = Fn<void>;
+  type GenericFn = Fn<unknown>;
+  ```
+
+  The new `On.Subscription` alias is the registerable union for
+  `walker.on(action, X)`.
+
+  #### On.\* upgrade
+
+  ```ts
+  // before
+  walker.on('consent', { marketing: (collector, consent) => /* … */ });
+  walker.on('ready', (collector) => /* … */);
+  walker.on('session', (collector, session) => /* … */);
+
+  // after
+  walker.on('consent', { marketing: (consent, ctx) => /* … */ });
+  walker.on('ready', (_, ctx) => /* … */);
+  walker.on('session', (session, ctx) => /* … */);
+  ```
+
+  `ctx.collector` replaces the positional first arg; `ctx.logger` is also
+  available.
+
+  ### Why both at once
+
+  Both refactors follow the same `(data, context)` pattern. Shipping them in one
+  release means consumers do one search-and-replace pass instead of two, and the
+  codebase reaches full callback-signature consistency in v4.1.
+
+### Patch Changes
+
+- Updated dependencies [93ea9c4]
+- Updated dependencies [465775c]
+- Updated dependencies [942a7fe]
+- Updated dependencies [cfc7469]
+- Updated dependencies [8e06b1f]
+- Updated dependencies [3d50dd6]
+- Updated dependencies [1ef33d9]
+  - @walkeros/core@4.0.0
+  - @walkeros/web-core@4.0.0
+
+## 3.4.2
+
+### Patch Changes
+
+- @walkeros/core@3.4.2
+- @walkeros/web-core@3.4.2
+
+## 3.4.1
+
+### Patch Changes
+
+- Updated dependencies [12adf24]
+- Updated dependencies [75aa26b]
+- Updated dependencies [caea905]
+  - @walkeros/core@3.4.1
+  - @walkeros/web-core@3.4.1
+
+## 3.4.0
+
+### Minor Changes
+
+- 724f97e: Migrate every step example in every walkerOS package to the
+  standardized `[callable, ...args][]` shape introduced in `@walkeros/core`.
+  Every step example's `out` is now an array of effect tuples whose first
+  element is the callable's public SDK name (`'gtag'`, `'analytics.track'`,
+  `'fbq'`, `'dataLayer.push'`, `'sendServer'`, `'fetch'`, `'trackClient.track'`,
+  `'amplitude.track'`, `'fs.writeFile'`, `'producer.send'`, `'client.xadd'`,
+  `'client.send'`, `'dataset.table.insert'`, etc.). Source examples use `'elb'`
+  as the callable; transformer examples use the reserved `'return'` keyword;
+  store examples use store-operation callables (`'get'`, `'set'`). Tests capture
+  real calls on each component's spy and assert against `example.out` directly —
+  the hardcoded `PACKAGE_CALLS` registry in the app is no longer consulted
+  (emptied; plan #3 removes it structurally).
+
+### Patch Changes
+
+- Updated dependencies [74940cc]
+- Updated dependencies [525f5d9]
+  - @walkeros/core@3.4.0
+  - @walkeros/web-core@3.4.0
+
+## 3.3.1
+
+### Patch Changes
+
+- @walkeros/core@3.3.1
+- @walkeros/web-core@3.3.1
+
+## 3.3.0
+
+### Patch Changes
+
+- 08c365a: Expand `getMarketingParameters` to recognise 25+ ad platform click
+  IDs (Pinterest, Reddit, Quora, Yandex, Outbrain, Taboola, Mailchimp, Klaviyo,
+  HubSpot, Adobe, Impact, CJ, Branch, plus Google's `wbraid`/`gbraid`). Add a
+  new `platform` field that resolves the click ID to a canonical platform
+  identifier (e.g. `gclid` → `google`, `fbclid` → `meta`). Multi-click-ID URLs
+  are resolved deterministically via a priority order.
+
+  Custom click-ID registries can be passed as the third argument to
+  `getMarketingParameters`, or via the new `clickIds` field in the session
+  source settings — so flow.json users can extend or override defaults without
+  touching code.
+
+- Updated dependencies [2849acb]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+- Updated dependencies [08c365a]
+  - @walkeros/core@3.3.0
+  - @walkeros/web-core@3.3.0
+
+## 3.2.0
+
+### Patch Changes
+
+- Updated dependencies [eb865e1]
+- Updated dependencies [c0a53f9]
+- Updated dependencies [f007c9f]
+- Updated dependencies [bf2dc5b]
+- Updated dependencies [da0b640]
+  - @walkeros/core@3.2.0
+  - @walkeros/web-core@3.2.0
+
+## 3.1.1
+
+### Patch Changes
+
+- @walkeros/core@3.1.1
+- @walkeros/web-core@3.1.1
+
+## 3.1.0
+
+### Minor Changes
+
+- 956c337: Add createTrigger following unified Trigger.CreateFn interface. Step
+  examples updated with trigger metadata.
+- ff58828: Add env.window and env.document to session source Env interface.
+  Session detection (window, storage, performance) now uses injected globals
+  when provided, enabling full simulation without a browser environment.
+
+### Patch Changes
+
+- Updated dependencies [ff58828]
+- Updated dependencies [dfc6738]
+- Updated dependencies [966342b]
+- Updated dependencies [bee8ba7]
+- Updated dependencies [966342b]
+- Updated dependencies [df990d4]
+  - @walkeros/web-core@3.1.0
+  - @walkeros/core@3.1.0
+
+## 3.0.2
+
+### Patch Changes
+
+- @walkeros/core@3.0.2
+- @walkeros/web-core@3.0.2
+
+## 3.0.1
+
+### Patch Changes
+
+- @walkeros/core@3.0.1
+- @walkeros/web-core@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- 499e27a: Add sideEffects declarations to all packages for bundler tree-shaking
+  support.
+- Updated dependencies [2b259b6]
+- Updated dependencies [2614014]
+- Updated dependencies [6ae0ee3]
+- Updated dependencies [37299a9]
+- Updated dependencies [499e27a]
+- Updated dependencies [0e5eede]
+- Updated dependencies [d11f574]
+- Updated dependencies [d11f574]
+- Updated dependencies [1fe337a]
+- Updated dependencies [5cb84c1]
+- Updated dependencies [23f218a]
+- Updated dependencies [499e27a]
+- Updated dependencies [c83d909]
+- Updated dependencies [b6c8fa8]
+  - @walkeros/core@3.0.0
+  - @walkeros/web-core@3.0.0
+
+## 2.1.1
+
+### Patch Changes
+
+- Updated dependencies [fab477d]
+  - @walkeros/core@2.1.1
+  - @walkeros/web-core@2.1.1
+
+## 2.1.0
+
+### Minor Changes
+
+- 97df0b2: Step examples: upgrade all packages to blueprint pattern with inline
+  mapping, no intermediate variables, no `all` export
+
+### Patch Changes
+
+- 60f0a1c: Add setup functions and renderer metadata for source simulation
+- Updated dependencies [7fc4cee]
+- Updated dependencies [7fc4cee]
+- Updated dependencies [cb2da05]
+- Updated dependencies [2bbe8c8]
+- Updated dependencies [3eb6416]
+- Updated dependencies [02a7958]
+- Updated dependencies [97df0b2]
+- Updated dependencies [97df0b2]
+- Updated dependencies [026c412]
+- Updated dependencies [7d38d9d]
+  - @walkeros/core@2.1.0
+  - @walkeros/web-core@2.1.0
+
+## 2.0.1
+
+## 1.1.4
+
+### Patch Changes
+
+- Updated dependencies [7b2d750]
+  - @walkeros/core@1.4.0
+  - @walkeros/web-core@2.0.0
+
+## 1.1.3
+
+### Patch Changes
+
+- Updated dependencies [a4cc1ea]
+  - @walkeros/core@1.3.0
+  - @walkeros/web-core@1.0.5
+
+## 1.1.2
+
+### Patch Changes
+
+- Updated dependencies [7ad6cfb]
+  - @walkeros/core@1.2.2
+  - @walkeros/web-core@1.0.4
+
+## 1.1.1
+
+### Patch Changes
+
+- Updated dependencies [6256c12]
+  - @walkeros/core@1.2.1
+  - @walkeros/web-core@1.0.3
+
+## 1.1.0
+
+### Minor Changes
+
+- a38d791: Session detection extracted to standalone sourceSession
+  - New `sourceSession` for composable session management
+  - Browser source no longer includes session by default
+  - To restore previous behavior, add sourceSession alongside browser source:
+
+  ```typescript
+  sources: {
+    browser: sourceBrowser,
+    session: { code: sourceSession, config: { storage: true } }
+  }
+  ```
+
+### Patch Changes
+
+- Updated dependencies [f39d9fb]
+- Updated dependencies [888bbdf]
+  - @walkeros/core@1.2.0
+  - @walkeros/web-core@1.0.2

package/README.md

@@ -1,41 +1,17 @@
+<p align="left">
+  <a href="https://www.walkeros.io">
+    <img alt="walkerOS" title="walkerOS" src="https://www.walkeros.io/img/walkerOS_logo.svg" width="256px"/>
+  </a>
+</p>
+
 # @walkeros/web-source-session
 
-Standalone session detection and management for walkerOS.
+Standalone session detection and management that can be composed with any
+walkerOS source.
 
+[Documentation](https://www.walkeros.io/docs/sources/web/session) &bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-source-session) &bull;
 [Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/sources/session)
-| [NPM](https://www.npmjs.com/package/@walkeros/web-source-session) |
-[Documentation](https://www.walkeros.io/docs/sources/web/session)
-
-## Quick Start
-
-```typescript
-import { startFlow } from '@walkeros/collector';
-import { sourceBrowser } from '@walkeros/web-source-browser';
-import { sourceSession } from '@walkeros/web-source-session';
-
-const { collector, elb } = await startFlow({
-  sources: {
-    browser: sourceBrowser,
-    session: {
-      code: sourceSession,
-      config: {
-        settings: {
-          storage: true, // Enable persistent session storage
-        },
-      },
-    },
-  },
-});
-```
-
-## Features
-
-- **Session detection**: Automatic detection of new sessions based on
-  navigation, referrer, and marketing parameters
-- **Device tracking**: Persistent device ID across sessions (with consent)
-- **Consent-aware**: Switches between window-only and storage-based sessions
-  based on user consent
-- **Composable**: Works alongside any source (browser, dataLayer, custom)
 
 ## Installation
 
@@ -43,176 +19,34 @@ const { collector, elb } = await startFlow({
 npm install @walkeros/web-source-session
 ```
 
-## Why Separate Session Source?
-
-The session source was extracted from the browser source to enable:
-
-1. **Composability**: Use session detection with any source, not just browser
-2. **Single responsibility**: Browser source focuses on DOM events, session
-   source on identity
-3. **Flexibility**: Configure session independently from event capture
-4. **Server-side ready**: Session logic can work with server sources too
-
-## Configuration Reference
-
-| Name             | Type                       | Description                                      | Default          |
-| ---------------- | -------------------------- | ------------------------------------------------ | ---------------- |
-| `storage`        | `boolean`                  | Enable persistent storage for session/device IDs | `false`          |
-| `consent`        | `string \| string[]`       | Consent key(s) required to enable storage mode   | -                |
-| `length`         | `number`                   | Session timeout in minutes                       | `30`             |
-| `pulse`          | `boolean`                  | Keep session alive on each event                 | `false`          |
-| `sessionKey`     | `string`                   | Storage key for session ID                       | `'elbSessionId'` |
-| `sessionStorage` | `'local' \| 'session'`     | Storage type for session                         | `'local'`        |
-| `deviceKey`      | `string`                   | Storage key for device ID                        | `'elbDeviceId'`  |
-| `deviceStorage`  | `'local' \| 'session'`     | Storage type for device                          | `'local'`        |
-| `cb`             | `SessionCallback \| false` | Custom callback or disable default               | -                |
-
-## Examples
-
-### Basic (Window-only)
-
-No persistent storage, session detected per page load:
-
-```typescript
-const { elb } = await startFlow({
-  sources: {
-    browser: sourceBrowser,
-    session: sourceSession, // Defaults to window-only mode
-  },
-});
-```
-
-### With Persistent Storage
-
-Store session and device IDs in localStorage:
-
-```typescript
-const { elb } = await startFlow({
-  sources: {
-    browser: sourceBrowser,
-    session: {
-      code: sourceSession,
-      config: {
-        settings: {
-          storage: true,
-          length: 30, // 30-minute session timeout
-        },
-      },
-    },
-  },
-});
-```
-
-### Consent-Aware
-
-Switch to storage mode only when user grants consent:
-
-```typescript
-const { elb } = await startFlow({
-  sources: {
-    browser: sourceBrowser,
-    session: {
-      code: sourceSession,
-      config: {
-        settings: {
-          consent: 'analytics', // Wait for analytics consent
-          storage: true,
-        },
-      },
-    },
-  },
-});
-
-// Later, when user grants consent:
-elb('walker consent', { analytics: true });
-// Session source automatically switches to storage mode
-```
-
-## Session Start Event
-
-When a new session is detected, the source pushes a `session start` event:
+## Quick start
 
-```typescript
+```json
 {
-  name: 'session start',
-  data: {
-    isStart: true,
-    id: 'abc123',      // Session ID
-    device: 'xyz789',  // Device ID (if storage enabled)
-    storage: true,     // Whether storage mode is active
-    // ... additional session metadata
+  "version": 4,
+  "flows": {
+    "default": {
+      "config": { "platform": "web" },
+      "sources": {
+        "session": { "package": "@walkeros/web-source-session", "config": {} }
+      }
+    }
   }
 }
 ```
 
-Marketing click IDs detected in the URL (e.g. `gclid`, `fbclid`) resolve to a
-canonical `platform` field on the session data (e.g. `google`, `meta`). Extend
-or override the built-in registry via `settings.clickIds` — entries with a
-`param` matching a default override the platform name in place, new params
-append to the priority list.
-
-## Migration from Browser Source
-
-If you were using the browser source with session enabled:
-
-```typescript
-// Before (browser source with built-in session)
-const { elb } = await startFlow({
-  sources: {
-    browser: {
-      code: sourceBrowser,
-      config: { settings: { session: true } },
-    },
-  },
-});
-
-// After (separate session source)
-const { elb } = await startFlow({
-  sources: {
-    browser: sourceBrowser,
-    session: {
-      code: sourceSession,
-      config: { settings: { storage: true } },
-    },
-  },
-});
-```
-
-## Exported Functions
-
-The session source exports session functions for direct usage:
-
-```typescript
-import {
-  // Session functions
-  sessionStart,
-  sessionWindow,
-  sessionStorage,
-} from '@walkeros/web-source-session';
-
-// Use sessionStart directly (advanced usage)
-const session = sessionStart({
-  storage: true,
-  collector: collectorInstance,
-});
-```
-
-Storage utilities are available from `@walkeros/web-core`:
+## Documentation
 
-```typescript
-import { storageRead, storageWrite, storageDelete } from '@walkeros/web-core';
-
-storageWrite('key', 'value', 30); // 30-minute expiration
-const value = storageRead('key');
-storageDelete('key');
-```
+Full configuration, mapping, and examples live in the docs:
+**https://www.walkeros.io/docs/sources/web/session**
 
-## Type Definitions
+## Contribute
 
-See [src/types/index.ts](./src/types/index.ts) for TypeScript interfaces.
+Feel free to contribute by submitting an
+[issue](https://github.com/elbwalker/walkerOS/issues), starting a
+[discussion](https://github.com/elbwalker/walkerOS/discussions), or getting in
+[contact](https://calendly.com/elb-alexander/30min).
 
-## Related
+## License
 
-- [Browser Source](/docs/sources/web/browser) - DOM-based event tracking
-- [DataLayer Source](/docs/sources/web/dataLayer) - GTM/GA4 integration
-- [Session Documentation](https://www.walkeros.io/docs/sources/web/session)
+MIT