Web API Destination for walkerOS

Source Code
•
NPM Package

The API destination allows you to send events to any HTTP endpoint with
customizable data transformation and transport methods.

walkerOS follows a source → collector → destination architecture. This API
destination receives processed events from the walkerOS collector and sends them
to your custom API endpoint, enabling integration with internal analytics
systems, data warehouses, or custom business logic that requires real-time event
data.

Installation

``sh
npm install @walkeros/web-destination-api
`

Configuration

| Name | Type | Description | Required | Example |
| ----------- | ------------------------------ | ------------------------------------------------ | -------- | ------------------------------------------------------------------------- |
| url | string | The HTTP endpoint URL to send events to | Yes | 'https://api.example.com/events' |
| headers | Record | Additional HTTP headers to include with requests | No | { 'Authorization': 'Bearer token', 'Content-Type': 'application/json' } |
| method | string | HTTP method for the request | No | 'POST' |
| transform | function | Function to transform event data before sending | No | (data, config, mapping) => JSON.stringify(data) |
| transport | 'fetch' \| 'xhr' \| 'beacon' | Transport method for sending requests | No | 'fetch' |

Quick Start

Configure in your Flow JSON:

`json
{
"version": 1,
"flows": {
"default": {
"web": {},
"destinations": {
"api": {
"package": "@walkeros/web-destination-api",
"config": {
"settings": {
"url": "https://api.example.com/events",
"method": "POST",
"headers": { "Authorization": "Bearer your-token" }
}
}
}
}
}
}
}
`

Or programmatically:

`typescript
import { startFlow } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { elb } = await startFlow({
destinations: [
{
destination: destinationAPI,
config: {
settings: {
url: 'https://api.example.com/events',
method: 'POST',
headers: { Authorization: 'Bearer your-token' },
},
},
},
],
});
`

Usage

$3

`typescript
import { startFlow } from '@walkeros/collector';
import { destinationAPI } from '@walkeros/web-destination-api';

const { elb } = await startFlow({
destinations: [
{
destination: destinationAPI,
config: {
settings: {
url: 'https://api.example.com/events',
transport: 'fetch',
transform: (event, config, mapping) => {
return JSON.stringify({
timestamp: Date.now(),
event_name: ${event.entity}_${event.action},
properties: event.data,
context: event.context,
});
},
},
},
},
],
});
`

Examples

$3

`json
{
"destinations": {
"analytics": {
"package": "@walkeros/web-destination-api",
"config": {
"settings": {
"url": "https://analytics.example.com/track",
"method": "POST",
"headers": {
"Content-Type": "application/json",
"X-API-Key": "your-api-key"
}
}
}
}
}
}
`

$3

For critical events that need to be sent even when the page is unloading:

`json
{
"destinations": {
"critical": {
"package": "@walkeros/web-destination-api",
"config": {
"settings": {
"url": "https://api.example.com/critical-events",
"transport": "beacon"
}
}
}
}
}
`

$3

Use mapping rules to control which events are sent:

`json
{
"destinations": {
"api": {
"package": "@walkeros/web-destination-api",
"config": {
"settings": { "url": "https://api.example.com/events" },
"mapping": {
"entity": {
"action": { "data": "data" }
}
}
}
}
}
}
``

Transport Methods

- fetch (default): Modern, promise-based HTTP requests
- xhr: Traditional XMLHttpRequest for older browser compatibility
- beacon: Uses Navigator.sendBeacon() for reliable data transmission during
page unload

Type Definitions

See src/types/ for TypeScript interfaces.

Related

- Website Documentation
- Destination Interface

Contribute

Feel free to contribute by submitting an
issue, starting a
discussion, or getting in
contact.

License

This project is licensed under the MIT License.