Track Usage Events
Track usage events with sdkCallEventConsumer
Overview
The sdkCallEventConsumer method is the primary way to track billable usage events in your application. It records usage via gRPC and registers events with the Scrawn backend for billing tracking.
This is a general-purpose event consumer that can be used under abstractions to track any kind of usage. More specialized event consumers (compute-based, token stream-based, resource-based, etc.) will be coming soon.
For now, you can use this method under your own abstractions to track different types of usage events.
Basic Usage
import { Scrawn } from '@scrawn/core';
const scrawn = new Scrawn({
apiKey: process.env.SCRAWN_KEY as `scrn_${string}`,
baseURL: process.env.SCRAWN_BASE_URL || 'http://localhost:8069',
});
await scrawn.sdkCallEventConsumer({
userId: 'user-123',
debitAmount: 100,
});In simple terms: Charge user user-123 an amount of 100.
Parameters
userId (required)
- Type:
string - Description: The unique identifier of the user consuming the event
- Validation: Must be a non-empty string
debitAmount (required)
- Type:
number - Description: Amount to debit from user's balance. Use the same currency unit configured in your LemonSqueezy dashboard (dollars, cents, etc.)
- Validation: Must be a positive number
- Example:
100,10.50,1000
Response
The method returns a promise that resolves to void when the event is successfully tracked. Errors are thrown if validation fails or the gRPC call fails.
Examples
These examples show how sdkCallEventConsumer can be used under abstractions for different use cases.
Track API Call Usage
// Track a single API call
await scrawn.sdkCallEventConsumer({
userId: 'user-123',
debitAmount: 0.10,
});Track Token Usage (AI/LLM)
// Create an abstraction for token-based billing
async function trackTokenUsage(userId: string, tokensUsed: number) {
const costPerToken = 0.002;
const totalCost = tokensUsed * costPerToken;
await scrawn.sdkCallEventConsumer({
userId,
debitAmount: totalCost,
});
}
// Use the abstraction
await trackTokenUsage('user-123', 1500);Track Storage Usage
// Create an abstraction for storage-based billing
async function trackStorageUsage(userId: string, fileSizeMB: number) {
const costPerMB = 0.05;
const totalCost = fileSizeMB * costPerMB;
await scrawn.sdkCallEventConsumer({
userId,
debitAmount: totalCost,
});
}
// Use the abstraction
await trackStorageUsage('user-123', 50);Error Handling
try {
await scrawn.sdkCallEventConsumer({
userId: 'user-123',
debitAmount: 100,
});
console.log('Usage tracked successfully');
} catch (error) {
console.error('Error tracking usage:', error);
}Best Practices
Track Events After Service Delivery
Track usage as soon as the service is consumed:
const result = await processImage(imageData);
if (result.success) {
await scrawn.sdkCallEventConsumer({
userId: user.id,
debitAmount: calculateCost(result),
});
}