@zapier/zapier-sdk 0.13.3 → 0.13.4

package/src/plugins/eventEmission/index.ts

@@ -0,0 +1,294 @@
+/**
+ * Event Emission Plugin for Zapier SDK
+ *
+ * Provides silent telemetry event emission capability to the SDK.
+ * All events are emitted asynchronously and failures are silently handled.
+ */
+
+import type { Plugin } from "../../types/plugin";
+import type { BaseEvent } from "../../types/telemetry-events";
+import type { EventTransport, TransportConfig } from "./transport";
+import { createTransport } from "./transport";
+import { generateEventId, getCurrentTimestamp, getReleaseId } from "./utils";
+import {
+  buildApplicationLifecycleEvent,
+  buildErrorEventWithContext,
+} from "./builders";
+import { TRACKING_API_ENDPOINT } from "../../constants";
+
+// Plugin configuration
+export interface EventEmissionConfig {
+  enabled?: boolean;
+  transport?: TransportConfig;
+}
+
+// Context provided by this plugin
+export interface EventEmissionContext {
+  eventEmission: {
+    transport: EventTransport;
+    config: EventEmissionConfig;
+    // Generic event emission method
+    emit<T extends any>(subject: string, event: T): void;
+    // Builder for base event properties
+    createBaseEvent(): BaseEvent;
+  };
+}
+
+export interface EventEmissionProvides {
+  context: EventEmissionContext;
+}
+
+const APPLICATION_LIFECYCLE_EVENT_SUBJECT =
+  "platform.sdk.ApplicationLifecycleEvent";
+const ERROR_OCCURRED_EVENT_SUBJECT = "platform.sdk.ErrorOccurredEvent";
+
+// Silent emission wrapper - ensures events never disrupt SDK operation
+async function silentEmit<T extends any>(
+  transport: EventTransport,
+  subject: string,
+  event: T,
+): Promise<void> {
+  try {
+    // Fire and forget - don't await the transport
+    transport.emit(subject, event).catch(() => {
+      // Silently ignore transport failures
+    });
+  } catch {
+    // Silently ignore all errors
+  }
+}
+
+// Helper to get transport config from environment or defaults
+function getTransportConfig(): TransportConfig {
+  const envTransport = process?.env?.ZAPIER_SDK_TELEMETRY_TRANSPORT;
+
+  if (envTransport === "noop" || envTransport === "disabled") {
+    return { type: "noop" };
+  }
+
+  if (envTransport === "console") {
+    return { type: "console" };
+  }
+
+  // Default to HTTP transport
+  const endpoint =
+    process?.env?.ZAPIER_SDK_TELEMETRY_ENDPOINT || TRACKING_API_ENDPOINT;
+
+  return {
+    type: "http",
+    endpoint,
+  };
+}
+
+export const eventEmissionPlugin: Plugin<
+  {},
+  { options: { eventEmission?: EventEmissionConfig } },
+  EventEmissionProvides
+> = ({ context }) => {
+  const defaultTransport = getTransportConfig();
+
+  // Merge config: env var takes precedence over options, options take precedence over defaults
+  const config: EventEmissionConfig = {
+    enabled: context.options.eventEmission?.enabled ?? true,
+    transport:
+      // If env var is set, use it (defaultTransport will be from env)
+      process?.env?.ZAPIER_SDK_TELEMETRY_TRANSPORT
+        ? defaultTransport
+        : // Otherwise, use option transport or default
+          (context.options.eventEmission?.transport ?? defaultTransport),
+  };
+
+  const startupTime = Date.now();
+  let shutdownStartTime: number | null = null;
+
+  // If disabled, return noop implementations
+  if (!config.enabled) {
+    return {
+      context: {
+        eventEmission: {
+          transport: createTransport({ type: "noop" }),
+          config,
+          emit: () => {},
+          createBaseEvent: (): BaseEvent => ({
+            event_id: generateEventId(),
+            timestamp_ms: getCurrentTimestamp(),
+            release_id: getReleaseId(),
+            customuser_id: null,
+            account_id: null,
+            identity_id: null,
+            visitor_id: null,
+            correlation_id: null,
+          }),
+        },
+      },
+    };
+  }
+
+  let transport: EventTransport;
+  try {
+    transport = createTransport(config.transport || { type: "noop" });
+  } catch {
+    // If transport creation fails, fallback to noop to maintain silent operation
+    transport = createTransport({ type: "noop" });
+  }
+
+  // Helper to create base event
+  const createBaseEventHelper = (): BaseEvent => ({
+    event_id: generateEventId(),
+    timestamp_ms: getCurrentTimestamp(),
+    release_id: getReleaseId(),
+    customuser_id: null,
+    account_id: null,
+    identity_id: null,
+    visitor_id: null,
+    correlation_id: null,
+  });
+
+  // Register lifecycle event handlers if enabled
+  if (config.enabled) {
+    // Emit startup event
+    const startupEvent = buildApplicationLifecycleEvent({
+      lifecycle_event_type: "startup",
+    });
+    silentEmit(transport, APPLICATION_LIFECYCLE_EVENT_SUBJECT, startupEvent);
+
+    // Register process event handlers (Node.js only)
+    if (typeof process?.on === "function") {
+      // Handle normal process exit
+      process.on("exit", (code: number) => {
+        const uptime = Date.now() - startupTime;
+        const shutdownDuration = shutdownStartTime
+          ? Date.now() - shutdownStartTime
+          : null;
+
+        const exitEvent = buildApplicationLifecycleEvent({
+          lifecycle_event_type: "exit",
+          exit_code: code,
+          uptime_ms: uptime,
+          is_graceful_shutdown: code === 0,
+          shutdown_duration_ms: shutdownDuration,
+        });
+        silentEmit(transport, APPLICATION_LIFECYCLE_EVENT_SUBJECT, exitEvent);
+      });
+
+      // Handle uncaught exceptions
+      process.on("uncaughtException", async (error: Error) => {
+        const errorEvent = buildErrorEventWithContext({
+          error_message: error.message || "Unknown error",
+          error_type: "UncaughtException",
+          error_stack_trace: error.stack || null,
+          error_severity: "critical",
+          is_user_facing: false,
+          is_recoverable: false,
+          execution_start_time: startupTime,
+        });
+
+        // Wait up to 300ms for telemetry to send before allowing process to exit
+        try {
+          await Promise.race([
+            transport.emit(ERROR_OCCURRED_EVENT_SUBJECT, errorEvent),
+            new Promise((resolve) => setTimeout(resolve, 300)),
+          ]);
+        } catch {
+          // Silently ignore telemetry failures
+        }
+        // Let Node.js exit naturally after all handlers complete
+      });
+
+      // Handle unhandled promise rejections
+      process.on(
+        "unhandledRejection",
+        async (reason: any, promise: Promise<any>) => {
+          const errorMessage =
+            reason instanceof Error
+              ? reason.message
+              : typeof reason === "string"
+                ? reason
+                : "Unhandled promise rejection";
+
+          const errorStack = reason instanceof Error ? reason.stack : null;
+
+          const errorEvent = buildErrorEventWithContext({
+            error_message: errorMessage,
+            error_type: "UnhandledRejection",
+            error_stack_trace: errorStack,
+            error_severity: "critical",
+            is_user_facing: false,
+            is_recoverable: false,
+            execution_start_time: startupTime,
+            error_metadata: {
+              promise: String(promise),
+            },
+          });
+
+          // Wait up to 300ms for telemetry to send
+          try {
+            await Promise.race([
+              transport.emit(ERROR_OCCURRED_EVENT_SUBJECT, errorEvent),
+              new Promise((resolve) => setTimeout(resolve, 300)),
+            ]);
+          } catch {
+            // Silently ignore telemetry failures
+          }
+        },
+      );
+
+      // Handle termination signals
+      const handleSignal = async (signal: string) => {
+        shutdownStartTime = Date.now();
+        const uptime = Date.now() - startupTime;
+
+        const signalEvent = buildApplicationLifecycleEvent({
+          lifecycle_event_type: "signal_termination",
+          signal_name: signal,
+          uptime_ms: uptime,
+          is_graceful_shutdown: true,
+        });
+
+        // Wait up to 300ms for telemetry to send
+        try {
+          await Promise.race([
+            transport.emit(APPLICATION_LIFECYCLE_EVENT_SUBJECT, signalEvent),
+            new Promise((resolve) => setTimeout(resolve, 300)),
+          ]);
+        } catch {
+          // Silently ignore telemetry failures
+        }
+        // Let other signal handlers run and decide when to exit
+      };
+
+      // Register signal handlers
+      ["SIGINT", "SIGTERM"].forEach((signal) => {
+        process.on(signal as any, () => handleSignal(signal));
+      });
+    }
+  }
+
+  return {
+    context: {
+      eventEmission: {
+        transport,
+        config,
+        emit: <T extends any>(subject: string, event: T) => {
+          silentEmit(transport, subject, event);
+        },
+        createBaseEvent: createBaseEventHelper,
+      },
+    },
+  };
+};
+
+// Export types and utilities for other plugins
+export type {
+  EventContext,
+  ApplicationLifecycleEventData,
+  EnhancedErrorEventData,
+} from "./types";
+export {
+  buildApplicationLifecycleEvent,
+  buildErrorEventWithContext,
+  buildErrorEvent,
+  createBaseEvent,
+} from "./builders";
+export type { BaseEvent } from "../../types/telemetry-events";
+export * from "./utils";

