understanding-sources
Use when working with sources, understanding event capture, or learning about the push interface. Covers browser, dataLayer, and server source patterns.
When & Why to Use This Skill
This Claude skill provides a comprehensive technical guide to walkerOS sources, the fundamental components responsible for event capture. It explains the core principles of data ingestion across browser DOM, GTM-style dataLayers, and server-side cloud functions. By detailing the context-based initialization patterns and the universal push interface, this skill enables developers to architect and implement robust, scalable tracking infrastructures that bridge the gap between external triggers and data collectors.
Use Cases
- Web Tracking Architecture: Implementing browser-based event capture using data attributes to track user interactions without complex JavaScript wrappers.
- DataLayer Integration: Synchronizing walkerOS with existing Google Tag Manager (GTM) setups by capturing events directly from the window.dataLayer array.
- Server-Side Event Ingestion: Designing cloud function handlers (e.g., GCP) to transform incoming HTTP requests into standardized walkerOS events for server-side tracking.
- Custom Source Development: Utilizing the TypeScript Source.Init interface and context patterns to build proprietary data sources for unique environment requirements.
| name | understanding-sources |
|---|
Understanding walkerOS Sources
Overview
Sources capture events from the external world (browser DOM, dataLayer, HTTP requests, cloud functions) and feed them to the collector.
Core principle: Sources capture. They don't process or deliver—that's collector and destinations.
Source Interface
See packages/core/src/types/source.ts for canonical interface.
Init Function (Context Pattern)
Sources use a context-based initialization pattern:
import type { Source } from '@walkeros/core';
export const sourceMySource: Source.Init<Types> = async (context) => {
const { config = {}, env, logger, id } = context;
// ...
};
Context contains:
| Property | Type | Purpose |
|---|---|---|
config |
Source.Config<T> |
Settings, mapping, options |
env |
Types['env'] |
Environment (push, logger) |
logger |
Logger |
Logging functions |
id |
string |
Source identifier |
collector |
Collector.Instance |
Reference to collector |
Push Method
| Method | Purpose |
|---|---|
push(input) |
Receive external input, emit events |
Push Signatures by Type
| Source Type | Signature | Example |
|---|---|---|
| Cloud Function | push(req, res) → Promise<void> |
HTTP handler |
| Browser | push(event, data) → Promise<void> |
DOM events |
| DataLayer | push(event, data) → Promise<void> |
GTM-style |
Key insight: Source push IS the handler. No wrappers needed.
// Direct deployment
http('handler', source.push);
Source Paths
| Type | Path | Examples |
|---|---|---|
| Web | packages/web/sources/ |
browser, dataLayer |
| Server | packages/server/sources/ |
gcp |
Browser Source
The browser source captures events from DOM using data attributes.
<button data-elb="product" data-elb-product="id:P123;name:Laptop">
<span data-elbaction="click">Add to Cart</span>
</button>
See packages/web/sources/browser/ for implementation.
DataLayer Source
Captures events from a GTM-style dataLayer array.
window.dataLayer.push({
event: 'product view',
product: { id: 'P123', name: 'Laptop' },
});
See packages/web/sources/dataLayer/ for implementation.
Server Sources
Handle HTTP requests in cloud functions. Server sources use the context pattern:
import type { Source } from '@walkeros/core';
export const sourceCloudFunction: Source.Init<Types> = async (context) => {
const { config = {}, env } = context;
const { push: envPush } = env;
// Validate settings with Zod schema
const settings = SettingsSchema.parse(config.settings || {});
const push = async (req: Request, res: Response): Promise<void> => {
// Transform HTTP request → walkerOS event
const event = transformRequest(req);
await envPush(event);
res.json({ success: true });
};
return { type: 'cloudfunction', config: { ...config, settings }, push };
};
// Direct deployment
export const handler = source.push;
See packages/server/sources/gcp/ for implementation.
Transformer Wiring
Sources can wire to pre-collector transformer chains via the next property:
sources: {
browser: {
code: sourceBrowser,
next: 'validate' // First transformer to run after this source
}
}
The transformer chain runs before events reach the collector. See understanding-transformers for chain details.
Related
Skills:
- understanding-flow skill - How sources fit in architecture
- understanding-transformers skill - Transformer chaining from sources
- understanding-events skill - Events that sources emit
Source Files:
- packages/core/src/types/source.ts - Interface
Package READMEs:
- packages/web/sources/browser/README.md - Browser source
- packages/web/sources/dataLayer/README.md - DataLayer source
Documentation:
- Website: Sources - Overview
- Website: Browser Source - Browser docs
- Website: Create Your Own - Guide