@walkeros/server-source-fetch

Web Standard Fetch API source for walkerOS - Deploy to any modern edge/serverless platform

What This Source Does

Accepts walkerOS events via HTTP (Fetch API) Forwards events to collector for processing Returns HTTP responses with CORS support

This is an HTTP transport layer - it accepts events in walkerOS format and forwards them to the collector. Not a transformation source.

Features

• ✅ Web Standard Fetch API - Native (Request) => Response signature
• ✅ Platform Agnostic - Cloudflare Workers, Vercel Edge, Deno, Bun, Node.js 18+
• ✅ Event Validation - Zod schema validation with detailed error messages
• ✅ Batch Processing - Handle multiple events in single request
• ✅ CORS Support - Configurable cross-origin resource sharing
• ✅ Pixel Tracking - 1x1 transparent GIF for GET requests
• ✅ Request Limits - Configurable size and batch limits
• ✅ Health Checks - Built-in /health endpoint

Installation

npm install @walkeros/server-source-fetch @walkeros/collector @walkeros/core

Quick Start

import { sourceFetch, type SourceFetch } from '@walkeros/server-source-fetch';
import { startFlow } from '@walkeros/collector';

const { elb } = await startFlow<SourceFetch.Push>({
  sources: { api: { code: sourceFetch } },
});

export default { fetch: elb };

Platform Deployment

Cloudflare Workers

import { sourceFetch, type SourceFetch } from '@walkeros/server-source-fetch';
import { startFlow } from '@walkeros/collector';

const { elb } = await startFlow<SourceFetch.Push>({
  sources: {
    api: {
      code: sourceFetch,
      config: { settings: { cors: true } },
    },
  },
  destinations: {
    // Your destinations
  },
});

export default { fetch: elb };

Deploy: wrangler deploy

Vercel Edge Functions

// api/collect.ts
export const config = { runtime: 'edge' };

import { sourceFetch, type SourceFetch } from '@walkeros/server-source-fetch';
import { startFlow } from '@walkeros/collector';

const { elb } = await startFlow<SourceFetch.Push>({
  sources: { api: { code: sourceFetch } },
});

export default elb;

Deno Deploy

import { sourceFetch, type SourceFetch } from '@walkeros/server-source-fetch';
import { startFlow } from '@walkeros/collector';

const { elb } = await startFlow<SourceFetch.Push>({
  sources: { api: { code: sourceFetch } },
});

Deno.serve(elb);

Bun

import { sourceFetch, type SourceFetch } from '@walkeros/server-source-fetch';
import { startFlow } from '@walkeros/collector';

const { elb } = await startFlow<SourceFetch.Push>({
  sources: { api: { code: sourceFetch } },
});

Bun.serve({ fetch: elb, port: 3000 });

Usage Examples

Single Event (POST)

fetch('https://your-endpoint.com/collect', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'page view',
    data: { title: 'Home', path: '/' },
    user: { id: 'user-123' },
    globals: { language: 'en' },
  }),
});

Batch Events (POST)

fetch('https://your-endpoint.com/collect', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    batch: [
      { name: 'page view', data: { title: 'Home' } },
      { name: 'button click', data: { id: 'cta' } },
      { name: 'form submit', data: { formId: 'contact' } },
    ],
  }),
});

Pixel Tracking (GET)

<img
  src="https://your-endpoint.com/collect?event=page%20view&data[title]=Home&user[id]=user123"
  width="1"
  height="1"
/>

Health Check

curl https://your-endpoint.com/health
# {"status":"ok","timestamp":1234567890,"source":"fetch"}

Configuration

interface Settings {
  path: string; // Collection path (default: '/collect')
  cors: boolean | CorsOptions; // CORS config (default: true)
  healthPath: string; // Health check path (default: '/health')
  maxRequestSize: number; // Max bytes (default: 102400 = 100KB)
  maxBatchSize: number; // Max events per batch (default: 100)
}

interface CorsOptions {
  origin?: string | string[] | '*';
  methods?: string[];
  headers?: string[];
  credentials?: boolean;
  maxAge?: number;
}

Error Responses

Validation Error

{
  "success": false,
  "error": "Event validation failed",
  "validationErrors": [
    { "path": "name", "message": "Event name is required" },
    { "path": "nested.0.entity", "message": "Required" }
  ]
}

Batch Partial Failure (207 Multi-Status)

{
  "success": false,
  "processed": 2,
  "failed": 1,
  "errors": [
    { "index": 1, "error": "Validation failed: Event name is required" }
  ]
}

Input Format

Accepts standard walkerOS events. See @walkeros/core Event documentation.

Required field:

• name (string) - Event name in "entity action" format (e.g., "page view")

Optional fields:

• data - Event-specific properties
• user - User identification
• context - Ordered context properties
• globals - Global properties
• custom - Custom properties
• nested - Nested entities
• consent - Consent flags

Testing

npm test        # Run tests
npm run dev     # Watch mode
npm run lint    # Type check + lint
npm run build   # Build package

Development

Follows walkerOS XP principles:

• DRY - Uses @walkeros/core utilities
• KISS - Minimal HTTP wrapper
• TDD - Example-driven tests
• No any - Strict TypeScript

See AGENT.md for walkerOS development guide.

Related

• understanding-sources skill
• using-logger skill
• @walkeros/server-source-express - Alternative for Express.js
• @walkeros/core - Core utilities

License

MIT