API Reference

interface IgniterTelemetryActorOptions {
  description?: string;
  required?: boolean;
}

interface IgniterTelemetryScopeOptions {
  description?: string;
  required?: boolean;
}

interface IgniterTelemetryEventsValidationOptions {
  mode?: "development" | "always" | "none";
  strict?: boolean;
}

interface IgniterTelemetryEmitInput {
  level?: "debug" | "info" | "warn" | "error" | "fatal";
  time?: string;
  sessionId?: string;
  actor?: { type: string; id?: string; tags?: Record<string, unknown> };
  scope?: { type: string; id: string; tags?: Record<string, unknown> };
  attributes?: Record<string, unknown>;
  error?: {
    name: string;
    message: string;
    code?: string;
    stack?: string;
  };
  source?: {
    causer?: string;
    file?: string;
    line?: number;
  };
}

LoggerTransportAdapter.create(options: {
  logger: { info, warn, error, debug };  // Required
  format?: "json" | "pretty";            // Default: "pretty"
  minLevel?: string;                       // Default: "debug"
  includeTimestamp?: boolean;              // Default: true
})

HttpTransportAdapter.create(options: {
  url: string;                             // Required
  headers?: Record<string, string>;        // Default: {}
  timeout?: number;                        // Default: 5000
  retries?: number;                        // Default: 0
})

OtltpTransportAdapter.create(options: {
  url: string;                             // Required
  headers?: Record<string, string>;        // Default: {}
})

SentryTransportAdapter.create(options: {
  sentry: typeof Sentry;                   // Required
})

SlackTransportAdapter.create(options: {
  webhookUrl: string;                      // Required
  minLevel?: string;                       // Default: "warn"
  username?: string;                       // Default: "Igniter Telemetry"
  iconEmoji?: string;                      // Default: ":bar_chart:"
})

DiscordTransportAdapter.create(options: {
  webhookUrl: string;                      // Required
  minLevel?: string;                       // Default: "warn"
  username?: string;                       // Default: "Igniter Telemetry"
  avatarUrl?: string;
})

TelegramTransportAdapter.create(options: {
  botToken: string;                        // Required
  chatId: string;                          // Required
  minLevel?: string;                       // Default: "error"
})

InMemoryTransportAdapter.create()

// Methods:
.getEvents() => Envelope[]   // Get all captured events
.clear()                      // Clear captured events

MockTelemetryAdapter.create()

// Methods:
.getLastEvent() => Envelope | undefined  // Most recent event
.getEvents() => Envelope[]               // All captured events
.clear()                                  // Clear captured events

StoreStreamTransportAdapter.create(options: {
  store: IgniterStore;                     // Required
  stream?: string;                         // Default: "telemetry:events"
  maxLen?: number;                         // Default: 10000
})

interface IgniterTelemetryTransportAdapter {
  readonly type: string;
  init?(meta: TransportMeta): Promise<void>;
  handle(envelope: Envelope): Promise<void>;
  flush?(): Promise<void>;
  shutdown?(): Promise<void>;
}

interface IgniterTelemetryTransportMeta {
  service: string;
  environment: string;
  version?: string;
}

interface IgniterTelemetrySamplingPolicy {
  debugRate?: number;       // Default: 0.01
  infoRate?: number;        // Default: 0.1
  warnRate?: number;        // Default: 1.0
  errorRate?: number;       // Default: 1.0
  always?: string[];        // Glob patterns always sampled
  never?: string[];         // Glob patterns never sampled
}

interface IgniterTelemetryRedactionPolicy {
  denylistKeys?: string[];    // Keys to remove (case-insensitive)
  hashKeys?: string[];        // Keys to SHA-256 hash (case-insensitive)
  maxStringLength?: number;   // Default: 5000
}

interface IgniterTelemetryEnvelope {
  name: string;
  time: string;
  level: "debug" | "info" | "warn" | "error" | "fatal";
  service: string;
  environment: string;
  version?: string;
  sessionId: string;
  actor?: { type: string; id?: string; tags?: Record<string, unknown> };
  scope?: { type: string; id: string; tags?: Record<string, unknown> };
  attributes?: Record<string, unknown>;
  error?: { name: string; message: string; code?: string; stack?: string };
  source?: { causer?: string; file?: string; line?: number };
}

import { IgniterTelemetryError, IGNITER_TELEMETRY_ERROR_CODES } from "@igniter-js/telemetry";

// Configuration
TELEMETRY_SERVICE_REQUIRED
TELEMETRY_ENVIRONMENT_REQUIRED
TELEMETRY_CONFIGURATION_INVALID

// Transport
TELEMETRY_INVALID_TRANSPORT
TELEMETRY_TRANSPORT_FAILED
TELEMETRY_TRANSPORT_INIT_FAILED

// Events
TELEMETRY_INVALID_EVENT_NAME
TELEMETRY_UNKNOWN_EVENT
TELEMETRY_DUPLICATE_EVENT

// Schema & Validation
TELEMETRY_SCHEMA_VALIDATION_FAILED
TELEMETRY_INVALID_NAMESPACE
TELEMETRY_RESERVED_NAMESPACE
TELEMETRY_DUPLICATE_NAMESPACE

// Sessions
TELEMETRY_SESSION_ENDED
TELEMETRY_SESSION_INVALID

// Scope & Actor
TELEMETRY_DUPLICATE_SCOPE
TELEMETRY_INVALID_SCOPE
TELEMETRY_DUPLICATE_ACTOR
TELEMETRY_INVALID_ACTOR

// Emit & Runtime
TELEMETRY_EMIT_FAILED
TELEMETRY_RUNTIME_NOT_INITIALIZED

class IgniterTelemetryError extends IgniterError {
  readonly code: IgniterTelemetryErrorCode;
  static is(error: unknown): error is IgniterTelemetryError;
  hasCode(code: IgniterTelemetryErrorCode): boolean;
}

type IgniterTelemetryLevel = "debug" | "info" | "warn" | "error" | "fatal";

// Level priority values (used internally for minLevel filtering)
IGNITER_TELEMETRY_LEVEL_PRIORITY = { debug: 10, info: 20, warn: 30, error: 40, fatal: 50 }

// Event registry types
type IgniterTelemetryFlattenRegistryKeys<TRegistry>;
type IgniterTelemetryGetEventSchema<TRegistry, TKey>;
type IgniterTelemetryInferEventSchema<TSchema>;

// Session types
type IgniterTelemetrySessionState;
type IIgniterTelemetrySession<TActor, TScope>;

// Manager type
type IIgniterTelemetryManager<TRegistry, TScopes, TActors>;