> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emitkit.com/llms.txt
> Use this file to discover all available pages before exploring further.
# TypeScript SDK
> Official TypeScript/JavaScript SDK for EmitKit
## Overview
The EmitKit TypeScript/JavaScript SDK provides a type-safe, developer-friendly interface for monitoring critical product moments and sending real-time alerts.
## Features
Full TypeScript support with auto-generated types
No external runtime dependencies, minimal bundle size
Type-safe error classes with detailed information
Automatic rate limit tracking and handling
Built-in support for safe retries
Optimized bundle size with ES modules
## Installation
```bash npm theme={null}
npm install @emitkit/js
```
```bash pnpm theme={null}
pnpm add @emitkit/js
```
```bash yarn theme={null}
yarn add @emitkit/js
```
## Basic Usage
```typescript theme={null}
import { EmitKit } from '@emitkit/js';
const client = new EmitKit('emitkit_xxxxxxxxxxxxxxxxxxxxx');
// Create an event
const result = await client.events.create({
channelName: 'payments',
title: 'Payment Received',
metadata: { amount: 99.99 }
});
console.log('Event ID:', result.data.id);
console.log('Rate limit remaining:', result.rateLimit.remaining);
```
## Configuration
### Basic Configuration
```typescript theme={null}
const client = new EmitKit('your_api_key');
```
### Advanced Configuration
```typescript theme={null}
const client = new EmitKit('your_api_key', {
// Custom base URL (for self-hosted instances)
baseUrl: 'https://api.your-domain.com',
// Request timeout in milliseconds (default: 30000)
timeout: 60000,
// Custom fetch implementation
fetch: customFetch
});
```
## Methods
### events.create()
Create a new event and optionally send notifications.
**Parameters:**
* `channelName` (string, required): Channel name (auto-creates if doesn't exist)
* `title` (string, required): Event title
* `description` (string, optional): Event description
* `icon` (string, optional): Single emoji icon
* `tags` (string\[], optional): Array of tags
* `metadata` (object, optional): Custom JSON metadata
* `userId` (string | null, optional): User identifier
* `notify` (boolean, optional): Send push notification to connected devices (default: true)
* `source` (string, optional): Source identifier
**Options:**
* `idempotencyKey` (string): For safe retries
* `timeout` (number): Request timeout override
* `headers` (object): Additional headers
**Returns:** `Promise`
```typescript theme={null}
const result = await client.events.create({
channelName: 'payments',
title: 'Payment Received',
description: 'User upgraded to Pro plan',
icon: '💰',
tags: ['payment', 'upgrade'],
metadata: {
amount: 99.99,
currency: 'USD',
plan: 'pro'
},
userId: 'user_123',
notify: true
});
```
### identify()
Create or update a user identity with properties and aliases.
**Parameters:**
* `user_id` (string, required): Your internal user ID
* `properties` (object, optional): Custom user properties
* `aliases` (string\[], optional): Alternative identifiers
**Returns:** `Promise>`
```typescript theme={null}
await client.identify({
user_id: 'user_123',
properties: {
email: 'john@example.com',
name: 'John Doe',
plan: 'pro'
},
aliases: ['john@example.com', 'johndoe']
});
```
## Response Types
### EmitKitResponse
```typescript theme={null}
interface EmitKitResponse {
data: T; // Response data
rateLimit: RateLimitInfo; // Rate limit info
requestId: string; // Request ID for debugging
wasReplayed: boolean; // Idempotent replay flag
}
```
### RateLimitInfo
```typescript theme={null}
interface RateLimitInfo {
limit: number; // Max requests allowed
remaining: number; // Remaining requests
reset: number; // Unix timestamp when limit resets
resetIn: number; // Milliseconds until reset
}
```
## Error Handling
The SDK provides type-safe error classes for different error scenarios:
```typescript theme={null}
import {
EmitKit,
EmitKitError,
RateLimitError,
ValidationError
} from '@emitkit/js';
try {
await client.events.create({...});
} catch (error) {
if (error instanceof RateLimitError) {
console.log('Rate limit exceeded!');
console.log(`Retry in ${error.rateLimit.resetIn}ms`);
} else if (error instanceof ValidationError) {
console.log('Validation failed:');
error.validationErrors.forEach(err => {
console.log(`- ${err.path.join('.')}: ${err.message}`);
});
} else if (error instanceof EmitKitError) {
console.log(`API Error ${error.statusCode}:`, error.message);
console.log('Request ID:', error.requestId);
}
}
```
See [Error Handling](/sdk/error-handling) for detailed documentation.
## Rate Limit Tracking
Access rate limit information from responses:
```typescript theme={null}
const result = await client.events.create({...});
console.log(result.rateLimit);
// {
// limit: 100,
// remaining: 95,
// reset: 1733270400,
// resetIn: 45000
// }
// Access last known rate limit
console.log(client.rateLimit);
```
## Next Steps
Learn about event creation and metadata
Identify users and manage aliases
Handle errors and rate limits
Idempotency, retries, and more