elb

.changeset/collector-elb-arguments.md

@@ -0,0 +1,12 @@
+---
+'@walkeros/collector': patch
+---
+
+`elb` takes an event object,
+`elb({ name, data, trigger, context, nested, custom })`, a command,
+`elb('walker <command>', data)`, or the string form
+`elb('entity action', data)`. The positional `context`, `nested` and `custom`
+arguments are gone, and a second argument after an event object is no longer
+merged into `data`. Such arguments are ignored and reported as an error. The
+string form takes `data` only when it is a plain object; before, any non-array
+object, such as an element or a date, was taken.

.changeset/frame-links.md

@@ -1,5 +1,5 @@
 ---
-'@walkeros/mcp': minor
+'@walkeros/mcp': patch
 '@walkeros/cli': patch
 ---
 

.changeset/web-source-browser-elb-event-copy.md

@@ -0,0 +1,19 @@
+---
+'@walkeros/web-source-browser': patch
+---
+
+`elb` takes an event object,
+`elb({ name, data, trigger, context, nested, custom })`, or a `walker` command.
+The string form `elb('entity action', data)` still works and sends exactly
+`{ name, data }`. Any argument after `data` or after the event object, and
+`data` that is not an object (such as an element), is ignored and reported as an
+error: put trigger, context, nested and custom inside the event object. The
+types `BrowserArguments`, `BrowserPushData`, `BrowserPushOptions` and
+`BrowserPushContext` are removed.
+
+The automatic page view uses the path as `data.id` unless the page tags an id; a
+page event you push keeps its `data` as written. `elb` no longer writes `source`
+or `globals` onto the event or `data` object you pass in.
+
+An event that carries its own `globals` keeps the globals tagged on the page as
+well; the event's values win per key.

.github/workflows/website.yml

@@ -65,11 +65,20 @@ jobs:
           cache: 'npm'
       - run: npm ci
 
+      # The source checks take seconds and need only core's `dev` export, so
+      # they run before the website build: a docs error fails in about two
+      # minutes, not after the build. The website build reuses this core build.
+      - name: Validate docs sources
+        run: |
+          npx turbo run build --filter=@walkeros/core
+          npm run validate:sources
+
       - name: Build website
         run: npm run build:website
 
-      - name: Validate docs and LLM export
-        run: npm run validate
+      # Reads the build output, so it runs after the build.
+      - name: Validate LLM export
+        run: npm run validate:llms
 
       - name: Deploy to production
         if:
@@ -102,11 +111,12 @@ jobs:
         if: github.event_name == 'pull_request'
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         env:
-          BUNNY_PULLZONE_URL: ${{ secrets.BUNNY_WEBSITE_PULLZONE_URL }}
           PR_NUM: ${{ github.event.pull_request.number }}
         with:
           script: |
-            const previewUrl = `${process.env.BUNNY_PULLZONE_URL}/preview/pr-${process.env.PR_NUM}/`;
+            // The public host serves the same pull zone as the CDN host the
+            // deploy purges through.
+            const previewUrl = `https://www.walkeros.io/preview/pr-${process.env.PR_NUM}/`;
             const body = `### Preview deployed\n\n${previewUrl}`;
 
             // Find existing comment

README.md

@@ -86,7 +86,7 @@ const { elb } = await startFlow({
   },
 });
 
