@walkeros/web-destination-segment 4.1.0-next-1778668930820 → 4.1.0

package/CHANGELOG.md

@@ -0,0 +1,153 @@
+# @walkeros/web-destination-segment
+
+## 4.1.0
+
+### Patch Changes
+
+- 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
+
+- @walkeros/web-core@4.0.2
+
+## 4.0.1
+
+### Patch Changes
+
+- @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.
+
+### Patch Changes
+
+- Updated dependencies [93ea9c4]
+  - @walkeros/web-core@4.0.0
+
+## 3.4.2
+
+### Patch Changes
+
+- @walkeros/web-core@3.4.2
+
+## 3.4.1
+
+### Patch Changes
+
+- Updated dependencies [caea905]
+  - @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
+
+- @walkeros/web-core@3.4.0
+
+## 3.3.1
+
+### Patch Changes
+
+- @walkeros/web-core@3.3.1
+
+## 3.3.0
+
+### Minor Changes
+
+- 08c365a: Add Segment CDP web destination (`@walkeros/web-destination-segment`)
+  — forwards walkerOS events to Segment via the official
+  `@segment/analytics-next` (Analytics.js 2.0) package. Implements the full
+  Segment Spec surface with automatic walkerOS→Segment consent context
+  forwarding and deferred-load consent handling.
+  - Default event forwarding: every walkerOS event becomes
+    `analytics.track(name, properties)`
+  - Custom event properties: `settings.include` flattens walkerOS event sections
+    with prefix (`data_*`, `globals_*`, etc.) or use `mapping.data` for full
+    Segment-Spec-shaped properties
+  - Identity: destination-level + per-event `settings.identify` resolving to
+    `{ userId, traits, anonymousId }`. Runtime state diffing skips redundant
+    `identify()` calls.
+  - Groups: `settings.group` and per-event `mapping.settings.group` with
+    reserved Segment group trait names
+  - Page views: first-class `mapping.settings.page` →
+    `analytics.page(category, name, properties)` (explicit configuration, no
+    auto-detection)
+  - Reset: `settings.reset: true` calls `analytics.reset()` on logout
+  - Consent context forwarding: walkerOS consent state is automatically stamped
+    as `context.consent.categoryPreferences` on every track, identify, group,
+    and page call when `settings.consent` is configured, with optional key
+    remapping (e.g. walkerOS `marketing` → Segment `Advertising`)
+  - Deferred-load consent pattern: when `config.consent` is declared,
+    `AnalyticsBrowser.load()` is held until `on('consent')` fires with all
+    required keys granted
+  - Ecommerce: walkerOS `mapping.name` + `mapping.data` produce Segment Spec
+    event names (e.g. `Order Completed`) with a `products` array property — a
+    single `track()` call per order, not a loop
+  - SDK resolution follows the `env?.analytics ?? realSegment` pattern (mirrors
+    `@walkeros/web-destination-clarity`)
+  - Plugins, source middleware, and destination middleware are explicitly out of
+    scope for v1 (JavaScript functions cannot be serialized in JSON flow configs
+    — register them programmatically on the returned `AnalyticsBrowser` instance
+    if needed)
+  - `alias()` and `screen()` are intentionally deferred (legacy / mobile-only)
+
+### Patch Changes
+
+- @walkeros/web-core@3.3.0

package/README.md

@@ -4,361 +4,46 @@
   </a>
 </p>
 
-# Segment CDP Destination for walkerOS
+# @walkeros/web-destination-segment
 
