A TypeScript library for sending events to Warden data warehouse API.
npm install @wardenprotocol/warden-clientA TypeScript library for sending events to Warden data warehouse API.
sendBeacon (if available).```
npm run build
The output will be in the dist/ directory.
The Warden API supports Bearer token authentication. If authentication is enabled on the server, you must provide a valid Bearer token with your requests.
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.
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'
};
`
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.
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();
`ts
import { postEventsBatch, Event } from "warden-client";
const apiUrl = "
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);
});
`
`ts
import { postEvent, Event } from "warden-client";
const apiUrl = "
// 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);
});
`
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.