MetricsFirst TypeScript/JavaScript SDK

Official TypeScript/JavaScript SDK for MetricsFirst - Analytics for Telegram bots.

Note: Commands and interactions are tracked automatically when you add your bot to MetricsFirst. This SDK is for tracking custom events like services, purchases, and errors.

Installation

npm install @metricsfirst/sdk
# or
pnpm add @metricsfirst/sdk
# or
yarn add @metricsfirst/sdk

Features

• Fire-and-forget: All tracking calls are non-blocking and don't add latency
• Automatic batching: Events are queued and sent in batches
• Error resilience: Errors are logged, never thrown to your code
• Memory safe: Queue is limited to 1000 events to prevent memory issues

Quick Start

import { MetricsFirst } from '@metricsfirst/sdk';

const mf = new MetricsFirst({
  botId: 'your_bot_id',
  apiKey: 'your_api_key',
});

// Track a service (fire-and-forget, non-blocking)
mf.trackService({
  userId: 123456789,
  serviceName: 'image_generation',
  isFree: false,
  price: 10,
  currency: 'USD',
});

// Track a purchase
mf.trackPurchaseCompleted({
  userId: 123456789,
  purchaseId: 'purchase_123',
  price: 9.99,
  currency: 'USD',
  tariffName: 'Pro Plan',
});

// Shutdown when done (flushes remaining events)
await mf.shutdown();

Available Methods

| Method | Description | | ------------------------------ | ------------------------- | | trackService() | Track services provided | | trackError() | Track errors | | trackErrorFromException() | Track error from Error | | trackPurchaseInitiated() | Track purchase start | | trackPurchaseCompleted() | Track successful purchase | | trackPurchaseError() | Track failed purchase | | trackRecurringChargeSuccess()| Track subscription charge | | trackRecurringChargeFailed() | Track failed charge | | identify() | Identify user | | flush() | Manually flush events | | shutdown() | Shutdown and flush |

Configuration

const mf = new MetricsFirst({
  botId: 'your_bot_id',      // Required
  apiKey: 'your_api_key',    // Required
  apiUrl: 'https://api.metricsfirst.com',  // Custom API URL
  batchEvents: true,         // Batch events before sending
  batchSize: 10,             // Events per batch
  batchInterval: 5000,       // ms between flushes
  debug: false,              // Enable debug logging
  timeout: 10000,            // HTTP timeout in ms
});

License

MIT