package/src/plugins/eventEmission/transport.test.ts

@@ -0,0 +1,214 @@
+/**
+ * Tests for Event Transport Layer
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  HttpTransport,
+  ConsoleTransport,
+  NoopTransport,
+  createTransport,
+} from "./transport";
+import type { TelemetryEvent } from "../../types/telemetry-events";
+
+// Mock fetch globally
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+// Mock console.log
+const mockConsoleLog = vi.spyOn(console, "log").mockImplementation(() => {});
+
+describe("Transport Layer", () => {
+  const sampleEvent: TelemetryEvent = {
+    event_id: "test-123",
+    timestamp_ms: Date.now(),
+    release_id: "test-release",
+    error_message: "Test error",
+    is_user_facing: false,
+  } as any;
+
+  const sampleSubject = "platform.sdk.ErrorOccurredEvent";
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("HttpTransport", () => {
+    it("should emit events via HTTP successfully", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+      });
+
+      const transport = new HttpTransport({
+        endpoint: "https://telemetry.example.com/events",
+        headers: { "x-api-key": "test-key" },
+      });
+
+      await transport.emit(sampleSubject, sampleEvent);
+
+      expect(mockFetch).toHaveBeenCalledWith(
+        "https://telemetry.example.com/events",
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            "x-api-key": "test-key",
+          },
+          body: JSON.stringify({
+            subject: sampleSubject,
+            properties: sampleEvent,
+          }),
+        },
+      );
+    });
+
+    it("should retry on HTTP failures", async () => {
+      // Fail twice, then succeed
+      mockFetch
+        .mockResolvedValueOnce({ ok: false, status: 500 })
+        .mockResolvedValueOnce({ ok: false, status: 500 })
+        .mockResolvedValueOnce({ ok: true, status: 200 });
+
+      const transport = new HttpTransport({
+        endpoint: "https://telemetry.example.com/events",
+        retryAttempts: 3,
+        retryDelayMs: 10, // Short delay for testing
+      });
+
+      await transport.emit(sampleSubject, sampleEvent);
+
+      expect(mockFetch).toHaveBeenCalledTimes(3);
+    });
+
+    it("should handle network errors silently", async () => {
+      mockFetch.mockRejectedValue(new Error("Network error"));
+
+      const transport = new HttpTransport({
+        endpoint: "https://telemetry.example.com/events",
+        retryAttempts: 1,
+        retryDelayMs: 1,
+      });
+
+      // Should not throw despite network error
+      await expect(
+        transport.emit(sampleSubject, sampleEvent),
+      ).resolves.toBeUndefined();
+    });
+
+    it("should stop retrying after max attempts", async () => {
+      mockFetch.mockResolvedValue({ ok: false, status: 500 });
+
+      const transport = new HttpTransport({
+        endpoint: "https://telemetry.example.com/events",
+        retryAttempts: 2,
+        retryDelayMs: 1,
+      });
+
+      await transport.emit(sampleSubject, sampleEvent);
+
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("ConsoleTransport", () => {
+    it("should log events to console", async () => {
+      const transport = new ConsoleTransport();
+
+      await transport.emit(sampleSubject, sampleEvent);
+
+      expect(mockConsoleLog).toHaveBeenCalledWith(
+        "[SDK Telemetry]",
+        JSON.stringify(
+          { subject: sampleSubject, properties: sampleEvent },
+          null,
+          2,
+        ),
+      );
+    });
+
+    it("should handle console errors silently", async () => {
+      mockConsoleLog.mockImplementation(() => {
+        throw new Error("Console error");
+      });
+
+      const transport = new ConsoleTransport();
+
+      // Should not throw despite console error
+      await expect(
+        transport.emit(sampleSubject, sampleEvent),
+      ).resolves.toBeUndefined();
+    });
+  });
+
+  describe("NoopTransport", () => {
+    it("should do nothing when emitting events", async () => {
+      const transport = new NoopTransport();
+
+      await transport.emit(sampleSubject, sampleEvent);
+
+      // Verify no side effects
+      expect(mockFetch).not.toHaveBeenCalled();
+      expect(mockConsoleLog).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("createTransport", () => {
+    it("should create HTTP transport with valid config", () => {
+      const transport = createTransport({
+        type: "http",
+        endpoint: "https://example.com",
+        headers: { "x-key": "value" },
+        retryAttempts: 5,
+        retryDelayMs: 2000,
+      });
+
+      expect(transport).toBeInstanceOf(HttpTransport);
+    });
+
+    it("should create console transport", () => {
+      const transport = createTransport({
+        type: "console",
+      });
+
+      expect(transport).toBeInstanceOf(ConsoleTransport);
+    });
+
+    it("should create noop transport by default", () => {
+      const transport = createTransport({
+        type: "noop",
+      });
+
+      expect(transport).toBeInstanceOf(NoopTransport);
+    });
+
+    it("should fallback to noop transport on invalid HTTP config", () => {
+      const transport = createTransport({
+        type: "http",
+        // Missing endpoint
+      });
+
+      expect(transport).toBeInstanceOf(NoopTransport);
+    });
+
+    it("should fallback to noop transport on unknown type", () => {
+      const transport = createTransport({
+        type: "unknown" as any,
+      });
+
+      expect(transport).toBeInstanceOf(NoopTransport);
+    });
+
+    it("should handle transport creation errors gracefully", () => {
+      // Since createTransport already handles errors internally,
+      // this test verifies that invalid configs don't throw
+      expect(() => {
+        const transport = createTransport({
+          type: "http" as const,
+          // Missing required endpoint - should fallback to noop
+        });
+        expect(transport).toBeInstanceOf(NoopTransport);
+      }).not.toThrow();
+    });
+  });
+});

package/src/plugins/eventEmission/transport.ts

@@ -0,0 +1,135 @@
+/**
+ * Transport abstraction layer for event emission
+ *
+ * Provides configurable transport mechanisms for emitting telemetry events.
+ * All transports implement silent failure to prevent SDK disruption.
+ */
+
+// Constants for transport configuration
+const DEFAULT_RETRY_ATTEMPTS = 2;
+const DEFAULT_RETRY_DELAY_MS = 300;
+
+// Transport interface - all implementations must be async and silent
+export interface EventTransport {
+  emit<T extends any>(subject: string, event: T): Promise<void>;
+  close?(): Promise<void>;
+}
+
+// Transport configuration
+export interface TransportConfig {
+  type: "http" | "console" | "noop";
+  endpoint?: string;
+  headers?: Record<string, string>;
+  retryAttempts?: number;
+  retryDelayMs?: number;
+}
+
+// HTTP Transport - sends events to remote endpoint
+export class HttpTransport implements EventTransport {
+  constructor(
+    private config: {
+      endpoint: string;
+      headers?: Record<string, string>;
+      retryAttempts?: number;
+      retryDelayMs?: number;
+    },
+  ) {}
+
+  async emit<T extends any>(subject: string, event: T): Promise<void> {
+    try {
+      await this.emitWithRetry(
+        subject,
+        event,
+        this.config.retryAttempts || DEFAULT_RETRY_ATTEMPTS,
+      );
+    } catch {
+      // Silent failure - never throw
+    }
+  }
+
+  private async emitWithRetry<T extends any>(
+    subject: string,
+    event: T,
+    attemptsLeft: number,
+  ): Promise<void> {
+    try {
+      const payload = {
+        subject,
+        properties: event,
+      };
+
+      const response = await fetch(this.config.endpoint, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers,
+        },
+        body: JSON.stringify(payload),
+      });
+
+      if (!response.ok && attemptsLeft > 1) {
+        await this.delay(this.config.retryDelayMs || DEFAULT_RETRY_DELAY_MS);
+        return this.emitWithRetry(subject, event, attemptsLeft - 1);
+      }
+    } catch (error) {
+      if (attemptsLeft > 1) {
+        await this.delay(this.config.retryDelayMs || DEFAULT_RETRY_DELAY_MS);
+        return this.emitWithRetry(subject, event, attemptsLeft - 1);
+      }
+      throw error;
+    }
+  }
+
+  private async delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+// Console Transport - logs events to console (for development)
+export class ConsoleTransport implements EventTransport {
+  async emit<T extends any>(subject: string, event: T): Promise<void> {
+    try {
+      console.log(
+        "[SDK Telemetry]",
+        JSON.stringify({ subject, properties: event }, null, 2),
+      );
+    } catch {
+      // Silent failure - never throw
+    }
+  }
+}
+
+// No-op Transport - discards all events (for testing/disabled state)
+export class NoopTransport implements EventTransport {
+  async emit<T extends any>(_subject: string, _event: T): Promise<void> {
+    // Intentionally do nothing
+  }
+}
+
+// Transport factory
+export function createTransport(config: TransportConfig): EventTransport {
+  try {
+    switch (config.type) {
+      case "http":
+        if (!config.endpoint) {
+          throw new Error("HTTP transport requires endpoint");
+        }
+        return new HttpTransport({
+          endpoint: config.endpoint,
+          headers: config.headers,
+          retryAttempts: config.retryAttempts,
+          retryDelayMs: config.retryDelayMs,
+        });
+
+      case "console":
+        return new ConsoleTransport();
+
+      case "noop":
+      default:
+        return new NoopTransport();
+    }
+  } catch {
+    // If transport creation fails, return noop to maintain silent operation
+    return new NoopTransport();
+  }
+}

