@trig.email/ingest-sdk

TypeScript SDK for the VanEmail event ingestion API.

Installation

bun add @trig.email/ingest-sdk

Usage

Initialize the client

import { IngestClient } from '@trig.email/ingest-sdk';

const client = new IngestClient({
  apiKey: 'vk_your_api_key_here',
  baseUrl: 'https://ingest.yourdomain.com' // optional, defaults to http://localhost:3001
});

Track events

Track a single event:

const response = await client.track({
  eventType: 'purchase',
  email: '[email protected]',
  properties: {
    amount: 99.99,
    product: 'Premium Plan'
  },
  occurredAt: new Date().toISOString(), // optional
  externalId: 'order_123' // optional, for deduplication
});

console.log(response);
// {
//   success: true,
//   eventId: '...',
//   deduplicated: false,
//   flowsTriggered: 2
// }

Batch track events

Track multiple events in a single request (up to 1000):

const response = await client.batch({
  events: [
    {
      eventType: 'page_view',
      email: '[email protected]',
      properties: { page: '/pricing' }
    },
    {
      eventType: 'button_click',
      email: '[email protected]',
      properties: { button: 'Sign Up' }
    }
  ]
});

console.log(response);
// {
//   success: true,
//   processed: 2,
//   deduplicated: 0,
//   total: 2
// }

Identify profiles

Create or update a user profile:

const response = await client.identify({
  email: '[email protected]',
  externalId: 'user_123', // optional
  traits: {
    name: 'John Doe',
    plan: 'premium',
    signupDate: '2024-01-15'
  }
});

console.log(response);
// {
//   success: true,
//   profileId: '...'
// }

Queued tracking

For high-volume event tracking, use trackWithQueue() to buffer events and send them in batches. Events are automatically flushed when either:

• The queue reaches 100 events (configurable via queueMaxSize)
• 1 minute has passed since the first queued event (configurable via queueFlushIntervalMs)

const client = new IngestClient({
  apiKey: 'vk_your_api_key_here',
  queueMaxSize: 100,
  queueFlushIntervalMs: 60000
});

client.trackWithQueue({
  eventType: 'page_view',
  email: '[email protected]',
  properties: { page: '/home' }
});

client.trackWithQueue({
  eventType: 'button_click',
  email: '[email protected]',
  properties: { button: 'Sign Up' }
});

console.log(client.getQueueSize());

const result = await client.flush();
console.log(result);
// {
//   success: true,
//   processed: 2,
//   deduplicated: 0,
//   total: 2
// }

Health check

Check if the ingest server is healthy:

const health = await client.health();
console.log(health);
// {
//   status: 'ok',
//   timestamp: '2024-01-15T10:30:00.000Z',
//   service: 'ingest'
// }

Error Handling

The SDK throws IngestError for all errors:

import { IngestClient, IngestError } from '@trig.email/ingest-sdk';

try {
  await client.track({
    eventType: 'purchase',
    email: 'invalid-email' // will fail validation
  });
} catch (error) {
  if (error instanceof IngestError) {
    console.error('Ingest error:', error.message);
    console.error('Status code:', error.statusCode);
    console.error('Response:', error.response);
  }
}

TypeScript Support

The SDK is written in TypeScript and provides full type safety:

import type {
  TrackEvent,
  TrackResponse,
  BatchEvents,
  BatchResponse,
  IdentifyProfile,
  IdentifyResponse,
  HealthResponse
} from '@trig.email/ingest-sdk';

API Reference

IngestClient

Constructor

new IngestClient(config: IngestClientConfig)

• config.apiKey (required): Your API key with vk_ prefix
• config.baseUrl (optional): Base URL of the ingest server (default: http://localhost:3001)
• config.queueMaxSize (optional): Maximum events to buffer before auto-flush (default: 100)
• config.queueFlushIntervalMs (optional): Time in ms before auto-flush (default: 60000)

Methods

• track(event: TrackEvent): Promise<TrackResponse> - Track a single event immediately
• trackWithQueue(event: TrackEvent): void - Add event to queue for batched sending
• flush(): Promise<BatchResponse | null> - Manually flush queued events
• getQueueSize(): number - Get current number of queued events
• batch(batch: BatchEvents): Promise<BatchResponse> - Track multiple events
• identify(profile: IdentifyProfile): Promise<IdentifyResponse> - Identify a profile
• health(): Promise<HealthResponse> - Check server health