-[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/segment)
-&bull;
-[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-segment)
-&bull; [Documentation](https://www.walkeros.io/docs/destinations/web/segment)
-
-This package forwards walkerOS events to [Segment](https://segment.com/) - the
-customer data platform that routes your event data to 400+ downstream
-destinations. Built on the official
-[`@segment/analytics-next`](https://www.npmjs.com/package/@segment/analytics-next)
-(Analytics.js 2.0) SDK.
-
-walkerOS follows a **source → collector → destination** architecture. This
-Segment destination receives processed events from the walkerOS collector and
-forwards them via the full Segment Spec surface: `track`, `identify`, `group`,
-`page`, and `reset`.
+Segment CDP, routing events to 400+ downstream destinations.
 
-## Features
-
-- **Default event forwarding** - every walkerOS event becomes
-  `analytics.track(name, properties)` with no additional config
-- **Custom event properties** - flatten walkerOS sections with
-  `settings.include` (`data_*`, `globals_*`, etc.) or produce fully-shaped
-  Segment Spec properties via `mapping.data`
-- **Identity** - destination-level or per-event `settings.identify` resolving to
-  `{ userId, traits, anonymousId }`, with runtime state diffing so redundant
-  `identify()` calls are skipped
-- **Groups** - `settings.group` with Segment-reserved group traits (`name`,
-  `industry`, `employees`, `plan`, ...)
-- **Page views** - first-class `analytics.page(category, name, properties)` via
-  explicit `mapping.settings.page` configuration
-- **Reset on logout** - `settings.reset: true` calls `analytics.reset()` so the
-  current user identity is cleared
-- **Consent context forwarding** - walkerOS consent state is automatically
-  stamped as `context.consent.categoryPreferences` on every call, with optional
-  `settings.consent` key remapping
-- **Deferred-load consent pattern** - when `config.consent` is declared,
-  `AnalyticsBrowser.load()` is held until the first grant
-- **Ecommerce via the Segment Spec** - walkerOS `mapping.name` + `mapping.data`
-  produce PascalCase event names (`Order Completed`) with a `products` array, a
-  single `track()` call per order (no loop)
+[Documentation](https://www.walkeros.io/docs/destinations/web/segment) &bull;
+[NPM Package](https://www.npmjs.com/package/@walkeros/web-destination-segment)
+&bull;
+[Source Code](https://github.com/elbwalker/walkerOS/tree/main/packages/web/destinations/segment)
 
 ## Installation
 
-```sh
+```bash
 npm install @walkeros/web-destination-segment
 ```
 
-## Quick Start
-
-```typescript
-import { startFlow } from '@walkeros/collector';
-import { destinationSegment } from '@walkeros/web-destination-segment';
+## Quick start
 
-await startFlow({
-  destinations: {
-    segment: {
-      code: destinationSegment,
-      config: {
-        settings: {
-          apiKey: 'YOUR_SEGMENT_WRITE_KEY',
-        },
+```json
+{
+  "version": 4,
+  "flows": {
+    "default": {
+      "config": {
+        "platform": "web"
       },
-    },
-  },
-});
-```
-
-## Configuration
-
-### Settings (destination-level)
-
-The `Settings` type extends Segment's `InitOptions`, so every passthrough option
-(cookie, storage, integrations, plan, retryQueue, ...) works alongside the
-walkerOS-specific fields listed below.
-
-| Name                       | Type                     | Description                                                                                                         | Required |
-| -------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------- | -------- |
-| `apiKey`                   | `string`                 | Your Segment source write key - maps to `writeKey` in `AnalyticsBrowser.load()`                                     | Yes      |
-| `identify`                 | `Mapping.Value`          | Destination-level identity mapping resolving to `{ userId, traits, anonymousId }`                                   | No       |
-| `group`                    | `Mapping.Value`          | Destination-level group mapping resolving to `{ groupId, traits }`                                                  | No       |
-| `include`                  | `string[]`               | walkerOS event sections to flatten into Segment `properties` (`data`, `globals`, `context`, `user`, `event`, `all`) | No       |
-| `consent`                  | `Record<string, string>` | Mapping from walkerOS consent keys → Segment `categoryPreferences` keys (e.g. `{ marketing: 'Advertising' }`)       | No       |
-| `initialPageview`          | `boolean`                | Default `false` - walkerOS sources handle page tracking, so the SDK's auto pageview is disabled                     | No       |
-| `disableClientPersistence` | `boolean`                | Disable all cookie / localStorage writes                                                                            | No       |
-| `integrations`             | `object`                 | Enable/disable downstream Segment destinations. Example: `{ All: true, Mixpanel: false }`                           | No       |
-
-### Mapping (`rule.settings`)
-
-| Name       | Type                    | Description                                                                                                 |
-| ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `identify` | `Mapping.Value`         | Per-event identity override; resolves to `{ userId, traits, anonymousId }`                                  |
-| `group`    | `Mapping.Value`         | Per-event group assignment; resolves to `{ groupId, traits }`                                               |
-| `page`     | `Mapping.Value \| true` | Page call config. `true` → empty `analytics.page()`. Object resolves to `{ category?, name?, properties? }` |
-| `reset`    | `Mapping.Value \| true` | Logout trigger. Truthy → `analytics.reset()`                                                                |
-| `include`  | `string[]`              | Override destination-level `include` for this rule                                                          |
-
-Use `mapping.silent: true` to suppress the default `analytics.track()` call when
-a rule runs identity / group / page side effects only.
-
-## Event Properties
-
-Two ways to shape Segment track properties:
-
-```typescript
-// 1. Flatten walkerOS sections via settings.include
-config: {
-  settings: {
-    apiKey: 'WRITE_KEY',
-    include: ['data', 'globals'], // → data_*, globals_* props on every event
-  },
-}
-
-// 2. Build Segment-Spec-shaped properties via mapping.data
-mapping: {
-  order: {
-    complete: {
-      name: 'Order Completed',
-      data: {
-        map: {
-          order_id: 'data.id',
-          currency: { key: 'data.currency', value: 'EUR' },
-          shipping: 'data.shipping',
-          tax: 'data.taxes',
-          total: 'data.total',
-          products: {
-            loop: [
-              'nested',
-              {
-                condition: (v) => typeof v?.data?.price === 'number',
-                map: {
-                  product_id: 'data.id',
-                  name: 'data.name',
-                  price: 'data.price',
-                  quantity: { key: 'data.quantity', value: 1 },
-                  currency: { key: 'data.currency', value: 'EUR' },
-                },
-              },
-            ],
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-The Segment Ecommerce Spec uses a **single**
-`track('Order Completed', { products: [...] })` call - not a loop of N revenue
-calls. walkerOS `mapping.data` with a nested `loop` over `nested` builds the
-products array inline.
-
-## Identity
-
-Destination-level identity fires on every push (with state diffing to skip
-redundant calls):
-
-```typescript
-config: {
-  settings: {
-    apiKey: 'WRITE_KEY',
-    identify: {
-      map: {
-        userId: 'user.id',
-        traits: {
-          map: {
-            email: 'user.email',
-            name: 'user.name',
-          },
-        },
-      },
-    },
-  },
+      "destinations": {
+        "segment": {
+          "package": "@walkeros/web-destination-segment",
+          "config": {}
+        }
+      }
+    }
+  }
 }
 ```
 
-Per-event identity uses a mapping rule with `silent: true` so only the identity
-side effect runs (not a default `track()`):
-
-```typescript
-mapping: {
-  user: {
-    login: {
-      silent: true,
-      settings: {
-        identify: {
-          map: {
-            userId: 'data.user_id',
-            traits: {
-              map: {
-                email: 'data.email',
-                plan: 'data.plan',
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-### Reserved Traits (Segment Spec)
-
-Use these trait names so downstream destinations recognize them: `email`,
-`name`, `firstName`, `lastName`, `phone`, `avatar`, `birthday`, `plan`,
-`company`, `createdAt`, `title`, `username`, `gender`, `age`.
-
-## Groups
-
-```typescript
-mapping: {
-  company: {
-    update: {
-      silent: true,
-      settings: {
-        group: {
-          map: {
-            groupId: 'data.company_id',
-            traits: {
-              map: {
-                name: 'data.company_name',
-                industry: 'data.industry',
-                employees: 'data.employees',
-                plan: 'data.plan',
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-Reserved Segment group traits: `name`, `industry`, `employees`, `plan`,
-`createdAt`, `description`, `email`, `website`.
-
-## Page Views
-
-Segment's `page()` is first-class - walkerOS `page view` events should map to
-`analytics.page()`, not `analytics.track('page view')`. Configure explicitly via
-`mapping.settings.page`:
-
-```typescript
-mapping: {
-  page: {
-    view: {
-      silent: true,
-      settings: {
-        page: {
-          map: {
-            category: 'data.category',
-            name: 'data.title',
-            properties: {
-              map: {
-                section: 'data.section',
-              },
-            },
-          },
-        },
-      },
-    },
-  },
-}
-```
-
-Or the minimal form (`true`) that fires an empty `analytics.page()` and relies
-on the SDK's automatic url/path/referrer/title collection:
-
-```typescript
-mapping: {
-  page: {
-    view: {
-      silent: true,
-      settings: {
-        page: true,
-      },
-    },
-  },
-}
-```
-
-## Consent
-
-The destination supports two complementary consent mechanisms:
-
-**Automatic context forwarding.** When `settings.consent` is configured, the
-destination stamps every `track`, `identify`, `group`, and `page` call with
-`context.consent.categoryPreferences`:
-
-```typescript
-config: {
-  settings: {
-    apiKey: 'WRITE_KEY',
-    consent: {
-      analytics: 'Analytics',
-      marketing: 'Advertising',
-    },
-  },
-}
-```
-
-When the walker emits an event with
-`consent: { analytics: true, marketing: true }`, the destination calls
-`analytics.track(name, props, { context: { consent: { categoryPreferences: { Analytics: true, Advertising: true } } } })`.
-
-**Deferred-load consent pattern.** When `config.consent` is declared,
-`AnalyticsBrowser.load()` is held until the first `walker consent` command that
-grants all required keys. Once granted, the SDK loads and all queued events
-flush:
-
-```typescript
-destinations: {
-  segment: {
-    code: destinationSegment,
-    config: {
-      consent: { analytics: true },
-      settings: { apiKey: 'WRITE_KEY' },
-    },
-  },
-}
-```
-
-This is the primary consent mechanism for Segment, since Segment's SDK has no
-`optOut()` method - the only way to enforce consent is to avoid loading the SDK
-in the first place.
-
-## Reset (Logout)
-
-```typescript
-mapping: {
-  user: {
-    logout: {
-      silent: true,
-      settings: {
-        reset: true,
-      },
-    },
-  },
-}
-```
-
-`analytics.reset()` clears the stored `userId`, `anonymousId`, and traits, then
-generates a fresh anonymous ID.
-
-## Scope Notes
+## Documentation
 
-- **`alias()` and `screen()`** are intentionally deferred. `alias()` is a legacy
-  identity-linking method (most identity resolution happens server-side in
-  Segment Profiles); `screen()` is mobile-only.
-- **Plugins, source middleware, and destination middleware** cannot be
-  serialized in JSON flow configs. Register them programmatically on the
-  returned `AnalyticsBrowser` instance if needed.
+Full configuration, mapping, and examples live in the docs:
+**https://www.walkeros.io/docs/destinations/web/segment**
 
 ## Contribute
 
@@ -369,4 +54,4 @@ Feel free to contribute by submitting an
 
 ## License
 
-This project is licensed under the MIT License.
+MIT