@zapier/zapier-sdk 0.13.3 → 0.13.4

package/dist/types/telemetry-events.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Event emission types matching Avro schemas for SDK telemetry
+ *
+ * These interfaces correspond to the Avro schemas:
+ * - application_lifecycle_event.avsc
+ * - error_occurred_event.avsc
+ */
+export interface BaseEvent {
+    event_id: string;
+    timestamp_ms: number;
+    release_id: string;
+    customuser_id?: number | null;
+    account_id?: number | null;
+    identity_id?: number | null;
+    visitor_id?: string | null;
+    correlation_id?: string | null;
+}
+export interface ErrorOccurredEvent extends BaseEvent {
+    zap_id?: number | null;
+    node_id?: number | null;
+    selected_api?: string | null;
+    app_id?: number | null;
+    app_version_id?: number | null;
+    error_message: string;
+    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_user_facing: boolean;
+    is_recoverable?: boolean | null;
+    sdk_version?: string | 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;
+    environment?: string | null;
+    execution_time_before_error_ms?: number | null;
+}
+export interface ApplicationLifecycleEvent extends BaseEvent {
+    lifecycle_event_type: "startup" | "exit" | "signal_termination";
+    selected_api?: string | null;
+    app_id?: number | null;
+    app_version_id?: number | null;
+    sdk_version?: string | null;
+    cli_version?: string | null;
+    exit_code?: number | null;
+    signal_name?: string | null;
+    uptime_ms?: number | null;
+    memory_usage_bytes?: number | null;
+    peak_memory_usage_bytes?: number | null;
+    cpu_time_ms?: number | null;
+    os_platform?: string | null;
+    os_release?: string | null;
+    os_architecture?: string | null;
+    platform_versions?: Record<string, string | null> | null;
+    environment?: string | null;
+    is_ci_environment?: boolean | null;
+    ci_platform?: string | null;
+    session_id?: string | null;
+    metadata?: Record<string, string | null> | null;
+    process_argv?: (string | null)[] | null;
+    is_graceful_shutdown?: boolean | null;
+    shutdown_duration_ms?: number | null;
+    active_requests_count?: number | null;
+}
+export type TelemetryEvent = ErrorOccurredEvent | ApplicationLifecycleEvent;
+export type TelemetryEventType = "error_occurred" | "application_lifecycle";
+//# sourceMappingURL=telemetry-events.d.ts.map

package/dist/types/telemetry-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-events.d.ts","sourceRoot":"","sources":["../../src/types/telemetry-events.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAGD,MAAM,WAAW,kBAAmB,SAAQ,SAAS;IACnD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACtD,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kBAAkB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mBAAmB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,8BAA8B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChD;AAGD,MAAM,WAAW,yBAA0B,SAAQ,SAAS;IAC1D,oBAAoB,EAAE,SAAS,GAAG,MAAM,GAAG,oBAAoB,CAAC;IAChE,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACzD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,iBAAiB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAChD,YAAY,CAAC,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;IACxC,oBAAoB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAGD,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAAG,yBAAyB,CAAC;AAG5E,MAAM,MAAM,kBAAkB,GAAG,gBAAgB,GAAG,uBAAuB,CAAC"}

package/dist/types/telemetry-events.js

@@ -0,0 +1,8 @@
+/**
+ * Event emission types matching Avro schemas for SDK telemetry
+ *
+ * These interfaces correspond to the Avro schemas:
+ * - application_lifecycle_event.avsc
+ * - error_occurred_event.avsc
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/zapier-sdk",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "description": "Complete Zapier SDK - combines all Zapier SDK packages",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

package/src/constants.ts

@@ -8,3 +8,9 @@
  * Maximum number of items that can be requested per page across all paginated functions
  */
 export const MAX_PAGE_LIMIT = 10000;
+
+/**
+ * Default telemetry endpoint for the Tracking API
+ */
+export const TRACKING_API_ENDPOINT =
+  "https://zapier.com/api/v4/tracking/event/";

package/src/index.ts

@@ -85,3 +85,27 @@ export { registryPlugin } from "./plugins/registry";
 
 // Export ZapierSdk from sdk.ts (it's now ReturnType<typeof createZapierSdk>)
 export type { ZapierSdk } from "./types/sdk";
