@alertsamurai/sdk-js 0.0.1

package/README.md

@@ -0,0 +1,191 @@
+# @alertsamurai/sdk
+
+TypeScript SDK for AlertSamurai metrics and alerting.
+
+## Installation
+
+```bash
+npm install @alertsamurai/sdk
+```
+
+## Quick Start
+
+```typescript
+import { AlertSamuraiClient } from "@alertsamurai/sdk";
+
+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
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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
+
+```typescript
+// 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:
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+import type {
+  AlertSamuraiConfig,
+  SendMetricOptions,
+  SendMetricResponse,
+  SendAlertOptions,
+  SendAlertResponse,
+  AlertPriority,
+} from "@alertsamurai/sdk";
+
+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

package/dist/index.d.mts

@@ -0,0 +1,194 @@
+/**
+ * Client configuration options
+ */
+interface AlertSamuraiConfig {
+    /** Project DSN (required) - found in your project settings */
+    dsn: string;
+    /** API base URL (optional) - defaults to https://api.alertsamurai.com */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (optional) - defaults to 30000 */
+    timeout?: number;
+    /** Number of retries on network failure (optional) - defaults to 3 */
+    retries?: number;
+}
+/**
+ * Options for sending a metric
+ */
+interface SendMetricOptions {
+    /** Metric type/name (e.g., "photo_upload_speed", "api_latency") */
+    metricType: string;
+    /** Numeric value of the metric */
+    value: number;
+    /** Unit of measurement (e.g., "MB/s", "ms") */
+    unit?: string;
+    /** Environment name (e.g., "production", "staging") */
+    environment?: string;
+    /** Additional metadata as key-value pairs */
+    metadata?: Record<string, unknown>;
+    /** Timestamp - accepts Date, milliseconds, or ISO string. Defaults to now */
+    timestamp?: Date | number | string;
+}
+/**
+ * Response from sending a metric
+ */
+interface SendMetricResponse {
+    /** ID of the created metric record */
+    id: string;
+    /** Whether the metric was successfully processed */
+    success: boolean;
+    /** Whether any threshold-based alerts were triggered */
+    alertTriggered?: boolean;
+}
+/**
+ * Alert priority levels
+ */
+type AlertPriority = "critical" | "error" | "warning" | "info" | "debug";
+/**
+ * Options for sending an alert
+ */
+interface SendAlertOptions {
+    /** Alert message/description */
+    message: string;
+    /** Priority level of the alert */
+    priority: AlertPriority;
+    /** Environment name (e.g., "production", "staging") */
+    environment?: string;
+    /** Additional context data as key-value pairs */
+    data?: Record<string, unknown>;
+}
+/**
+ * Response from sending an alert
+ */
+interface SendAlertResponse {
+    /** ID of the created alert record */
+    id: string;
+    /** Whether the alert was successfully processed */
+    success: boolean;
+}
+
+/**
+ * AlertSamurai SDK client for sending metrics and alerts
+ *
+ * @example
+ * ```typescript
+ * const client = new AlertSamuraiClient({
+ *   dsn: "your-project-dsn",
+ * });
+ *
+ * // Send a metric
+ * await client.sendMetric({
+ *   metricType: "photo_upload_speed",
+ *   value: 2.5,
+ *   unit: "MB/s",
+ * });
+ *
+ * // Send an alert
+ * await client.critical("Database connection failed");
+ * ```
+ */
+declare class AlertSamuraiClient {
+    private dsn;
+    private baseUrl;
+    private timeout;
+    private retries;
+    constructor(config: AlertSamuraiConfig);
+    /**
+     * Send a custom metric for tracking and threshold-based alerting
+     *
+     * @param options - Metric options
+     * @returns Response with metric ID and alert trigger status
+     *
+     * @example
+     * ```typescript
+     * await client.sendMetric({
+     *   metricType: "photo_upload_speed",
+     *   value: 2.5,
+     *   unit: "MB/s",
+     *   environment: "production",
+     *   metadata: { userId: "123" },
+     * });
+     * ```
+     */
+    sendMetric(options: SendMetricOptions): Promise<SendMetricResponse>;
+    /**
+     * Send an application alert with priority level
+     *
+     * @param options - Alert options
+     * @returns Response with alert ID
+     *
+     * @example
+     * ```typescript
+     * await client.sendAlert({
+     *   message: "Database connection failed",
+     *   priority: "critical",
+     *   environment: "production",
+     *   data: { errorCode: "ECONNREFUSED" },
+     * });
+     * ```
+     */
+    sendAlert(options: SendAlertOptions): Promise<SendAlertResponse>;
+    /**
+     * Send a critical priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    critical(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    /**
+     * Send an error priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    error(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    /**
+     * Send a warning priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    warning(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    /**
+     * Send an info priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    info(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    /**
+     * Send a debug priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    debug(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    private request;
+    private doRequest;
+    private validateMetric;
+    private validateAlert;
+    private normalizeTimestamp;
+}
+
+/**
+ * Base error class for all AlertSamurai SDK errors
+ */
+declare class AlertSamuraiError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+/**
+ * Thrown when authentication fails (invalid or missing DSN)
+ */
+declare class AuthenticationError extends AlertSamuraiError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when request validation fails
+ */
+declare class ValidationError extends AlertSamuraiError {
+    constructor(message: string);
+}
+/**
+ * Thrown when network request fails (timeout, connection error, etc.)
+ */
+declare class NetworkError extends AlertSamuraiError {
+    constructor(message?: string);
+}
+
+export { type AlertPriority, AlertSamuraiClient, type AlertSamuraiConfig, AlertSamuraiError, AuthenticationError, NetworkError, type SendAlertOptions, type SendAlertResponse, type SendMetricOptions, type SendMetricResponse, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Client configuration options
+ */
+interface AlertSamuraiConfig {
+    /** Project DSN (required) - found in your project settings */
+    dsn: string;
+    /** API base URL (optional) - defaults to https://api.alertsamurai.com */
+    baseUrl?: string;
+    /** Request timeout in milliseconds (optional) - defaults to 30000 */
+    timeout?: number;
+    /** Number of retries on network failure (optional) - defaults to 3 */
+    retries?: number;
+}
+/**
+ * Options for sending a metric
+ */
+interface SendMetricOptions {
+    /** Metric type/name (e.g., "photo_upload_speed", "api_latency") */
+    metricType: string;
+    /** Numeric value of the metric */
+    value: number;
+    /** Unit of measurement (e.g., "MB/s", "ms") */
+    unit?: string;
+    /** Environment name (e.g., "production", "staging") */
+    environment?: string;
+    /** Additional metadata as key-value pairs */
+    metadata?: Record<string, unknown>;
+    /** Timestamp - accepts Date, milliseconds, or ISO string. Defaults to now */
+    timestamp?: Date | number | string;
+}
+/**
+ * Response from sending a metric
+ */
+interface SendMetricResponse {
+    /** ID of the created metric record */
+    id: string;
+    /** Whether the metric was successfully processed */
+    success: boolean;
+    /** Whether any threshold-based alerts were triggered */
+    alertTriggered?: boolean;
+}
+/**
+ * Alert priority levels
+ */
+type AlertPriority = "critical" | "error" | "warning" | "info" | "debug";
+/**
+ * Options for sending an alert
+ */
+interface SendAlertOptions {
+    /** Alert message/description */
+    message: string;
+    /** Priority level of the alert */
+    priority: AlertPriority;
+    /** Environment name (e.g., "production", "staging") */
+    environment?: string;
+    /** Additional context data as key-value pairs */
+    data?: Record<string, unknown>;
+}
+/**
+ * Response from sending an alert
+ */
+interface SendAlertResponse {
+    /** ID of the created alert record */
+    id: string;
+    /** Whether the alert was successfully processed */
+    success: boolean;
+}
+
+/**
+ * AlertSamurai SDK client for sending metrics and alerts
+ *
+ * @example
+ * ```typescript
+ * const client = new AlertSamuraiClient({
+ *   dsn: "your-project-dsn",
+ * });
+ *
+ * // Send a metric
+ * await client.sendMetric({
+ *   metricType: "photo_upload_speed",
+ *   value: 2.5,
+ *   unit: "MB/s",
+ * });
+ *
+ * // Send an alert
+ * await client.critical("Database connection failed");
+ * ```
+ */
+declare class AlertSamuraiClient {
+    private dsn;
+    private baseUrl;
+    private timeout;
+    private retries;
+    constructor(config: AlertSamuraiConfig);
+    /**
+     * Send a custom metric for tracking and threshold-based alerting
+     *
+     * @param options - Metric options
+     * @returns Response with metric ID and alert trigger status
+     *
+     * @example
+     * ```typescript
+     * await client.sendMetric({
+     *   metricType: "photo_upload_speed",
+     *   value: 2.5,
+     *   unit: "MB/s",
+     *   environment: "production",
+     *   metadata: { userId: "123" },
+     * });
+     * ```
+     */
+    sendMetric(options: SendMetricOptions): Promise<SendMetricResponse>;
+    /**
+     * Send an application alert with priority level
+     *
+     * @param options - Alert options
+     * @returns Response with alert ID
+     *
+     * @example
+     * ```typescript
+     * await client.sendAlert({
+     *   message: "Database connection failed",
+     *   priority: "critical",
+     *   environment: "production",
+     *   data: { errorCode: "ECONNREFUSED" },
+     * });
+     * ```
+     */
+    sendAlert(options: SendAlertOptions): Promise<SendAlertResponse>;
+    /**
+     * Send a critical priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    critical(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    /**
+     * Send an error priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    error(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    /**
+     * Send a warning priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    warning(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    /**
+     * Send an info priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    info(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    /**
+     * Send a debug priority alert
+     * @param message - Alert message
+     * @param data - Optional additional context data
+     */
+    debug(message: string, data?: Record<string, unknown>): Promise<SendAlertResponse>;
+    private request;
+    private doRequest;
+    private validateMetric;
+    private validateAlert;
+    private normalizeTimestamp;
+}
+
+/**
+ * Base error class for all AlertSamurai SDK errors
+ */
+declare class AlertSamuraiError extends Error {
+    statusCode?: number | undefined;
+    response?: unknown | undefined;
+    constructor(message: string, statusCode?: number | undefined, response?: unknown | undefined);
+}
+/**
+ * Thrown when authentication fails (invalid or missing DSN)
+ */
+declare class AuthenticationError extends AlertSamuraiError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when request validation fails
+ */
+declare class ValidationError extends AlertSamuraiError {
+    constructor(message: string);
+}
+/**
+ * Thrown when network request fails (timeout, connection error, etc.)
+ */
+declare class NetworkError extends AlertSamuraiError {
+    constructor(message?: string);
+}
+
+export { type AlertPriority, AlertSamuraiClient, type AlertSamuraiConfig, AlertSamuraiError, AuthenticationError, NetworkError, type SendAlertOptions, type SendAlertResponse, type SendMetricOptions, type SendMetricResponse, ValidationError };

package/dist/index.js

@@ -0,0 +1,279 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AlertSamuraiClient: () => AlertSamuraiClient,
+  AlertSamuraiError: () => AlertSamuraiError,
+  AuthenticationError: () => AuthenticationError,
+  NetworkError: () => NetworkError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var AlertSamuraiError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "AlertSamuraiError";
+  }
+};
+var AuthenticationError = class extends AlertSamuraiError {
+  constructor(message = "Invalid or missing DSN") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends AlertSamuraiError {
+  constructor(message) {
+    super(message, 400);
+    this.name = "ValidationError";
+  }
+};
+var NetworkError = class extends AlertSamuraiError {
+  constructor(message = "Network request failed") {
+    super(message);
+    this.name = "NetworkError";
+  }
+};
+
+// src/utils/retry.ts
+async function withRetry(fn, options) {
+  let lastError;
+  for (let attempt = 0; attempt <= options.retries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (error instanceof Error && (error.name === "AuthenticationError" || error.name === "ValidationError")) {
+        throw error;
+      }
+      if (attempt < options.retries) {
+        const delay = Math.min(
+          options.baseDelay * Math.pow(2, attempt),
+          options.maxDelay
+        );
+        await sleep(delay);
+      }
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.alertsamurai.com";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RETRIES = 3;
+var AlertSamuraiClient = class {
+  constructor(config) {
+    if (!config.dsn) {
+      throw new ValidationError("DSN is required");
+    }
+    this.dsn = config.dsn;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.retries = config.retries ?? DEFAULT_RETRIES;
+  }
+  /**
+   * Send a custom metric for tracking and threshold-based alerting
+   *
+   * @param options - Metric options
+   * @returns Response with metric ID and alert trigger status
+   *
+   * @example
+   * ```typescript
+   * await client.sendMetric({
+   *   metricType: "photo_upload_speed",
+   *   value: 2.5,
+   *   unit: "MB/s",
+   *   environment: "production",
+   *   metadata: { userId: "123" },
+   * });
+   * ```
+   */
+  async sendMetric(options) {
+    this.validateMetric(options);
+    const body = {
+      metricType: options.metricType,
+      value: options.value,
+      unit: options.unit,
+      environment: options.environment,
+      metadata: options.metadata,
+      timestamp: this.normalizeTimestamp(options.timestamp)
+    };
+    return this.request("/api/metrics", body);
+  }
+  /**
+   * Send an application alert with priority level
+   *
+   * @param options - Alert options
+   * @returns Response with alert ID
+   *
+   * @example
+   * ```typescript
+   * await client.sendAlert({
+   *   message: "Database connection failed",
+   *   priority: "critical",
+   *   environment: "production",
+   *   data: { errorCode: "ECONNREFUSED" },
+   * });
+   * ```
+   */
+  async sendAlert(options) {
+    this.validateAlert(options);
+    return this.request("/api/alerts", options);
+  }
+  /**
+   * Send a critical priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async critical(message, data) {
+    return this.sendAlert({ message, priority: "critical", data });
+  }
+  /**
+   * Send an error priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async error(message, data) {
+    return this.sendAlert({ message, priority: "error", data });
+  }
+  /**
+   * Send a warning priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async warning(message, data) {
+    return this.sendAlert({ message, priority: "warning", data });
+  }
+  /**
+   * Send an info priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async info(message, data) {
+    return this.sendAlert({ message, priority: "info", data });
+  }
+  /**
+   * Send a debug priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async debug(message, data) {
+    return this.sendAlert({ message, priority: "debug", data });
+  }
+  async request(path, body) {
+    return withRetry(() => this.doRequest(path, body), {
+      retries: this.retries,
+      baseDelay: 1e3,
+      maxDelay: 1e4
+    });
+  }
+  async doRequest(path, body) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.dsn}`
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 401) {
+        throw new AuthenticationError();
+      }
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => ({}));
+        throw new AlertSamuraiError(
+          errorBody.message || `Request failed with status ${response.status}`,
+          response.status,
+          errorBody
+        );
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof AlertSamuraiError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError("Request timed out");
+      }
+      throw new NetworkError(
+        error instanceof Error ? error.message : "Unknown network error"
+      );
+    }
+  }
+  validateMetric(options) {
+    if (!options.metricType || typeof options.metricType !== "string") {
+      throw new ValidationError("metricType is required and must be a string");
+    }
+    if (options.metricType.length > 100) {
+      throw new ValidationError("metricType must be 100 characters or less");
+    }
+    if (typeof options.value !== "number" || isNaN(options.value)) {
+      throw new ValidationError("value is required and must be a number");
+    }
+    if (options.unit !== void 0 && typeof options.unit !== "string") {
+      throw new ValidationError("unit must be a string");
+    }
+    if (options.unit && options.unit.length > 50) {
+      throw new ValidationError("unit must be 50 characters or less");
+    }
+  }
+  validateAlert(options) {
+    if (!options.message || typeof options.message !== "string") {
+      throw new ValidationError("message is required and must be a string");
+    }
+    if (options.message.length > 4e3) {
+      throw new ValidationError("message must be 4000 characters or less");
+    }
+    const validPriorities = ["critical", "error", "warning", "info", "debug"];
+    if (!validPriorities.includes(options.priority)) {
+      throw new ValidationError(
+        `priority must be one of: ${validPriorities.join(", ")}`
+      );
+    }
+  }
+  normalizeTimestamp(timestamp) {
+    if (!timestamp) return void 0;
+    if (timestamp instanceof Date) return timestamp.toISOString();
+    if (typeof timestamp === "number") return new Date(timestamp).toISOString();
+    return timestamp;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AlertSamuraiClient,
+  AlertSamuraiError,
+  AuthenticationError,
+  NetworkError,
+  ValidationError
+});

package/dist/index.mjs

@@ -0,0 +1,248 @@
+// src/errors.ts
+var AlertSamuraiError = class extends Error {
+  constructor(message, statusCode, response) {
+    super(message);
+    this.statusCode = statusCode;
+    this.response = response;
+    this.name = "AlertSamuraiError";
+  }
+};
+var AuthenticationError = class extends AlertSamuraiError {
+  constructor(message = "Invalid or missing DSN") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends AlertSamuraiError {
+  constructor(message) {
+    super(message, 400);
+    this.name = "ValidationError";
+  }
+};
+var NetworkError = class extends AlertSamuraiError {
+  constructor(message = "Network request failed") {
+    super(message);
+    this.name = "NetworkError";
+  }
+};
+
+// src/utils/retry.ts
+async function withRetry(fn, options) {
+  let lastError;
+  for (let attempt = 0; attempt <= options.retries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (error instanceof Error && (error.name === "AuthenticationError" || error.name === "ValidationError")) {
+        throw error;
+      }
+      if (attempt < options.retries) {
+        const delay = Math.min(
+          options.baseDelay * Math.pow(2, attempt),
+          options.maxDelay
+        );
+        await sleep(delay);
+      }
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.alertsamurai.com";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_RETRIES = 3;
+var AlertSamuraiClient = class {
+  constructor(config) {
+    if (!config.dsn) {
+      throw new ValidationError("DSN is required");
+    }
+    this.dsn = config.dsn;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.retries = config.retries ?? DEFAULT_RETRIES;
+  }
+  /**
+   * Send a custom metric for tracking and threshold-based alerting
+   *
+   * @param options - Metric options
+   * @returns Response with metric ID and alert trigger status
+   *
+   * @example
+   * ```typescript
+   * await client.sendMetric({
+   *   metricType: "photo_upload_speed",
+   *   value: 2.5,
+   *   unit: "MB/s",
+   *   environment: "production",
+   *   metadata: { userId: "123" },
+   * });
+   * ```
+   */
+  async sendMetric(options) {
+    this.validateMetric(options);
+    const body = {
+      metricType: options.metricType,
+      value: options.value,
+      unit: options.unit,
+      environment: options.environment,
+      metadata: options.metadata,
+      timestamp: this.normalizeTimestamp(options.timestamp)
+    };
+    return this.request("/api/metrics", body);
+  }
+  /**
+   * Send an application alert with priority level
+   *
+   * @param options - Alert options
+   * @returns Response with alert ID
+   *
+   * @example
+   * ```typescript
+   * await client.sendAlert({
+   *   message: "Database connection failed",
+   *   priority: "critical",
+   *   environment: "production",
+   *   data: { errorCode: "ECONNREFUSED" },
+   * });
+   * ```
+   */
+  async sendAlert(options) {
+    this.validateAlert(options);
+    return this.request("/api/alerts", options);
+  }
+  /**
+   * Send a critical priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async critical(message, data) {
+    return this.sendAlert({ message, priority: "critical", data });
+  }
+  /**
+   * Send an error priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async error(message, data) {
+    return this.sendAlert({ message, priority: "error", data });
+  }
+  /**
+   * Send a warning priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async warning(message, data) {
+    return this.sendAlert({ message, priority: "warning", data });
+  }
+  /**
+   * Send an info priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async info(message, data) {
+    return this.sendAlert({ message, priority: "info", data });
+  }
+  /**
+   * Send a debug priority alert
+   * @param message - Alert message
+   * @param data - Optional additional context data
+   */
+  async debug(message, data) {
+    return this.sendAlert({ message, priority: "debug", data });
+  }
+  async request(path, body) {
+    return withRetry(() => this.doRequest(path, body), {
+      retries: this.retries,
+      baseDelay: 1e3,
+      maxDelay: 1e4
+    });
+  }
+  async doRequest(path, body) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch(`${this.baseUrl}${path}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.dsn}`
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status === 401) {
+        throw new AuthenticationError();
+      }
+      if (!response.ok) {
+        const errorBody = await response.json().catch(() => ({}));
+        throw new AlertSamuraiError(
+          errorBody.message || `Request failed with status ${response.status}`,
+          response.status,
+          errorBody
+        );
+      }
+      return response.json();
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof AlertSamuraiError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new NetworkError("Request timed out");
+      }
+      throw new NetworkError(
+        error instanceof Error ? error.message : "Unknown network error"
+      );
+    }
+  }
+  validateMetric(options) {
+    if (!options.metricType || typeof options.metricType !== "string") {
+      throw new ValidationError("metricType is required and must be a string");
+    }
+    if (options.metricType.length > 100) {
+      throw new ValidationError("metricType must be 100 characters or less");
+    }
+    if (typeof options.value !== "number" || isNaN(options.value)) {
+      throw new ValidationError("value is required and must be a number");
+    }
+    if (options.unit !== void 0 && typeof options.unit !== "string") {
+      throw new ValidationError("unit must be a string");
+    }
+    if (options.unit && options.unit.length > 50) {
+      throw new ValidationError("unit must be 50 characters or less");
+    }
+  }
+  validateAlert(options) {
+    if (!options.message || typeof options.message !== "string") {
+      throw new ValidationError("message is required and must be a string");
+    }
+    if (options.message.length > 4e3) {
+      throw new ValidationError("message must be 4000 characters or less");
+    }
+    const validPriorities = ["critical", "error", "warning", "info", "debug"];
+    if (!validPriorities.includes(options.priority)) {
+      throw new ValidationError(
+        `priority must be one of: ${validPriorities.join(", ")}`
+      );
+    }
+  }
+  normalizeTimestamp(timestamp) {
+    if (!timestamp) return void 0;
+    if (timestamp instanceof Date) return timestamp.toISOString();
+    if (typeof timestamp === "number") return new Date(timestamp).toISOString();
+    return timestamp;
+  }
+};
+export {
+  AlertSamuraiClient,
+  AlertSamuraiError,
+  AuthenticationError,
+  NetworkError,
+  ValidationError
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@alertsamurai/sdk-js",
+  "version": "0.0.1",
+  "description": "TypeScript SDK for AlertSamurai metrics and alerting",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "vitest",
+    "lint": "eslint src --ext .ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "alertsamurai",
+    "monitoring",
+    "metrics",
+    "alerting",
+    "observability"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}