@chirpier/chirpier-js 0.1.6 → 0.2.1

package/src/index.ts

@@ -1,126 +1,258 @@
-// Import necessary dependencies
 import axios, { AxiosInstance } from "axios";
 import axiosRetry from "axios-retry";
-import { Base64 } from "js-base64";
+import dotenv from "dotenv";
 import {
   DEFAULT_RETRIES,
   DEFAULT_TIMEOUT,
   DEFAULT_BATCH_SIZE,
   DEFAULT_FLUSH_DELAY,
-  MAX_QUEUE_SIZE,
+  DEFAULT_API_ENDPOINT,
+  DEFAULT_SERVICER_ENDPOINT,
 } from "./constants";
 import AsyncLock from "async-lock";
+import { v7 as uuidv7 } from "uuid";
 
-// Define logging levels
-export enum LogLevel {
+// Define logging levels as const enum for better tree-shaking
+export const enum LogLevel {
   None = 0,
   Error = 1,
   Info = 2,
   Debug = 3,
 }
 
-// Define the options interface for Chirpier initialization
-interface Options {
-  key: string;
-  region?: "us-west" | "eu-west" | "asia-southeast";
+export interface Config {
+  key?: string;
+  apiEndpoint?: string;
+  servicerEndpoint?: string;
   logLevel?: LogLevel;
+  retries?: number;
+  timeout?: number;
+  batchSize?: number;
+  flushDelay?: number;
+  /** @deprecated Queues are unbounded in memory. */
+  maxQueueSize?: number;
 }
 
-// Define the Event interface for monitoring
-export interface Event {
-  group_id: string;
-  stream_name: string;
+/**
+ * @deprecated Use Config.
+ */
+export type Options = Config;
+
+export interface Log {
+  log_id?: string;
+  agent?: string;
+  event: string;
   value: number;
+  meta?: unknown;
+  occurred_at?: string | Date;
+}
+
+export interface Event {
+	readonly event_id: string;
+	readonly agent?: string;
+	readonly event: string;
+	readonly title?: string;
+	readonly public: boolean;
+	readonly description?: string;
+	readonly unit?: string;
+	readonly timezone: string;
+	readonly created_at?: string;
+}
+
+export interface Policy {
+	readonly policy_id: string;
+	readonly event_id: string;
+	readonly title: string;
+	readonly description?: string;
+	readonly channel: string;
+	readonly period: string;
+	readonly aggregate: string;
+	readonly condition: string;
+	readonly threshold: number;
+	readonly severity: string;
+	readonly enabled: boolean;
+}
+
+export interface Alert {
+	readonly alert_id: string;
+	readonly policy_id: string;
+	readonly event_id: string;
+	readonly agent?: string;
+	readonly event: string;
+	readonly title: string;
+	readonly period: string;
+	readonly aggregate: string;
+	readonly condition: string;
+	readonly threshold: number;
+	readonly severity: string;
+	readonly status: string;
+	readonly value: number;
+	readonly count: number;
+	readonly min: number;
+	readonly max: number;
+	readonly triggered_at?: string;
+	readonly acknowledged_at?: string;
+	readonly resolved_at?: string;
+}
+
+export interface AlertDelivery {
+	readonly attempt_id: string;
+	readonly alert_id: string;
+	readonly webhook_id?: string;
+	readonly channel: string;
+	readonly target: string;
+	readonly status: string;
+	readonly response_status?: number;
+	readonly error_message?: string;
+	readonly created_at: string;
+}
+
+export interface EventLogPoint {
+	readonly event_id: string;
+	readonly agent?: string;
+	readonly event: string;
+	readonly period: string;
+	readonly occurred_at: string;
+	readonly count: number;
+	readonly value: number;
+	readonly squares: number;
+	readonly min: number;
+	readonly max: number;
 }
 
+export interface PaginationOptions {
+	period?: "minute" | "hour" | "day";
+	limit?: number;
+	offset?: number;
+}
+
+export type DeliveryKind = "alert" | "test" | "all";
+
 // Custom error class for Chirpier-specific errors
 export class ChirpierError extends Error {
-  constructor(message: string) {
+  constructor(
+    message: string,
+    public readonly code?: string
+  ) {
     super(message);
     this.name = "ChirpierError";
     Object.setPrototypeOf(this, ChirpierError.prototype);
   }
 }
 
-interface QueuedEvent {
-  event: Event;
-  timestamp: number;
-  retryCount: number;
+interface QueuedLog {
+  readonly log: Log;
+  readonly timestamp: number;
 }
 
-/**
- * Main Chirpier class for monitoring events.
- */
-export class Chirpier {
-  private static instance: Chirpier | null = null;
+export class Client {
   private readonly apiKey: string;
   private readonly apiEndpoint: string;
+  private readonly servicerEndpoint: string;
   private readonly retries: number;
   private readonly timeout: number;
   private readonly axiosInstance: AxiosInstance;
-  private eventQueue: QueuedEvent[] = [];
+  private logQueue: QueuedLog[] = [];
   private readonly batchSize: number;
   private readonly flushDelay: number;
   private flushTimeoutId: NodeJS.Timeout | null = null;
-  private readonly queueLock = new AsyncLock({
-    maxPending: MAX_QUEUE_SIZE,
-  });
-  private readonly flushLock = new AsyncLock({
-    maxPending: MAX_QUEUE_SIZE,
-  });
+  private readonly queueLock: AsyncLock;
+  private readonly flushLock: AsyncLock;
   private readonly logLevel: LogLevel;
 
-  /**
-   * Initializes a new instance of the Chirpier class.
-   * @param options - Configuration options for the SDK.
-   */
-  private constructor(options: Options) {
-    const { key, region = "eu-west", logLevel = LogLevel.None } = options;
+  constructor(options: Config = {}) {
+    const {
+      key: providedKey,
+      apiEndpoint = DEFAULT_API_ENDPOINT,
+      servicerEndpoint = DEFAULT_SERVICER_ENDPOINT,
+      logLevel = LogLevel.None,
+      retries = DEFAULT_RETRIES,
+      timeout = DEFAULT_TIMEOUT,
+      batchSize = DEFAULT_BATCH_SIZE,
+      flushDelay = DEFAULT_FLUSH_DELAY,
+      maxQueueSize,
+    } = options;
+
+    const key = resolveAPIKey(providedKey);
+
+    if (!key) {
+      throw new ChirpierError("API key is required", "INVALID_KEY");
+    }
 
-    if (!key || typeof key !== "string") {
-      throw new ChirpierError("API key is required and must be a string");
+    if (!isValidAPIKey(key)) {
+      throw new ChirpierError("Invalid API key: must start with 'chp_'", "INVALID_KEY");
     }
 
-    if (
-      typeof region !== "string" &&
-      !["us-west", "eu-west", "asia-southeast"].includes(region)
-    ) {
-      throw new ChirpierError(
-        "Region must be one of: us-west, eu-west, asia-southeast"
-      );
+    if (apiEndpoint !== undefined) {
+      if (typeof apiEndpoint !== "string" || apiEndpoint.trim().length === 0) {
+        throw new ChirpierError(
+          "apiEndpoint must be a non-empty string",
+          "INVALID_API_ENDPOINT"
+        );
+      }
+
+      let parsedURL: URL;
+      try {
+        parsedURL = new URL(apiEndpoint);
+      } catch {
+        throw new ChirpierError(
+          "apiEndpoint must be a valid absolute URL",
+          "INVALID_API_ENDPOINT"
+        );
+      }
+
+      if (parsedURL.protocol !== "https:" && parsedURL.protocol !== "http:") {
+        throw new ChirpierError(
+          "apiEndpoint must use http or https",
+          "INVALID_API_ENDPOINT"
+        );
+      }
     }
 
-    this.apiEndpoint = `https://${region}.chirpier.co/v1.0/events`;
+    // Validate numeric options
+    if (retries < 0 || !Number.isInteger(retries)) {
+      throw new ChirpierError("Retries must be a non-negative integer", "INVALID_RETRIES");
+    }
+    if (timeout <= 0) {
+      throw new ChirpierError("Timeout must be positive", "INVALID_TIMEOUT");
+    }
+    if (batchSize <= 0 || !Number.isInteger(batchSize)) {
+      throw new ChirpierError("Batch size must be a positive integer", "INVALID_BATCH_SIZE");
+    }
+    if (flushDelay < 0) {
+      throw new ChirpierError("Flush delay must be non-negative", "INVALID_FLUSH_DELAY");
+    }
+    this.apiEndpoint = apiEndpoint ?? DEFAULT_API_ENDPOINT;
+    this.servicerEndpoint = servicerEndpoint ?? DEFAULT_SERVICER_ENDPOINT;
     this.apiKey = key;
-    this.retries = DEFAULT_RETRIES;
-    this.timeout = DEFAULT_TIMEOUT;
-    this.batchSize = DEFAULT_BATCH_SIZE;
-    this.flushDelay = DEFAULT_FLUSH_DELAY;
+    this.retries = retries;
+    this.timeout = timeout;
+    this.batchSize = batchSize;
+    this.flushDelay = flushDelay;
     this.logLevel = logLevel;
 
-    // Create axios instance with authorization header
+    void maxQueueSize;
+    this.queueLock = new AsyncLock();
+    this.flushLock = new AsyncLock();
+
     this.axiosInstance = axios.create({
       headers: { Authorization: `Bearer ${this.apiKey}` },
       timeout: this.timeout,
     });
 
-    // Add the interceptor here
     this.axiosInstance.interceptors.response.use(
       (response) => response,
-      (error) => {
-        // Don't handle the error here; let axios-retry handle it
-        return Promise.reject(error);
-      }
+      (error) => Promise.reject(error)
     );
 
-    // Apply axios-retry to your Axios instance
     axiosRetry(this.axiosInstance, {
       retries: this.retries,
       retryDelay: (retryCount) => {
-        return Math.pow(2, retryCount) * 1000; // Exponential backoff starting at 1 second
+        const baseDelay = Math.pow(2, retryCount) * 1000;
+        const jitter = Math.random() * 0.3 * baseDelay;
+        return baseDelay + jitter;
       },
       retryCondition: (error) => {
-        // Retry on network errors, 5xx errors, and 429 (Too Many Requests)
         return (
           axiosRetry.isNetworkError(error) ||
           axiosRetry.isRetryableError(error) ||
@@ -131,60 +263,105 @@ export class Chirpier {
     });
   }
 
-  /**
-   * Gets the singleton instance of Chirpier, creating it if it doesn't exist.
-   * @param options - Configuration options for the SDK.
-   * @returns The Chirpier instance.
-   */
-  public static getInstance(options: Options): Chirpier | null {
-    if (!Chirpier.instance && options.key) {
-      Chirpier.instance = new Chirpier(options);
+  private isValidLog(log: Log): boolean {
+    const now = Date.now();
+    const oldestAllowed = now - 30 * 24 * 60 * 60 * 1000;
+    const newestAllowed = now + 24 * 60 * 60 * 1000;
+
+    if (typeof log.event !== "string" || log.event.trim().length === 0) {
+      return false;
     }
-    return Chirpier.instance;
-  }
-
-  /**
-   * Validates the event structure.
-   * @param event - The event to validate.
-   * @returns True if valid, false otherwise.
-   */
-  private isValidEvent(event: Event): boolean {
-    return (
-      typeof event.group_id === "string" &&
-      /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(
-        event.group_id
-      ) &&
-      event.group_id.trim().length > 0 &&
-      typeof event.stream_name === "string" &&
-      event.stream_name.trim().length > 0 &&
-      typeof event.value === "number"
-    );
-  }
 
-  /**
-   * Monitors an event by adding it to the queue and scheduling a flush if necessary.
-   * @param event - The event to monitor.
-   */
-  public async monitor(event: Event): Promise<void> {
-    if (!this.isValidEvent(event)) {
-      if (this.logLevel >= LogLevel.Debug) {
-        console.debug("Invalid event format, dropping event:", event);
+    if (log.log_id !== undefined) {
+      if (typeof log.log_id !== "string") {
+        return false;
+      }
+
+      const trimmedLogID = log.log_id.trim();
+      if (trimmedLogID.length > 0 && !isUUID(trimmedLogID)) {
+        return false;
       }
-      return; // Silently drop the event
     }
 
-    await this.queueLock.acquire("queue", async () => {
-      if (this.eventQueue.length >= MAX_QUEUE_SIZE) {
-        if (this.logLevel >= LogLevel.Debug) {
-          console.debug("Event queue is full, dropping event:", event);
+    if (typeof log.value !== "number" || !Number.isFinite(log.value)) {
+      return false;
+    }
+
+    if (log.agent !== undefined && typeof log.agent !== "string") {
+      return false;
+    }
+
+    if (log.meta !== undefined) {
+      try {
+        const serializedMeta = JSON.stringify(log.meta);
+        if (serializedMeta === undefined) {
+          return false;
         }
-        return; // Silently drop the event
+      } catch {
+        return false;
+      }
+    }
+
+    if (log.occurred_at !== undefined) {
+      const occurredAtMillis =
+        log.occurred_at instanceof Date
+          ? log.occurred_at.getTime()
+          : new Date(log.occurred_at).getTime();
+
+      if (!Number.isFinite(occurredAtMillis)) {
+        return false;
+      }
+
+      if (occurredAtMillis < oldestAllowed || occurredAtMillis > newestAllowed) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  private normalizeLog(log: Log): Log {
+    const normalizedLog: Log = {
+      log_id: resolveLogID(log.log_id),
+      event: log.event.trim(),
+      value: log.value,
+    };
+
+    if (typeof log.agent === "string") {
+      const trimmedAgent = log.agent.trim();
+      if (trimmedAgent.length > 0) {
+        normalizedLog.agent = trimmedAgent;
       }
+    }
+
+    if (log.meta !== undefined) {
+      normalizedLog.meta = log.meta;
+    }
 
-      this.eventQueue.push({ event, timestamp: Date.now(), retryCount: 0 });
+    if (log.occurred_at !== undefined) {
+      const occurredAtDate =
+        log.occurred_at instanceof Date ? log.occurred_at : new Date(log.occurred_at);
+      normalizedLog.occurred_at = occurredAtDate.toISOString();
+    }
+
+    return normalizedLog;
+  }
+
+  public async log(log: Log): Promise<void> {
+    if (!this.isValidLog(log)) {
+      throw new ChirpierError(
+        "Invalid log format: log_id must be a UUID when provided, event must not be empty, value must be a finite number, agent must be a string when provided, meta must be JSON-encodable, and occurred_at must be within the last 30 days and no more than 1 day in the future",
+        "INVALID_LOG"
+      );
+    }
+
+    const normalizedLog = this.normalizeLog(log);
+
+    await this.queueLock.acquire("queue", async () => {
+      this.logQueue.push({ log: normalizedLog, timestamp: Date.now() });
     });
 
-    if (this.eventQueue.length >= this.batchSize) {
+    if (this.logQueue.length >= this.batchSize) {
       await this.flushQueue();
     } else if (!this.flushTimeoutId) {
       this.flushTimeoutId = setTimeout(
@@ -194,142 +371,237 @@ export class Chirpier {
     }
   }
 
-  /**
-   * Flushes the event queue by sending all events to the API.
-   */
   private async flushQueue(): Promise<void> {
-    // Acquire the flush lock
     await this.flushLock.acquire("flush", async () => {
-      let eventsToSend: QueuedEvent[] = [];
+      let logsToSend: QueuedLog[] = [];
 
-      // Extract events from the queue under the queue lock
-      await this.queueLock.acquire("eventQueue", async () => {
-        if (this.eventQueue.length > 0) {
-          eventsToSend = [...this.eventQueue];
-          this.eventQueue = [];
+      await this.queueLock.acquire("logQueue", async () => {
+        if (this.logQueue.length > 0) {
+          logsToSend = [...this.logQueue];
+          this.logQueue = [];
         }
       });
 
-      if (eventsToSend.length === 0) {
+      if (logsToSend.length === 0) {
         return;
       }
 
       try {
-        // Clear any pending flush timeout
         if (this.flushTimeoutId) {
           clearTimeout(this.flushTimeoutId);
           this.flushTimeoutId = null;
         }
 
-        // Attempt to send events
-        await this.sendEvents(eventsToSend.map((qe) => qe.event));
+        await this.sendLogs(logsToSend.map((queuedLog) => queuedLog.log));
 
         if (this.logLevel >= LogLevel.Info) {
-          console.info(`Successfully sent ${eventsToSend.length} events`);
+          console.info(`Successfully sent ${logsToSend.length} logs`);
         }
       } catch (error) {
-        // Log failure
         if (this.logLevel >= LogLevel.Error) {
-          console.error("Failed to send events:", error);
+          console.error("Failed to send logs:", error);
         }
 
-        // Requeue failed events with retry count checks
-        const retryableEvents: QueuedEvent[] = [];
-        for (const queuedEvent of eventsToSend) {
-          if (queuedEvent.retryCount >= this.retries) {
-            if (this.logLevel >= LogLevel.Error) {
-              console.error(
-                `Dropping event after ${this.retries} retries:`,
-                queuedEvent.event
-              );
-            }
-            continue; // Skip adding this event back to the queue
-          }
-
-          // Increment retry count and add back to the queue
-          queuedEvent.retryCount++;
-          retryableEvents.push(queuedEvent);
-        }
-
-        // Requeue remaining retryable events
-        await this.queueLock.acquire("eventQueue", async () => {
-          this.eventQueue = [...retryableEvents, ...this.eventQueue];
+        await this.queueLock.acquire("logQueue", async () => {
+          this.logQueue = [...logsToSend, ...this.logQueue];
         });
       }
     });
   }
 
-  /**
-   * Sends multiple events to the API in a batch.
-   * @param events - The array of events to send.
-   */
-  private async sendEvents(events: Event[]): Promise<void> {
-    await this.axiosInstance.post(this.apiEndpoint, events);
+  private async sendLogs(logs: Log[]): Promise<void> {
+    await this.axiosInstance.post(this.apiEndpoint, logs);
   }
 
-  // Stop the timeout and uninitialize the Chirpier instance
-  public static async stop(): Promise<void> {
-    if (!Chirpier.instance) {
-      return;
-    }
-    if (Chirpier.instance.flushTimeoutId) {
-      clearTimeout(Chirpier.instance.flushTimeoutId);
-      Chirpier.instance.flushTimeoutId = null;
+  public async flush(): Promise<void> {
+    await this.flushQueue();
+  }
+
+  public async shutdown(): Promise<void> {
+    if (this.flushTimeoutId) {
+      clearTimeout(this.flushTimeoutId);
+      this.flushTimeoutId = null;
     }
-    // Flush any remaining events in the queue
-    await Chirpier.instance.flushQueue();
-    // Uninitialize the Chirpier instance
-    Chirpier.instance = null;
+
+    await this.flushQueue();
+  }
+
+  public async close(): Promise<void> {
+    await this.shutdown();
+  }
+
+  public async listEvents(): Promise<Event[]> {
+	const response = await this.axiosInstance.get<Event[]>(`${this.servicerEndpoint}/events`);
+	return response.data;
+  }
+
+  public async getEvent(eventID: string): Promise<Event> {
+	const response = await this.axiosInstance.get<Event>(`${this.servicerEndpoint}/events/${eventID}`);
+	return response.data;
+  }
+
+  public async updateEvent(
+	eventID: string,
+	payload: Partial<Omit<Event, "event_id" | "created_at">>
+  ): Promise<Event> {
+	const response = await this.axiosInstance.put<Event>(
+		`${this.servicerEndpoint}/events/${eventID}`,
+		payload
+	);
+	return response.data;
+  }
+
+  public async listPolicies(): Promise<Policy[]> {
+	const response = await this.axiosInstance.get<Policy[]>(`${this.servicerEndpoint}/policies`);
+	return response.data;
+  }
+
+  public async createPolicy(payload: Omit<Policy, "policy_id">): Promise<Policy> {
+	const response = await this.axiosInstance.post<Policy>(`${this.servicerEndpoint}/policies`, payload);
+	return response.data;
+  }
+
+  public async listAlerts(status?: string): Promise<Alert[]> {
+	const endpoint = status
+		? `${this.servicerEndpoint}/alerts?status=${encodeURIComponent(status)}`
+		: `${this.servicerEndpoint}/alerts`;
+	const response = await this.axiosInstance.get<Alert[]>(endpoint);
+	return response.data;
+  }
+
+  public async getAlertDeliveries(alertID: string, options: { limit?: number; offset?: number; kind?: DeliveryKind } = {}): Promise<AlertDelivery[]> {
+	const params = new URLSearchParams();
+	if (options.kind) {
+		params.set("kind", options.kind);
+	}
+	if (typeof options.limit === "number") {
+		params.set("limit", String(options.limit));
+	}
+	if (typeof options.offset === "number") {
+		params.set("offset", String(options.offset));
+	}
+	const suffix = params.toString() ? `?${params.toString()}` : "";
+	const response = await this.axiosInstance.get<AlertDelivery[]>(`${this.servicerEndpoint}/alerts/${alertID}/deliveries${suffix}`);
+	return response.data;
+  }
+
+  public async acknowledgeAlert(alertID: string): Promise<Alert> {
+	const response = await this.axiosInstance.post<Alert>(`${this.servicerEndpoint}/alerts/${alertID}/acknowledge`);
+	return response.data;
   }
+
+  public async archiveAlert(alertID: string): Promise<Alert> {
+	const response = await this.axiosInstance.post<Alert>(`${this.servicerEndpoint}/alerts/${alertID}/archive`);
+	return response.data;
+  }
+
+  public async testWebhook(webhookID: string): Promise<void> {
+	await this.axiosInstance.post(`${this.servicerEndpoint}/webhooks/${webhookID}/test`);
+  }
+
+  public async getEventLogs(eventID: string, options: PaginationOptions = {}): Promise<EventLogPoint[]> {
+	const params = new URLSearchParams();
+	if (options.period) {
+		params.set("period", options.period);
+	}
+	if (typeof options.limit === "number") {
+		params.set("limit", String(options.limit));
+	}
+	if (typeof options.offset === "number") {
+		params.set("offset", String(options.offset));
+	}
+	const suffix = params.toString() ? `?${params.toString()}` : "";
+	const response = await this.axiosInstance.get<EventLogPoint[]>(`${this.servicerEndpoint}/events/${eventID}/logs${suffix}`);
+	return response.data;
+  }
+
+  public async resolveAlert(alertID: string): Promise<Alert> {
+	const response = await this.axiosInstance.post<Alert>(`${this.servicerEndpoint}/alerts/${alertID}/resolve`);
+	return response.data;
+  }
+
 }
 
-/**
- * Decodes a base64url encoded string.
- * @param str - The base64url encoded string to decode.
- * @returns The decoded string.
- */
-function base64UrlDecode(str: string): string {
-  // Replace '-' with '+' and '_' with '/'
-  let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
-  // Pad the base64 string
-  const padding = base64.length % 4;
-  if (padding !== 0) {
-    base64 += "=".repeat(4 - padding);
-  }
-  return Base64.decode(base64);
+let instance: Client | null = null;
+
+export function createClient(config: Config = {}): Client {
+  return new Client(config);
 }
 
-/**
- * Validates if the provided token is a valid JWT.
- * @param token - The token to validate.
- * @returns True if valid, false otherwise.
- */
-function isValidJWT(token: string): boolean {
-  const parts = token.split(".");
-  if (parts.length !== 3) {
-    return false;
+function isNodeEnvironment(): boolean {
+  return typeof process !== "undefined" && !!(process.versions && process.versions.node);
+}
+
+function isValidAPIKey(token: string): boolean {
+  return token.startsWith("chp_") && token.length > "chp_".length;
+}
+
+function isUUID(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+function resolveLogID(logID?: string): string {
+  if (typeof logID === "string") {
+    const trimmedLogID = logID.trim();
+    if (trimmedLogID.length > 0) {
+      return trimmedLogID;
+    }
+  }
+
+  return uuidv7();
+}
+
+function loadDotEnvKey(): string | undefined {
+  if (!isNodeEnvironment()) {
+    return undefined;
   }
+
   try {
-    const header = JSON.parse(base64UrlDecode(parts[0]));
-    const payload = JSON.parse(base64UrlDecode(parts[1]));
-    return typeof header === "object" && typeof payload === "object";
-  } catch (error) {
-    console.error("Failed to validate JWT:", error);
-    return false;
+    dotenv.config({ path: ".env", override: false });
+  } catch {
+    return undefined;
+  }
+
+  const envKey = process.env.CHIRPIER_API_KEY;
+  if (typeof envKey !== "string") {
+    return undefined;
   }
+
+  const trimmedKey = envKey.trim();
+  return trimmedKey.length > 0 ? trimmedKey : undefined;
 }
 
-/**
- * Initializes the Chirpier SDK.
- * @param options - Configuration options for the SDK.
- */
-export function initialize(options: Options): void {
-  if (!isValidJWT(options.key)) {
-    throw new ChirpierError("Invalid API key: Not a valid JWT");
+function resolveAPIKey(providedKey?: string): string | undefined {
+  if (typeof providedKey === "string" && providedKey.trim().length > 0) {
+    return providedKey.trim();
+  }
+
+  if (typeof process !== "undefined" && process.env && typeof process.env.CHIRPIER_API_KEY === "string") {
+    const envKey = process.env.CHIRPIER_API_KEY.trim();
+    if (envKey.length > 0) {
+      return envKey;
+    }
+  }
+
+  return loadDotEnvKey();
+}
+
+export function initialize(options: Config = {}): void {
+  const resolvedKey = resolveAPIKey(options.key);
+  if (!resolvedKey) {
+    throw new ChirpierError("API key is required", "INVALID_KEY");
+  }
+
+  if (!isValidAPIKey(resolvedKey)) {
+    throw new ChirpierError("Invalid API key: must start with 'chp_'", "INVALID_KEY");
+  }
+
+  if (instance) {
+    return;
   }
 
   try {
-    Chirpier.getInstance(options);
+    instance = new Client({ ...options, key: resolvedKey });
   } catch (error) {
     if (error instanceof ChirpierError) {
       if (options.logLevel && options.logLevel >= LogLevel.Error) {
@@ -347,19 +619,33 @@ export function initialize(options: Options): void {
   }
 }
 
-/**
- * Monitors an event using the Chirpier SDK.
- * @param event - The event to monitor.
- */
-export function monitor(event: Event): void {
-  const instance = Chirpier.getInstance({} as Options);
+export async function logEvent(log: Log): Promise<void> {
+  if (!instance) {
+    throw new ChirpierError(
+      "Chirpier SDK is not initialized. Please call initialize() first.",
+      "NOT_INITIALIZED"
+    );
+  }
+
+  await instance.log(log);
+}
+
+export async function stop(): Promise<void> {
+  if (!instance) {
+    return;
+  }
+
+  await instance.shutdown();
+  instance = null;
+}
+
+export async function flush(): Promise<void> {
   if (!instance) {
     throw new ChirpierError(
-      "Chirpier SDK is not initialized. Please call initialize() first."
+      "Chirpier SDK is not initialized. Please call initialize() first.",
+      "NOT_INITIALIZED"
     );
   }
 
-  instance.monitor(event).catch((error) => {
-    console.error("Error in monitor function:", error);
-  });
+  await instance.flush();
 }