/walkeros-create-source

name: walkeros-create-source
description: >-
  Use when creating a new walkerOS source to capture events (browser source,
  dataLayer interception, server/HTTP source, webhook receiver, event capture),
  web or server-side. Example-driven workflow: research the input format and
  define step examples before implementing the push interface, createTrigger,
  and env pattern.

Create a New Source

Prerequisites

Before starting, read these skills:

• [understanding-flow](../walkeros-understanding-flow/SKILL.md) - How sources

fit in architecture

• [understanding-sources](../walkeros-understanding-sources/SKILL.md) - Source

interface

• [understanding-transformers](../walkeros-understanding-transformers/SKILL.md) -

Transformer chaining from sources

• [understanding-events](../walkeros-understanding-events/SKILL.md) - Event

structure sources emit

• [understanding-mapping](../walkeros-understanding-mapping/SKILL.md) -

Transform raw input to events

• [testing-strategy](../walkeros-testing-strategy/SKILL.md) - How to test with

env pattern and dev examples

• [using-step-examples](../walkeros-using-step-examples/SKILL.md) -

Authoritative `Flow.StepExample` pattern, `createTrigger`, Three Type Zones

• [using-logger](../walkeros-using-logger/SKILL.md) - For an HTTP source, see

"Choosing a level on public endpoints": rejected client input is debug or warn plus a `rejected` counter and a 4xx, never an error-level log

• [writing-documentation](../walkeros-writing-documentation/SKILL.md) -

Documentation standards (for Phase 9)

Source Types

A source's identity is split into two fields:

| Field | Meaning | Examples | | ----------------- | --------------------------------------------------------------- | ---------------------------------------------- | | `source.type` | The kind of source (its role / mechanism) | `browser`, `dataLayer`, `cookiefirst`, `fetch` | | `source.platform` | The runtime that hosts the source (`web`, `server`, `app`, ...) | `web`, `server` |

| Platform | Input | Example types | | -------- | ----------------------- | ----------------------------------- | | `web` | DOM events, dataLayer | `browser`, `dataLayer` | | `server` | HTTP requests, webhooks | `gcp`, `express`, `lambda`, `fetch` |

Augmenting `SourceMap`

Every source registers its `type` literal and any source-specific `source.*` fields by augmenting `SourceMap` from `@walkeros/core`. This is how the collector and downstream consumers know about the new source kind without loosening the union to `string`.

Add this to the source's `src/types.ts` (or `src/types/index.ts`):

import type { Source, Elb } from '@walkeros/core';

declare module '@walkeros/core' {
  interface SourceMap {
    // Replace `mySource` with the source's package-level identifier.
    mySource: {
      type: 'mySource'; // matches the literal you return from Source.Init
      platform?: 'web'; // 'web' | 'server' | 'app' | ...
      // Add any extra fields the source surfaces in `event.source.*` here.
      // e.g. `version?: string;` is already on the base Source - only add
      // truly source-specific keys.
    };
  }
}

Reference implementations: `packages/web/sources/browser/src/types/index.ts`, `packages/web/sources/demo/src/types.ts`. Conflicting declarations cause compile errors on purpose, this surfaces naming collisions early.

Source Categories

| Category | Purpose | Examples | Key Concern | | ------------------ | ----------------------------------------- | ----------------------- | -------------------- | | **Transformation** | Convert external format → walkerOS events | `dataLayer`, `fetch` | Mapping accuracy | | **Transport** | Receive events from specific platform | `gcp`, `aws`, `express` | Platform integration |

Choose Your Template

| Complexity | Template | When to Use | | --------------------- | -------------- | ------------------------------------- | | Simple transformation | `fetch/` | Generic HTTP handler, data conversion | | Platform transport | `gcp/`, `aws/` | Cloud platform integration | | Browser interception | `dataLayer/` | DOM events, array interception |

Process Overview

1. Research     → Deeply understand external system, SDK, and data format
2. Classify     → Determine source type and integration approach
3. Examples     → Define in/out pairs FIRST (start with the end result)
4. Mapping      → Define input → walkerOS event transformation
5. Scaffold     → Copy template and configure
6. Convention   → Add walkerOS.json metadata and buildDev
7. Implement    → Build using examples as test fixtures
8. Test         → Verify against example variations
9. Document     → Write README

---

Phase 1: Research

**Goal:** Deeply understand the external system before writing any code. Research quality determines implementation quality.

1.1 Find and Install Official SDK

Always prefer the vendor's official SDK package over raw HTTP API calls. The SDK handles transport, data formatting, and platform specifics - don't reinvent these.

• [ ] **Install the SDK** - `npm install @vendor/sdk` and read the actual source
• [ ] **Read TypeScript types** - Import types from the SDK package directly.

Never duplicate type definitions. This ensures IntelliSense completeness and consistency with SDK updates.

• [ ] **Understand the full API surface** - List every public method and type

export. What data structures does the platform provide? What request/event formats exist?

# Search npm for official packages
npm search [vendor-name]
npm search @[vendor]

# Install