Warden Client

A TypeScript library for sending events to Warden data warehouse API.

Features

- TypeScript typings for the event model.
- Simple function to POST events to the API using Axios.
- Collects events in memory and sends them in batches.
- Sends when batch size or interval is reached.
- Flushes remaining events on page unload using sendBeacon (if available).
- Retries sending if the network request fails.

Building

``
npm run build
`

The output will be in the dist/ directory.

Authentication

The Warden API supports Bearer token authentication. If authentication is enabled on the server, you must provide a valid Bearer token with your requests.

$3

Authentication is configured on the server side via the API_BEARER_TOKENS environment variable. If this is not set, authentication is disabled and no token is required.

$3

When authentication is enabled, include the Bearer token in your API calls:

`ts
// For EventBatcher
const batcher = new EventBatcher({
batchEventsUrl: "http://localhost:8888/v1/batch_events", // Full endpoint URL
batchSize: 5,
batchIntervalMs: 5000,
headers: {
'Authorization': 'Bearer your-token-here'
}
});

// For direct API calls
const headers = {
'Authorization': 'Bearer your-token-here',
'Content-Type': 'application/json'
};
`

$3

If authentication is enabled and you provide an invalid or missing token, the API will return a 401 Unauthorized status with an error message:

`json
{"error": "missing authorization header"}
{"error": "invalid authorization header format"}
{"error": "invalid token"}
`

Make sure to handle these errors appropriately in your application.

Usage

$3

For most web apps, you can use the EventBatcher class to automatically collect and
send events in batches based on size or time interval:

`ts
import { EventBatcher, Event } from "warden-client";

const batcher = new EventBatcher({
batchEventsUrl: "http://localhost:8888/v1/batch_events", // Full endpoint URL
batchSize: 5,
batchIntervalMs: 5000,
headers: {
'Authorization': 'Bearer your-token-here'
}
});

// Log events as users interact with your app
batcher.log(gameStartedEvent);
batcher.log(agentCallEvent);
batcher.log(swapEvent);
`

The batcher will send events automatically based on the configured size/timer.
To clean up (e.g., on SPA route change or app shutdown), call batcher.stop():

`ts
batcher.stop();
`

$3

`ts
import { postEventsBatch, Event } from "warden-client";

const apiUrl = ""; // http:///v1/batch_events

const events: Event[] = [gameStartedEvent, agentCallEvent, swapEvent];

// Optional: include headers if authentication is enabled
const options = {
headers: {
'Authorization': 'Bearer your-token-here'
}
};

postEventsBatch(apiUrl, events, options)
.then(response => {
console.log("Batch queued:", response);
})
.catch(err => {
console.error("Failed to send batch:", err);
});
`

$3

`ts
import { postEvent, Event } from "warden-client";

const apiUrl = ""; // http:///v1/events

// Game started event
const gameStartedEvent: Event = {
user_id: "user123",
session_id: "sess456",
event_type: "game_started",
timestamp: new Date().toISOString(),
payload: {
game_name: "Snake"
}
};

// Optional: include headers if authentication is enabled
const options = {
headers: {
'Authorization': 'Bearer your-token-here'
}
};

// Send any event
postEvent(apiUrl, gameStartedEvent, options)
.then(response => {
console.log("Event queued:", response);
})
.catch(err => {
console.error("Failed to send event:", err);
});
`

$3

You can use any structure for payload to represent any event type. Remember
that the event type is a string so try to be consistent with it.

Here are some payload examples:

`ts
// Swap action event
const swapEvent: Event = {
user_id: "user123",
session_id: "sess456",
event_type: "swap",
timestamp: new Date().toISOString(),
payload: {
from: "BTC",
to: "ETH",
amount: 0.3,
usd_value: 1234
}
};

// Agent call event
const agentCallEvent: Event = {
user_id: "user123",
session_id: "sess456",
event_type: "agent_call",
timestamp: new Date().toISOString(),
payload: {
agent_id: "messariAgent",
prompt_tokens: 234,
completion_tokens: 123,
total_tokens: 357,
}
};

// Game started event
const gameStartedEvent: Event = {
user_id: "user123",
session_id: "sess456",
event_type: "game_started",
timestamp: new Date().toISOString(),
payload: {
game_name: "Snake"
}
};
`

A full demo of the client can be found in the demo` directory.

License

Apache 2.0