/walkeros-create-destination

name: walkeros-create-destination
description: >-
  Use when creating a new walkerOS destination to send events to a vendor or API
  (GA4/gtag, Meta/Facebook Pixel, Mixpanel, Amplitude, a custom HTTP API,
  Measurement Protocol), web or server-side. Example-driven workflow: research
  the vendor SDK and define step examples before implementing the destination
  interface, env pattern, and mappings.

Create a New Destination

Prerequisites

Before starting, read these skills:

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

destinations fit in architecture

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

Destination interface

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

Transformer chaining to destinations

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

transformation

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

env pattern (Phase 3 + Phase 8)

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

Authoritative pattern for `Flow.StepExample` structure and Three Type Zones

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

Documentation standards (for Phase 9)

Choose Your Template

| Complexity | Template | When to Use | | ---------- | ------------ | ----------------------------------- | | Simple | `plausible/` | Single SDK call, minimal config | | Complex | `gtag/` | Multiple services, sub-destinations | | Server | `gcp/` | Server-side, batching, SDK init |

Process Overview

1. Research     → Deeply understand vendor SDK, API, and event taxonomy
2. Classify     → Determine vendor taxonomy type and integration approach
3. Examples     → Define in/out pairs FIRST (start with the end result)
4. Mapping      → Define walkerOS → vendor 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 vendor SDK 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, batching, retries, and plugin ecosystems — 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, not just

`track()`. Identity methods, property operations, group management, specialized event types (revenue, etc.)

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

# Install and inspect actual types
npm install @vendor/analytics-browser
ls node_modules/@vendor/analytics-browser/lib/esm/

1.2 Understand SDK Architecture

• [ ] **Init options** — What does `init()` accept? What can be configured?
• [ ] **Call ordering** — Can you call methods before `init()`? Is there

internal queuing? What are the race condition implications?

• [ ] **Plugin system** — Does the SDK support plugins? How are they added?
• [ ] **Identity management** — How does the SDK handle user/device/session IDs?

Does it manage cookies/storage? Can this be disabled (since walkerOS manages identity)?

• [ ] **Consent** — Does the SDK have a consent mode or just binary opt-out?

1.3 Identify All Event Methods

Go beyond just `track()`. Most SDKs have specialized methods:

| Method Category | Examples | walkerOS Handling | | ---------------- | ----------------------------------- | ------------------- | | Event tracking | `track()`, `logEvent()` | Default `push()` | | User properties | `identify()`, `setUserProperties()` | `mapping.settings` | | Revenue/purchase | `revenue()`, `purchase()` | `mapping.settings` | | Groups/accounts | `setGroup()`, `groupIdentify()` | `mapping.settings` | | Identity setters | `setUserId()`, `setDeviceId()` | `settings.identify` | | Opt-out | `setOptOut()`, `consent()` | `on('consent')` | | Cleanup | `flush()`, `reset()` | `destroy()` |

1.4 Check Existing Patterns

Review similar destinations in the codebase:

ls packages/web/destinations/

Gate: Research Complete

• [ ] Official SDK installed and types inspected
• [ ] All public methods listed with their purpose
• [ ] Init options understood (what to disable, what to pass through)
• [ ] Call ordering / race conditions understood
• [ ] Identity, consent, and plugin patterns documented

Checkpoint: Research Review (Optional)

If working with human oversight, pause here to confirm:

• SDK integration approach correct?
• Event mapping makes sense for the use case?
• Any vendor quirks or limitations to handle?

---

Phase 2: Classify Vendor Taxonomy

**Goal:** Understand what the vendor expects, which determines destination complexity.

2.1 Taxonomy Types

| Type | Description | Mapping Needed | Example Vendors | | ---------------- | ---------------------------------------------- | -------------------------------------- | --------------------- | | **Free-form** | Any event name accepted, no prescribed schema | Minimal — names pass through | Most modern analytics | | **Rigid** | Prescribed event names unlock specific reports | Essential — must map to exact names