+
+// Export event types and utilities for external packages
+export type { BaseEvent } from "./types/telemetry-events";
+export type {
+  EventEmissionContext,
+  EventContext,
+  ApplicationLifecycleEventData,
+  EnhancedErrorEventData,
+} from "./plugins/eventEmission";
+export {
+  generateEventId,
+  getCurrentTimestamp,
+  getReleaseId,
+  getOsInfo,
+  getPlatformVersions,
+  isCi,
+  getCiPlatform,
+  getMemoryUsage,
+  getCpuTime,
+  buildApplicationLifecycleEvent,
+  buildErrorEventWithContext,
+  buildErrorEvent,
+  createBaseEvent,
+} from "./plugins/eventEmission";

package/src/plugins/api/index.ts

@@ -13,11 +13,7 @@ export interface ApiPluginProvides {
 }
 
 // API plugin requires no context and provides api in context
-export const apiPlugin: Plugin<
-  {}, // no SDK dependencies
-  {}, // requires no context
-  ApiPluginProvides
-> = (params) => {
+export const apiPlugin: Plugin<{}, {}, ApiPluginProvides> = (params) => {
   // Extract all options - everything passed to the plugin
   const {
     fetch: customFetch = globalThis.fetch,

package/src/plugins/eventEmission/builders.ts

@@ -0,0 +1,115 @@
+/**
+ * Event builder utilities for creating telemetry events
+ *
+ * Provides builder functions that auto-populate common fields and ensure
+ * schema compliance for all event types.
+ */
+
+import type {
+  ErrorOccurredEvent,
+  ApplicationLifecycleEvent,
+  BaseEvent,
+} from "../../types/telemetry-events";
+import type {
+  ApplicationLifecycleEventData,
+  EnhancedErrorEventData,
+  ErrorEventData,
+  EventContext,
+} from "./types";
+import {
+  generateEventId,
+  getCurrentTimestamp,
+  getReleaseId,
+  getOsInfo,
+  getPlatformVersions,
+  getMemoryUsage,
+  getCpuTime,
+  isCi,
+  getCiPlatform,
+} from "./utils";
+import sdkPackageJson from "../../../package.json";
+
+// Create base event with auto-populated common fields
+// Kept for backward compatibility but can be replaced with direct construction
+export function createBaseEvent(context: EventContext = {}): BaseEvent {
+  return {
+    event_id: generateEventId(),
+    timestamp_ms: getCurrentTimestamp(),
+    release_id: getReleaseId(),
+    customuser_id: context.customuser_id,
+    account_id: context.account_id,
+    identity_id: context.identity_id,
+    visitor_id: context.visitor_id,
+    correlation_id: context.correlation_id,
+  };
+}
+
+export function buildErrorEvent(
+  data: ErrorEventData,
+  context: EventContext = {},
+): ErrorOccurredEvent {
+  return {
+    ...createBaseEvent(context),
+    zap_id: context.zap_id,
+    node_id: context.node_id,
+    selected_api: context.selected_api,
+    app_id: context.app_id,
+    app_version_id: context.app_version_id,
+    environment: context.environment,
+    sdk_version: sdkPackageJson.version,
+    ...data,
+  };
+}
+
+export function buildApplicationLifecycleEvent(
+  data: ApplicationLifecycleEventData,
+  context: EventContext = {},
+): ApplicationLifecycleEvent {
+  const osInfo = getOsInfo();
+  const platformVersions = getPlatformVersions();
+
+  return {
+    ...createBaseEvent(context),
+    selected_api: context.selected_api,
+    app_id: context.app_id,
+    app_version_id: context.app_version_id,
+    sdk_version: sdkPackageJson.version,
+    cli_version: null,
+    memory_usage_bytes: data.memory_usage_bytes ?? getMemoryUsage(),
+    peak_memory_usage_bytes: data.peak_memory_usage_bytes ?? getMemoryUsage(),
+    cpu_time_ms: data.cpu_time_ms ?? getCpuTime(),
+    os_platform: osInfo.platform,
+    os_release: osInfo.release,
+    os_architecture: osInfo.architecture,
+    platform_versions: platformVersions,
+    environment: context.environment ?? (process.env.NODE_ENV || null),
+    is_ci_environment: isCi(),
+    ci_platform: getCiPlatform(),
+    session_id: null,
+    metadata: null,
+    process_argv: process.argv || null,
+    ...data,
+  };
+}
+
+export function buildErrorEventWithContext(
+  data: EnhancedErrorEventData,
+  context: EventContext = {},
+): ErrorOccurredEvent {
+  const executionTime = data.execution_start_time
+    ? Date.now() - data.execution_start_time
+    : null;
+
+  return {
+    ...createBaseEvent(context),
+    zap_id: context.zap_id,
+    node_id: context.node_id,
+    selected_api: context.selected_api,
+    app_id: context.app_id,
+    app_version_id: context.app_version_id,
+    environment: context.environment ?? (process.env.NODE_ENV || null),
+    sdk_version: sdkPackageJson.version,
+    execution_time_before_error_ms: executionTime,
+    ...data,
+  };
+}

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

@@ -0,0 +1,169 @@
+/**
+ * Tests for Event Emission Plugin
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { eventEmissionPlugin } from "./index";
+import { createTransport } from "./transport";
+import type { EventEmissionConfig } from "./index";
+
+// Mock transport for testing
+const mockTransport = {
+  emit: vi.fn().mockResolvedValue(undefined),
+  close: vi.fn().mockResolvedValue(undefined),
+};
+
+vi.mock("./transport", () => ({
+  createTransport: vi.fn(() => mockTransport),
+}));
+
+describe("eventEmissionPlugin", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should create plugin with default configuration", () => {
+    const plugin = eventEmissionPlugin({
+      sdk: {},
+      context: {
+        meta: {},
+        options: {},
+      },
+    });
+
+    expect(plugin.context.eventEmission).toBeDefined();
+    expect(plugin.context.eventEmission.emit).toBeDefined();
+    expect(plugin.context.eventEmission.transport).toBeDefined();
+    expect(plugin.context.eventEmission.config).toBeDefined();
+  });
+
+  it("should create noop implementations when disabled", () => {
+    const config: EventEmissionConfig = { enabled: false };
+    const plugin = eventEmissionPlugin({
+      sdk: {},
+      context: {
+        meta: {},
+        options: { eventEmission: config },
+      },
+    });
+
+    // Should not emit any events when disabled
+    plugin.context.eventEmission.emit("platform.sdk.TestEvent", {
+      test_event: "data",
+    });
+
+    expect(mockTransport.emit).not.toHaveBeenCalled();
+  });
+
+  it("should emit events using generic emit method", async () => {
+    const plugin = eventEmissionPlugin({
+      sdk: {},
+      context: {
+        meta: {},
+        options: {
+          eventEmission: {
+            enabled: true,
+            transport: { type: "console" as const },
+          },
+        },
+      },
+    });
+
+    const testEvent = {
+      test_data: "example",
+      value: 123,
+    };
+
+    const testSubject = "test.event.TestEvent";
+
+    plugin.context.eventEmission.emit(testSubject, testEvent);
+
+    // Give async emission time to complete
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(mockTransport.emit).toHaveBeenCalledWith(testSubject, testEvent);
+  });
+
+  it("should handle transport creation failures silently", () => {
+    // Mock createTransport to throw an error
+    vi.mocked(createTransport).mockImplementationOnce(() => {
+      throw new Error("Transport creation failed");
+    });
+
+    expect(() => {
+      eventEmissionPlugin({
+        sdk: {},
+        context: {
+          meta: {},
+          options: {
+            eventEmission: {
+              enabled: true,
+              transport: { type: "http" as const, endpoint: "invalid-url" },
+            },
+          },
+        },
+      });
+    }).not.toThrow();
+  });
+
+  it("should handle event emission failures silently", async () => {
+    // Mock transport to throw error
+    const failingTransport = {
+      emit: vi.fn().mockRejectedValue(new Error("Network error")),
+      close: vi.fn().mockResolvedValue(undefined),
+    };
+
+    vi.mocked(createTransport).mockReturnValueOnce(failingTransport);
+
+    const plugin = eventEmissionPlugin({
+      sdk: {},
+      context: {
+        meta: {},
+        options: {
+          eventEmission: {
+            enabled: true,
+            transport: {
+              type: "http" as const,
+              endpoint: "https://example.com",
+            },
+          },
+        },
+      },
+    });
+
+    // Should not throw even if transport fails
+    expect(() => {
+      plugin.context.eventEmission.emit("test.event.TestEvent", {
+        test_event: "data",
+      });
+    }).not.toThrow();
+
+    // Give async emission time to complete
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(failingTransport.emit).toHaveBeenCalled();
+  });
+
+  it("should merge options with defaults", () => {
+    const plugin = eventEmissionPlugin({
+      sdk: {},
+      context: {
+        meta: {},
+        options: {
+          eventEmission: {
+            transport: {
+              type: "http" as const,
+              endpoint: "https://example.com",
+            },
+          },
+        },
+      },
+    });
+
+    expect(plugin.context.eventEmission.config.enabled).toBe(true);
+    expect(plugin.context.eventEmission.config.transport).toEqual({
+      type: "http",
+      endpoint: "https://example.com",
+    });
+  });
+});