-await elb('page view', { title: 'Home' });
+await elb({ name: 'page view', data: { title: 'Home' } });
 // -> logs: Event: page view
 ```
 

apps/demos/flows/README.md

@@ -309,7 +309,8 @@ echo "walker.js available at: $SERVE_URL/walker.js"
 1. **Click buttons** - See events in the visual console
 2. **Open Network tab** - Events go to YOUR endpoint, not google-analytics.com
 3. **Open BigQuery** - Events arrive in your database
-4. **Browser console** - `elb('custom event', { data: 'here' })`
+4. **Browser console** -
+   `elb({ name: 'custom event', data: { label: 'here' } })`
 
 ---
 

apps/demos/flows/index.html

@@ -92,16 +92,16 @@ <h1>walkerOS Flow Demo</h1>
     <div class="card">
       <h2>Quick Events</h2>
       <div class="btn-grid">
-        <button class="btn btn-primary" onclick="elb('page view', { title: 'Demo Page' })">
+        <button class="btn btn-primary" onclick="elb({ name: 'page view', data: { title: 'Demo Page' } })">
           Page View
         </button>
-        <button class="btn btn-success" onclick="elb('button click', { label: 'CTA Button' })">
+        <button class="btn btn-success" onclick="elb({ name: 'button click', data: { label: 'CTA Button' } })">
           Button Click
         </button>
-        <button class="btn btn-warning" onclick="elb('form submit', { form: 'newsletter' })">
+        <button class="btn btn-warning" onclick="elb({ name: 'form submit', data: { form: 'newsletter' } })">
           Form Submit
         </button>
-        <button class="btn btn-purple" onclick="elb('order complete', { orderId: 'ORD-' + Date.now(), total: 99.99 })">
+        <button class="btn btn-purple" onclick="elb({ name: 'order complete', data: { orderId: 'ORD-' + Date.now(), total: 99.99 } })">
           Order Complete
         </button>
       </div>
@@ -128,7 +128,7 @@ <h2>Batch Demo (hover to trigger)</h2>
 
     <div class="info">
       <strong>Try in browser console:</strong>
-      <code>elb('custom event', { any: 'data' })</code>
+      <code>elb({ name: 'custom event', data: { any: 'data' } })</code>
       <br><br>
       <strong>Check Network tab:</strong> Events go to <code>walkeros-demo-xxx.run.app/collect</code> (YOUR endpoint)
     </div>

apps/demos/react/README.md

@@ -76,10 +76,9 @@ Track events manually from React components:
 
 ```typescript
 // Track custom event
