Understanding walkerOS Events

Overview

walkerOS events are self-describing, stateless, vendor-agnostic data structures. They capture user interactions in a standardized format that can be transformed for any destination.

Core principle: Events describe WHAT happened, not WHERE it goes. Stateless. Self-describing. Industry-agnostic.

Entity-Action Naming (Critical)

STRICT REQUIREMENT: All events use "entity action" format with space separation.

typescript
1// Correct
2'page view';
3'product add';
4'order complete';
5'button click';
6
7// Wrong
8'page_view'; // underscore
9'pageview'; // no separator
10'purchase'; // no entity
11'add_to_cart'; // wrong format

Parsing: const [entity, action] = event.split(' ')

• Entity: Noun (page, product, user, order, button)
• Action: Verb (view, add, complete, click, login)

Event Properties

See packages/core/src/types/walkeros.ts for canonical types (Event interface, plus event helpers in event.ts).

data Property

Entity-specific properties. Schema-free but consistent within entity type.

typescript
1// product entity
2data: { id: "P123", name: "Laptop", price: 999, currency: "USD" }
3
4// page entity
5data: { title: "Home", path: "/", referrer: "https://..." }

context Property

Hierarchical state information. Format: { name: [value, order] }

typescript
1context: {
2  stage: ["checkout", 1],    // checkout stage, first step
3  test: ["variant-A", 0],    // A/B test variant
4  group: ["premium", 2]      // user segment
5}

globals Property

Properties that apply to ALL events in the session.

typescript
1globals: {
2  language: "en",
3  currency: "USD",
4  environment: "production"
5}

nested Property

Related entities captured together.

typescript
1// Order with line items
2nested: [
3  { type: 'product', data: { id: 'P1', quantity: 2 } },
4  { type: 'product', data: { id: 'P2', quantity: 1 } },
5];

user Property

User identification across sessions.

typescript
1user: {
2  id: "user123",        // Your user ID
3  device: "device456",  // Device fingerprint
4  session: "sess789"    // Session ID
5}

Design Principles

Statelessness

Events are immutable snapshots. They don't reference previous events or maintain state.

Self-Describing

Events contain all context needed to understand them. No external lookups required.

Vendor-Agnostic

Events use generic concepts (product, order) not vendor-specific (GA4 item, FB content).

Transformation to vendor formats happens in mapping, not in event creation.

Creating Events

typescript
1import { elb } from '@walkeros/collector';
2
3// Basic event
4await elb('page view', { title: 'Home', path: '/' });
5
6// With all properties
7await elb(
8  'product add',
9  { id: 'P123', price: 99 }, // data
10  { stage: ['cart', 1] }, // context (optional)
11  { currency: 'USD' }, // globals (optional)
12);

Related Skills

• walkeros-understanding-mapping - Transform events for destinations
• walkeros-understanding-flow - Data flow architecture

Source Files:

• packages/core/src/types/walkeros.ts - Event types
• packages/core/src/schemas/ - Event schemas

Documentation:

• Website: Event Model - User-facing docs
• walkeros.io/docs - Public documentation