Track an Event
Track what users are doing in your app. Used for usage metering, billing, and analytics.
typescript
// Non-blocking — returns void immediately
// The event is queued and sent in the background
settle.events.track({
userId: 'user_123',
eventType: 'AI_QUERY',
quantity: 1, // Optional — defaults to 1
metadata: { // Optional — attach any context
model: 'gpt-4',
tokens: 1240,
},
})track() is synchronous and non-blocking.** It never awaits a network call. Events are pushed to an internal buffer and sent to the API in batches automatically. This means it will never slow down your response time.
**Why is
track() not awaited, but wallet.debit() is? - events.track() (Usage Telemetry)**: Operates on a background in-memory queue and processes at 0ms user-latency. It returns void instantly. - **wallet.debit() (Credit Transactions)**: Makes a blocking atomic database withdrawal and can throw InsufficientCreditsError. It MUST be awaited to guarantee transaction safety before exposing paid features.Never do this: ``
typescript // ❌ Wrong — track() returns void, not a Promise await settle.events.track({ userId, eventType: 'AI_QUERY' }) Always do this:
typescript
// ✅ Correct — fire and continue
settle.events.track({ userId, eventType: 'AI_QUERY' })Naming your events — use SCREAMING_SNAKE_CASE
| Good | Bad |
|---|---|
AI_QUERY | aiQuery |
PDF_EXPORT | pdf-export |
API_CALL | event1 |
VIDEO_MINUTE | userDidSomething |
💎 100% TypeScript Type-Safety
While the SDK accepts any string as an eventType to remain completely flexible, you can strictly enforce autocomplete across your entire app by wrapping it in a typesafe map:
typescript
// 1. Define your immutable application events
export const APP_EVENTS = {
AI_QUERY: 'AI_QUERY',
IMAGE_GEN: 'IMAGE_GEN',
PDF_EXPORT: 'PDF_EXPORT',
} as const;
export type AppEvent = typeof APP_EVENTS[keyof typeof APP_EVENTS];
// 2. Create a lightweight typesafe wrapper
export function trackAppEvent(userId: string, type: AppEvent) {
settle.events.track({ userId, eventType: type });
}
// 3. Now get IDE Autocomplete & Compiler safety!
trackAppEvent(userId, APP_EVENTS.AI_QUERY);Force-flush the buffer immediately
typescript
// Use this during graceful shutdown
await settle.events.flush()Check how many events are waiting
typescript
console.log(settle.events.pendingCount) // e.g. 12