-window.elb('custom event', {
-  category: 'interaction',
-  action: 'button_click',
-  label: 'cta',
+window.elb({
+  name: 'custom event',
+  data: { category: 'interaction', action: 'button_click', label: 'cta' },
 });
 
 // Update consent

apps/demos/storybook/src/shared/controls.test.ts

@@ -1,8 +1,7 @@
-import type { SourceBrowser } from '@walkeros/web-source-browser';
-import { elbAtApplyFrom } from './controls';
+import { elbAtApplyFrom, type PageElb } from './controls';
 
 test('looks the elb up at each call, not when made', async () => {
-  let running: SourceBrowser.Push | undefined = undefined;
+  let running: PageElb | undefined = undefined;
   const elb = elbAtApplyFrom(() => running);
 
   expect(await elb('walker init', document.body)).toStrictEqual({

apps/demos/storybook/src/shared/controls.ts

@@ -1,3 +1,4 @@
+import type { Elb } from '@walkeros/core';
 import type { SourceBrowser } from '@walkeros/web-source-browser';
 import type { DemoConsent } from './consent';
 import type { Language } from './language';
@@ -22,6 +23,12 @@ export interface DemoPageProps {
   controls: DemoControls;
 }
 
+/**
+ * A page global elb as the page holds it: a function the page calls with
+ * whatever arguments it has. The browser source reports the ones it ignores.
+ */
+export type PageElb = (...args: unknown[]) => Promise<Elb.PushResult>;
+
 /** Why a command was not sent: no walkerOS runs on the page (yet). */
 export const notRunning = 'walkerOS is not running.';
 
@@ -32,9 +39,9 @@ export const notRunning = 'walkerOS is not running.';
  * `{ ok: false }` with the reason, which ViewSource shows.
  */
 export function elbAtApplyFrom(
-  getElb: () => SourceBrowser.Push | undefined,
+  getElb: () => PageElb | undefined,
 ): SourceBrowser.Push {
-  return (...args: Parameters<SourceBrowser.BrowserArguments>) => {
+  return (...args: unknown[]) => {
     const elb = getElb();
     return elb
       ? elb(...args)

apps/demos/storybook/src/shared/stories/useStoryControls.ts

@@ -1,7 +1,6 @@
 import { useState } from 'react';
-import type { SourceBrowser } from '@walkeros/web-source-browser';
 import { useDemoConsent } from '../consent';
-import { elbAtApplyFrom, type DemoControls } from '../controls';
+import { elbAtApplyFrom, type DemoControls, type PageElb } from '../controls';
 import type { Language } from '../language';
 import type { PersonaKey } from '../personas';
 
@@ -10,7 +9,7 @@ import type { PersonaKey } from '../personas';
 // when it failed to).
 declare global {
   interface Window {
-    __storybookElb?: SourceBrowser.Push;
+    __storybookElb?: PageElb;
   }
 }
 

apps/demos/storybook/src/site/walkerjs.ts

@@ -1,4 +1,4 @@
-import type { SourceBrowser } from '@walkeros/web-source-browser';
+import type { PageElb } from '../shared/controls';
 
 /**
  * The managed walker.js of the app flow "Tagging demo", the one the static
@@ -11,7 +11,7 @@ export const WALKER_JS_URL =
 // Narrowed by `typeof`: on this page only the queue below or walker.js's
 // push sits there. The global's own type (`Elb.Fn`) lacks the browser-only
 // commands ViewSource sends, such as `walker init`.
-const isPush = (value: unknown): value is SourceBrowser.Push =>
+const isPush = (value: unknown): value is PageElb =>
   typeof value === 'function';
 
 /**
@@ -23,17 +23,15 @@ const isPush = (value: unknown): value is SourceBrowser.Push =>
 export function installElbQueue(win: Window): void {
   const existing: unknown = win.elb;
   if (isPush(existing)) return;
-  const queue: SourceBrowser.Push = (
-    ...args: Parameters<SourceBrowser.BrowserArguments>
-  ) => {
+  const queue: PageElb = (...args) => {
     (win.elbLayer = win.elbLayer || []).push(args);
     return Promise.resolve({ ok: true });
   };
   win.elb = queue;
 }
 
 /** The page's elb right now: the queue until walker.js runs, then its push. */
-export function currentElb(win: Window): SourceBrowser.Push | undefined {
+export function currentElb(win: Window): PageElb | undefined {
   const elb: unknown = win.elb;
   return isPush(elb) ? elb : undefined;
 }

apps/explorer/design/components/src/viz.jsx

@@ -79,9 +79,9 @@ const MEVENTS = [
     ] },
 ];
 const MSHORT = {
-  product: "elb('product view', { id: 'ers', price: 420, currency: 'EUR' })",
-  lead: "elb('lead submit', { type: 'demo', value: 2500, currency: 'EUR' })",
-  order: "elb('order complete', { id: '0rd3r1d', value: 462, currency: 'EUR' })",
+  product: "elb({ name: 'product view', data: { id: 'ers', price: 420, currency: 'EUR' } })",
+  lead: "elb({ name: 'lead submit', data: { type: 'demo', value: 2500, currency: 'EUR' } })",
+  order: "elb({ name: 'order complete', data: { id: '0rd3r1d', value: 462, currency: 'EUR' } })",
 };
 
 function DestinationMappingViz(props) {

apps/explorer/src/components/molecules/__tests__/view-source.test.tsx

@@ -47,10 +47,9 @@ const edit = `<div data-elb="promotion" data-elbaction="visible:view">
 </div>`;
 
 function elbResolving(result: Elb.PushResult) {
-  return jest.fn<
-    ReturnType<SourceBrowser.BrowserArguments>,
-    Parameters<SourceBrowser.BrowserArguments>
-  >(() => Promise.resolve(result));
+  return jest.fn<Promise<Elb.PushResult>, unknown[]>(() =>
+    Promise.resolve(result),
+  );
 }
 
 type Queries = ReturnType<typeof render>;
@@ -300,17 +299,13 @@ describe('ViewSource', () => {
     ['walker init fails', elbResolving({ ok: false, error: 'not running' })],
     [
       'walker init rejects',
-      jest.fn<
-        ReturnType<SourceBrowser.BrowserArguments>,
-        Parameters<SourceBrowser.BrowserArguments>
-      >(() => Promise.reject(new Error('gone'))),
+      jest.fn<Promise<Elb.PushResult>, unknown[]>(() =>
+        Promise.reject(new Error('gone')),
+      ),
     ],
     [
       'elb throws',
-      jest.fn<
-        ReturnType<SourceBrowser.BrowserArguments>,
-        Parameters<SourceBrowser.BrowserArguments>
-      >(() => {
+      jest.fn<Promise<Elb.PushResult>, unknown[]>(() => {
         throw new Error('broken');
       }),
     ],

apps/explorer/src/components/molecules/view-source.stories.tsx

@@ -24,13 +24,14 @@ type Story = StoryObj<typeof ViewSource>;
 // The Actions panel stands in for the page's walkerOS: it logs the call and
 // accepts it.
 const logInit = action('elb');
+const actionsElb: SourceBrowser.Push = async (...args: unknown[]) => {
+  logInit(...args);
+  return { ok: true };
+};
 
 export const TaggedSample: Story = {
   args: {
-    elb: async (...args: Parameters<SourceBrowser.BrowserArguments>) => {
-      logInit(...args);
-      return { ok: true };
-    },
+    elb: actionsElb,
     children: (
       <section
         data-elb="promotion"

apps/explorer/src/design/components/viz/__tests__/format.test.ts

@@ -77,14 +77,16 @@ describe('formatCall', () => {
 });
 
 describe('formatElb', () => {
-  it('prints a flat event as elb(name, data)', () => {
+  it('prints a flat event as a partial event', () => {
     expect(
       formatElb({
         entity: 'product',
         action: 'view',
         data: { id: 'ers', price: 420, currency: 'EUR' },
       }),
-    ).toBe("elb('product view', { id: 'ers', price: 420, currency: 'EUR' })");
+    ).toBe(
+      "elb({ name: 'product view', data: { id: 'ers', price: 420, currency: 'EUR' } })",
+    );
   });
 
   it('prints an event with nested entities as an object, nested abbreviated', () => {

apps/explorer/src/design/components/viz/parts/format.ts

@@ -94,15 +94,19 @@ export function formatCall(record: CallRecord): string[] {
   ];
 }
 
-/** The `elb()` call that sends `event`; nested entities are abbreviated. */
+/** The `elb()` call that sends `event`, as a partial event; nested entities are abbreviated. */
 export function formatElb(event: ElbShape): string {
-  const name = literal(`${event.entity} ${event.action}`);
-  const data = literal(event.data);
-  if (!event.nested?.length) return `elb(${name}, ${data})`;
-  const nested = event.nested.map(
-    (entity) => `{ entity: ${literal(entity.entity)}, … }`,
-  );
-  return `elb({ name: ${name}, data: ${data}, nested: [${nested.join(', ')}] })`;
+  const fields = [
+    `name: ${literal(`${event.entity} ${event.action}`)}`,
+    `data: ${literal(event.data)}`,
+  ];
+  if (event.nested?.length) {
+    const nested = event.nested.map(
+      (entity) => `{ entity: ${literal(entity.entity)}, … }`,
+    );
+    fields.push(`nested: [${nested.join(', ')}]`);
+  }
+  return `elb({ ${fields.join(', ')} })`;
 }
 
 const TOKEN = /"[^"]*"|'[^']*'|\d+(?:\.\d+)?|[A-Za-z_]\w*|\s+|./g;

apps/quickstart/src/first-event.ts

@@ -19,7 +19,7 @@ export async function firstEvent(): Promise<string[]> {
     },
   });
 
-  await elb('page view', { title: 'Home' });
+  await elb({ name: 'page view', data: { title: 'Home' } });
 
   return seen;
 }

apps/quickstart/src/ga4-ecommerce.ts

@@ -55,10 +55,9 @@ export async function ga4AddToCart(): Promise<unknown[]> {
     },
   });
 
-  await elb('product add', {
-    id: 'ers',
-    name: 'Everyday Ruck Snack',
-    price: 420,
+  await elb({
+    name: 'product add',
+    data: { id: 'ers', name: 'Everyday Ruck Snack', price: 420 },
   });
 
   // The destination's init emits gtag('js', ...) and gtag('config', ...) first,