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.

Configuration

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.

Using Bearer Tokens

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

// 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'
};

Authentication Errors

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

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

Make sure to handle these errors appropriately in your application.

Usage

Recommended: automatic batching with EventBatcher

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

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():

batcher.stop();

Batch events without automatic batching

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

const apiUrl = "<API endpoint>"; // http://<API-URL>/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);
  });

Single event

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

const apiUrl = "<API endpoint>"; // http://<API-URL>/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);
  });

Examples of payloads

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:

// 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