package/src/plugins/eventEmission/types.ts

@@ -0,0 +1,58 @@
+// Common context that can be injected into events
+export interface EventContext {
+  customuser_id?: number | null;
+  account_id?: number | null;
+  identity_id?: number | null;
+  visitor_id?: string | null;
+  correlation_id?: string | null;
+  selected_api?: string | null;
+  app_id?: number | null;
+  app_version_id?: number | null;
+  zap_id?: number | null;
+  node_id?: number | null;
+  environment?: string | null;
+  sdk_version?: string | null;
+  operation_type?: string | null;
+}
+
+export interface ErrorEventData {
+  error_message: string;
+  is_user_facing: boolean;
+  error_type?: string | null;
+  error_status_code?: number | null;
+  error_stack_trace?: string | null;
+  error_source_method?: string | null;
+  error_source_file?: string | null;
+  error_line_number?: number | null;
+  operation_type?: string | null;
+  operation_key?: string | null;
+  error_severity?: string | null;
+  is_recoverable?: boolean | null;
+  error_metadata?: Record<string, string | null> | null;
+  parent_error_id?: string | null;
+  error_occurred_timestamp_ms?: number | null;
+  error_code?: string | null;
+  recovery_attempted?: boolean | null;
+  recovery_action?: string | null;
+  recovery_successful?: boolean | null;
+  execution_time_before_error_ms?: number | null;
+}
+
+// Enhanced Error Event Builder with runtime context
+export interface EnhancedErrorEventData extends ErrorEventData {
+  execution_start_time?: number | null;
+}
+
+export interface ApplicationLifecycleEventData {
+  lifecycle_event_type: "startup" | "exit" | "signal_termination";
+  exit_code?: number | null;
+  signal_name?: string | null;
+  uptime_ms?: number | null;
+  is_graceful_shutdown?: boolean | null;
+  shutdown_duration_ms?: number | null;
+  // Allow overriding auto-gathered system info if needed
+  memory_usage_bytes?: number | null;
+  peak_memory_usage_bytes?: number | null;
+  cpu_time_ms?: number | null;
+  active_requests_count?: number | null;
+}