name: understanding-events description: Use when creating events, understanding event structure, or working with event properties. Covers entity-action naming, event properties, statelessness, and vendor-agnostic design.

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.

// Correct
'page view';
'product add';
'order complete';
'button click';

// Wrong
'page_view'; // underscore
'pageview'; // no separator
'purchase'; // no entity
'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).

data Property

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

// product entity
data: { id: "P123", name: "Laptop", price: 999, currency: "USD" }

// page entity
data: { title: "Home", path: "/", referrer: "https://..." }

context Property

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

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

globals Property

Properties that apply to ALL events in the session.

globals: {
  language: "en",
  currency: "USD",
  environment: "production"
}

nested Property

Related entities captured together.

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

user Property

User identification across sessions.

user: {
  id: "user123",        // Your user ID
  device: "device456",  // Device fingerprint
  session: "sess789"    // Session ID
}

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

import { elb } from '@walkeros/collector';

// Basic event
await elb('page view', { title: 'Home', path: '/' });

// With all properties
await elb(
  'product add',
  { id: 'P123', price: 99 }, // data
  { stage: ['cart', 1] }, // context (optional)
  { currency: 'USD' }, // globals (optional)
);

Related

Skills:

• understanding-mapping skill - Transform events for destinations

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