@alertsamurai/sdk

TypeScript SDK for AlertSamurai metrics and alerting.

Installation

npm install @alertsamurai/sdk-js

Quick Start

import { AlertSamuraiClient } from "@alertsamurai/sdk-js";

const client = new AlertSamuraiClient({
  dsn: "your-project-dsn",
});

// Send a metric
await client.sendMetric({
  metricType: "photo_upload_speed",
  value: 2.5,
  unit: "MB/s",
  environment: "production",
});

// Send an alert
await client.sendAlert({
  message: "Database connection failed",
  priority: "critical",
  environment: "production",
});

// Convenience methods
await client.critical("Server down!");
await client.error("Failed to process payment");
await client.warning("High memory usage");
await client.info("User signed in");
await client.debug("Cache miss for key: xyz");

Configuration

const client = new AlertSamuraiClient({
  dsn: "your-dsn", // Required - found in project settings
  baseUrl: "https://...", // Optional, default: api.alertsamurai.com
  timeout: 30000, // Optional, default: 30s
  retries: 3, // Optional, default: 3
});

Metrics API

Send custom metrics for tracking and threshold-based alerting.

await client.sendMetric({
  metricType: "photo_upload_speed", // Required - metric name
  value: 2.5, // Required - numeric value
  unit: "MB/s", // Optional - unit of measurement
  environment: "production", // Optional - environment name
  metadata: {
    // Optional - additional context
    userId: "123",
    endpoint: "/api/upload",
  },
  timestamp: new Date(), // Optional - defaults to now
});

Threshold-Based Alerts

Configure metric alerts in your AlertSamurai dashboard. When a metric exceeds a threshold (e.g., photo_upload_speed < 1 MB/s), you'll receive a notification via Telegram.

Alerts API

Send application alerts with priority levels.

await client.sendAlert({
  message: "Database connection failed", // Required - alert message
  priority: "critical", // Required - critical|error|warning|info|debug
  environment: "production", // Optional - environment name
  data: {
    // Optional - additional context
    errorCode: "ECONNREFUSED",
    retryCount: 3,
  },
});

Convenience Methods

// These methods send alerts with the specified priority
await client.critical("Server down!"); // priority: "critical"
await client.error("Failed to process payment"); // priority: "error"
await client.warning("High memory usage"); // priority: "warning"
await client.info("User signed in"); // priority: "info"
await client.debug("Cache miss"); // priority: "debug"

// With additional data
await client.error("Payment failed", {
  orderId: "12345",
  errorCode: "INSUFFICIENT_FUNDS",
});

Error Handling

The SDK provides typed errors for different failure scenarios:

import {
  AlertSamuraiClient,
  AlertSamuraiError,
  AuthenticationError,
  ValidationError,
  NetworkError,
} from "@alertsamurai/sdk";

try {
  await client.sendMetric({ metricType: "test", value: 123 });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or missing DSN (401)
    console.error("Authentication failed:", error.message);
  } else if (error instanceof ValidationError) {
    // Invalid request data (400)
    console.error("Validation failed:", error.message);
  } else if (error instanceof NetworkError) {
    // Network failure, timeout, etc.
    console.error("Network error:", error.message);
  } else if (error instanceof AlertSamuraiError) {
    // Other API errors
    console.error("API error:", error.message, error.statusCode);
  }
}

Retry Logic

The SDK automatically retries failed requests with exponential backoff:

• Default: 3 retries
• Backoff: 1s, 2s, 4s (capped at 10s)
• Does not retry on authentication (401) or validation (400) errors

Configure retries:

const client = new AlertSamuraiClient({
  dsn: "your-dsn",
  retries: 5, // More retries
  timeout: 60000, // Longer timeout
});

TypeScript Support

The SDK is written in TypeScript and includes full type definitions:

import type {
  AlertSamuraiConfig,
  SendMetricOptions,
  SendMetricResponse,
  SendAlertOptions,
  SendAlertResponse,
  AlertPriority,
} from "@alertsamurai/sdk-js";

const options: SendMetricOptions = {
  metricType: "api_latency",
  value: 150,
  unit: "ms",
};

const priority: AlertPriority = "warning";

Requirements

• Node.js 18+ (for native fetch support) or browser environment
• Or any environment with a global fetch implementation

License

MIT