@zapier/zapier-sdk 0.4.1 → 0.5.1

package/dist/api/client.js

@@ -0,0 +1,322 @@
+/**
+ * API Client Implementation
+ *
+ * This module contains the core API client implementation, including
+ * HTTP method handlers, response processing, and client factory functions.
+ */
+import { getAuthorizationHeader } from "./auth";
+import { createDebugLogger, createDebugFetch } from "./debug";
+import { pollUntilComplete } from "./polling";
+import { getTokenFromEnvOrConfig } from "../auth";
+import { ZapierApiError, ZapierAuthenticationError, ZapierValidationError, ZapierNotFoundError, } from "../types/errors";
+const SubdomainConfigMap = {
+    // e.g. https://relay.zapier.com
+    relay: {
+        authHeader: "X-Relay-Authorization",
+    },
+};
+class ZapierApiClient {
+    constructor(options) {
+        this.options = options;
+        this.fetch = async (path, init) => {
+            return this.plainFetch(path, init);
+        };
+        this.get = async (path, options = {}) => {
+            return this.fetchJson("GET", path, undefined, options);
+        };
+        this.post = async (path, data, options = {}) => {
+            return this.fetchJson("POST", path, data, options);
+        };
+        this.put = async (path, data, options = {}) => {
+            return this.fetchJson("PUT", path, data, options);
+        };
+        this.delete = async (path, options = {}) => {
+            return this.fetchJson("DELETE", path, undefined, options);
+        };
+        this.poll = async (path, options = {}) => {
+            return pollUntilComplete({
+                fetchPoll: () => this.plainFetch(path, {
+                    method: "GET",
+                    searchParams: options.searchParams,
+                    authRequired: options.authRequired,
+                }),
+                maxAttempts: options.maxAttempts,
+                initialDelay: options.initialDelay,
+                maxDelay: options.maxDelay,
+                successStatus: options.successStatus,
+                pendingStatus: options.pendingStatus,
+                resultExtractor: options.resultExtractor,
+            });
+        };
+    }
+    // Helper to parse response data
+    async parseResult(response) {
+        try {
+            return { type: "json", data: await response.json() };
+        }
+        catch {
+            return { type: "text", data: await response.text() };
+        }
+    }
+    // Helper to get a token from the different places it could be gotten
+    async getAuthToken() {
+        if (this.options.token) {
+            return this.options.token;
+        }
+        if (this.options.getToken) {
+            const token = await this.options.getToken();
+            if (token) {
+                return token;
+            }
+        }
+        return getTokenFromEnvOrConfig({
+            onEvent: this.options.onEvent,
+            fetch: this.options.fetch,
+        });
+    }
+    // Helper to handle responses
+    async handleResponse(params) {
+        const { response, customErrorHandler, wasMissingAuthToken } = params;
+        const { data: responseData } = await this.parseResult(response);
+        if (response.ok) {
+            return responseData;
+        }
+        const errorInfo = {
+            status: response.status,
+            statusText: response.statusText,
+            data: responseData,
+        };
+        // Check for custom error handling first
+        if (customErrorHandler) {
+            const customError = customErrorHandler(errorInfo);
+            if (customError) {
+                // javascript may not respect customErrorHandler return type, so we need to throw a proper error if it's not an Error
+                if (customError instanceof Error) {
+                    throw customError;
+                }
+                else {
+                    throw new Error(`customErrorHandler returned a non-Error: ${JSON.stringify(customError)}`);
+                }
+            }
+        }
+        // Parse the error response
+        const { message, errors } = this.parseErrorResponse(errorInfo);
+        const errorOptions = {
+            statusCode: response.status,
+            errors,
+        };
+        // Use appropriate error type based on status code
+        if (response.status === 404) {
+            throw new ZapierNotFoundError(message, errorOptions);
+        }
+        if (response.status === 401 || response.status === 403) {
+            // If we get a 401/403 error and no auth token was provided, give helpful message
+            if (wasMissingAuthToken) {
+                throw new ZapierAuthenticationError(`Authentication required (HTTP ${response.status}). Please provide a token in options or set ZAPIER_TOKEN environment variable.`, errorOptions);
+            }
+            throw new ZapierAuthenticationError(message, errorOptions);
+        }
+        if (response.status === 400) {
+            throw new ZapierValidationError(message, errorOptions);
+        }
+        // Generic API error for other status codes
+        throw new ZapierApiError(message, errorOptions);
+    }
+    hasErrorArray(data) {
+        return (typeof data === "object" &&
+            data !== null &&
+            "errors" in data &&
+            Array.isArray(data.errors));
+    }
+    // Helper to check if data has API errors
+    isApiErrorArray(dataArray) {
+        const data = dataArray[0];
+        return (typeof data === "object" &&
+            data !== null &&
+            "message" in data &&
+            "code" in data &&
+            "title" in data &&
+            "detail" in data);
+    }
+    // Do our best to extract an error message from the response data
+    extractErrorMessage(data) {
+        if (typeof data === "string") {
+            return data;
+        }
+        if (typeof data === "object" && data !== null) {
+            if ("message" in data && typeof data.message === "string") {
+                return data.message;
+            }
+            if ("error" in data) {
+                if (typeof data.error === "string") {
+                    return data.error;
+                }
+                if (typeof data.error === "object" && data.error !== null) {
+                    if ("message" in data.error &&
+                        typeof data.error.message === "string") {
+                        return data.error.message;
+                    }
+                }
+                try {
+                    return JSON.stringify(data.error);
+                }
+                catch {
+                    /* defend against circular objects, even though they shouldn't be coming back from the wire */
+                }
+            }
+            if ("errors" in data && Array.isArray(data.errors)) {
+                if (this.isApiErrorArray(data.errors)) {
+                    return data.errors[0].detail || data.errors[0].title;
+                }
+            }
+        }
+        return undefined;
+    }
+    // Helper to parse API error response
+    parseErrorResponse(errorInfo) {
+        // If we can't parse data, use status text
+        const fallbackMessage = `HTTP ${errorInfo.status}: ${errorInfo.statusText}`;
+        try {
+            // Check if the response has the standard error format
+            if (typeof errorInfo.data === "string") {
+                return { message: `${fallbackMessage}: ${errorInfo.data}` };
+            }
+            const errorMessage = this.extractErrorMessage(errorInfo.data) || fallbackMessage;
+            if (this.hasErrorArray(errorInfo.data)) {
+                if (this.isApiErrorArray(errorInfo.data.errors)) {
+                    return {
+                        message: errorMessage,
+                        errors: errorInfo.data.errors,
+                    };
+                }
+                else {
+                    return {
+                        message: errorMessage,
+                        errors: errorInfo.data.errors.map((e) => ({
+                            status: errorInfo.status,
+                            code: String(errorInfo.status),
+                            title: errorInfo.statusText,
+                            detail: JSON.stringify(e),
+                        })),
+                    };
+                }
+            }
+            return { message: errorMessage };
+        }
+        catch {
+            return { message: fallbackMessage };
+        }
+    }
+    // Check if this is a path that needs subdomain routing
+    // e.g. /relay/workflows -> relay.zapier.com/workflows
+    applySubdomainBehavior(path) {
+        const pathSegments = path.split("/").filter(Boolean);
+        if (pathSegments.length > 0 && pathSegments[0] in SubdomainConfigMap) {
+            // Transform paths to use subdomain routing
+            // /prefix/domain/path -> prefix.zapier.com/domain/path
+            const domainPrefix = pathSegments[0];
+            const subdomainConfig = SubdomainConfigMap[domainPrefix];
+            const originalBaseUrl = new URL(this.options.baseUrl);
+            const finalBaseUrl = `https://${domainPrefix}.${originalBaseUrl.hostname}`;
+            const pathWithoutPrefix = "/" + pathSegments.slice(1).join("/");
+            return { url: new URL(pathWithoutPrefix, finalBaseUrl), subdomainConfig };
+        }
+        return {
+            url: new URL(path, this.options.baseUrl),
+            subdomainConfig: undefined,
+        };
+    }
+    // Helper to build full URLs and return routing info
+    buildUrl(path, searchParams) {
+        const { url, subdomainConfig } = this.applySubdomainBehavior(path);
+        if (searchParams) {
+            Object.entries(searchParams).forEach(([key, value]) => {
+                url.searchParams.set(key, value);
+            });
+        }
+        return { url: url.toString(), subdomainConfig };
+    }
+    // Helper to build headers
+    async buildHeaders(options = {}, subdomainConfig) {
+        const headers = new Headers(options.headers ?? {});
+        // Even if auth is not required, we still want to add it in case it adds
+        // useful context to the API. The session is a good example of this. Auth
+        // is not required, but if we don't add auth, then we won't get the user's
+        // session!
+        const authToken = await this.getAuthToken();
+        if (authToken) {
+            const authHeaderName = subdomainConfig?.authHeader || "Authorization";
+            headers.set(authHeaderName, getAuthorizationHeader(authToken));
+        }
+        // If we know auth is required, and we don't have a token, throw an error
+        // before we even make a request.
+        if (options.authRequired) {
+            if (headers.get("Authorization") == null && authToken == null) {
+                throw new ZapierAuthenticationError(`Authentication required but no token available. Please set ZAPIER_TOKEN, or run the 'login' command with the CLI.`);
+            }
+        }
+        return headers;
+    }
+    // Helper to perform HTTP requests with JSON handling
+    async fetchJson(method, path, data, options = {}) {
+        const headers = { ...options.headers };
+        // Add Content-Type for JSON requests with body data
+        if (data && typeof data === "object") {
+            headers["Content-Type"] = "application/json";
+        }
+        // Check if we have an auth token available
+        const wasMissingAuthToken = options.authRequired && (await this.getAuthToken()) == null;
+        const response = await this.plainFetch(path, {
+            ...options,
+            method,
+            body: data != null ? JSON.stringify(data) : undefined,
+            headers,
+        });
+        // plainFetch already handled all auth and headers
+        const result = await this.handleResponse({
+            response,
+            customErrorHandler: options.customErrorHandler,
+            wasMissingAuthToken,
+        });
+        if (typeof result === "string") {
+            throw new ZapierValidationError(`Response could not be parsed as JSON: ${result}`);
+        }
+        return result;
+    }
+    // Plain fetch method for API paths (must start with /)
+    async plainFetch(path, fetchOptions) {
+        if (!path.startsWith("/")) {
+            throw new ZapierValidationError(`plainFetch expects a path starting with '/', got: ${path}`);
+        }
+        if (fetchOptions?.body && typeof fetchOptions.body === "object") {
+            fetchOptions.body = JSON.stringify(fetchOptions.body);
+        }
+        const { url, subdomainConfig } = this.buildUrl(path, fetchOptions?.searchParams);
+        const builtHeaders = await this.buildHeaders(fetchOptions, subdomainConfig);
+        const inputHeaders = new Headers(fetchOptions?.headers ?? {});
+        const mergedHeaders = new Headers();
+        builtHeaders.forEach((value, key) => {
+            mergedHeaders.set(key, value);
+        });
+        inputHeaders.forEach((value, key) => {
+            mergedHeaders.set(key, value);
+        });
+        return await this.options.fetch(url, {
+            ...fetchOptions,
+            headers: mergedHeaders,
+        });
+    }
+}
+export const createZapierApi = (options) => {
+    const { baseUrl, token, getToken, debug = false, fetch: originalFetch = globalThis.fetch, onEvent, } = options;
+    const debugLog = createDebugLogger(debug);
+    const debugFetch = createDebugFetch({ originalFetch, debugLog });
+    return new ZapierApiClient({
+        baseUrl,
+        token,
+        getToken,
+        debug,
+        fetch: debugFetch,
+        onEvent,
+    });
+};

package/dist/api/debug.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Debug Logging Utilities
+ *
+ * This module provides debug logging capabilities for API requests and responses,
+ * including request timing and detailed logging of HTTP interactions.
+ */
+import type { DebugLogger } from "./types";
+export declare function createDebugLogger(enabled: boolean): DebugLogger;
+export declare function createDebugFetch(options: {
+    originalFetch: typeof globalThis.fetch;
+    debugLog: DebugLogger;
+}): (input: RequestInfo | URL, options?: RequestInit) => Promise<Response>;
+//# sourceMappingURL=debug.d.ts.map

package/dist/api/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/api/debug.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAQ/D;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,aAAa,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACvC,QAAQ,EAAE,WAAW,CAAC;CACvB,IAEe,OAAO,WAAW,GAAG,GAAG,EAAE,UAAU,WAAW,uBA0C9D"}

package/dist/api/debug.js

@@ -0,0 +1,55 @@
+/**
+ * Debug Logging Utilities
+ *
+ * This module provides debug logging capabilities for API requests and responses,
+ * including request timing and detailed logging of HTTP interactions.
+ */
+export function createDebugLogger(enabled) {
+    if (!enabled) {
+        return () => { }; // No-op function when debug is disabled
+    }
+    return (message, data) => {
+        console.log(`[Zapier SDK] ${message}`, data || "");
+    };
+}
+export function createDebugFetch(options) {
+    const { originalFetch, debugLog } = options;
+    return async (input, options) => {
+        const startTime = Date.now();
+        // Convert input to URL string for logging
+        const url = typeof input === "string" ? input : input.toString();
+        const method = options?.method || "GET";
+        debugLog(`→ ${method} ${url}`, {
+            headers: options?.headers,
+            body: options?.body && typeof options.body === "string"
+                ? (() => {
+                    try {
+                        return JSON.parse(options.body);
+                    }
+                    catch {
+                        return options.body;
+                    }
+                })()
+                : options?.body,
+        });
+        try {
+            const response = await originalFetch(input, options);
+            const duration = Date.now() - startTime;
+            debugLog(`← ${response.status} ${response.statusText} (${duration}ms)`, {
+                url,
+                method,
+                status: response.status,
+            });
+            return response;
+        }
+        catch (error) {
+            const duration = Date.now() - startTime;
+            debugLog(`✖ Request failed (${duration}ms)`, {
+                url,
+                method,
+                error: error instanceof Error ? error.message : error,
+            });
+            throw error;
+        }
+    };
+}

package/dist/api/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Zapier API Client Module
+ *
+ * This module provides a centralized API layer for all HTTP interactions
+ * with Zapier's various APIs. It handles authentication, error handling,
+ * polling, and provides consistent patterns across all services.
+ */
+export type { ApiClient, ApiClientOptions, RequestOptions, PollOptions, DebugLogger, Action, Field, Choice, ActionExecutionResult, ActionField, ActionFieldChoice, NeedsRequest, NeedsResponse, Authentication, AuthenticationsResponse, } from "./types";
+import type { ApiClient } from "./types";
+export { isJwt, getAuthorizationHeader } from "./auth";
+export { createDebugLogger, createDebugFetch } from "./debug";
+export { pollUntilComplete } from "./polling";
+export { createZapierApi } from "./client";
+export declare function generateRequestId(): string;
+/**
+ * Utility function to get or create an API client for standalone functions
+ *
+ * @param config - Configuration that may include an existing API client
+ * @returns ApiClient instance
+ */
+export declare function getOrCreateApiClient(config: {
+    baseUrl?: string;
+    token?: string;
+    getToken?: () => Promise<string | undefined>;
+    api?: ApiClient;
+    debug?: boolean;
+    fetch?: typeof globalThis.fetch;
+}): ApiClient;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAEV,SAAS,EACT,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,WAAW,EAEX,MAAM,EACN,KAAK,EACL,MAAM,EACN,qBAAqB,EACrB,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,uBAAuB,GACxB,MAAM,SAAS,CAAC;AAGjB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAGzC,OAAO,EAAE,KAAK,EAAE,sBAAsB,EAAE,MAAM,QAAQ,CAAC;AAGvD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAG9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAM3C,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,GAAG,CAAC,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC,GAAG,SAAS,CAsBZ"}

package/dist/api/index.js

@@ -0,0 +1,41 @@
+/**
+ * Zapier API Client Module
+ *
+ * This module provides a centralized API layer for all HTTP interactions
+ * with Zapier's various APIs. It handles authentication, error handling,
+ * polling, and provides consistent patterns across all services.
+ */
+// Re-export authentication utilities
+export { isJwt, getAuthorizationHeader } from "./auth";
+// Re-export debug utilities
+export { createDebugLogger, createDebugFetch } from "./debug";
+// Re-export polling utilities
+export { pollUntilComplete } from "./polling";
+// Re-export the main client factory
+export { createZapierApi } from "./client";
+// Import for local use
+import { createZapierApi } from "./client";
+// Utility Functions
+export function generateRequestId() {
+    return Math.random().toString(36).substring(2) + Date.now().toString(36);
+}
+/**
+ * Utility function to get or create an API client for standalone functions
+ *
+ * @param config - Configuration that may include an existing API client
+ * @returns ApiClient instance
+ */
+export function getOrCreateApiClient(config) {
+    const { baseUrl = "https://zapier.com", token, getToken, api: providedApi, debug = false, fetch: customFetch, } = config;
+    // Use provided API client or create a new one
+    if (providedApi) {
+        return providedApi;
+    }
+    return createZapierApi({
+        baseUrl,
+        token,
+        getToken,
+        debug,
+        fetch: customFetch,
+    });
+}

package/dist/api/polling.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Polling Utilities
+ *
+ * This module provides utilities for polling HTTP endpoints until completion,
+ * with configurable retry logic and exponential backoff.
+ */
+export declare function pollUntilComplete(options: {
+    fetchPoll: () => Promise<Response>;
+    maxAttempts?: number;
+    initialDelay?: number;
+    maxDelay?: number;
+    successStatus?: number;
+    pendingStatus?: number;
+    resultExtractor?: (response: any) => any;
+}): Promise<any>;
+//# sourceMappingURL=polling.d.ts.map

package/dist/api/polling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling.d.ts","sourceRoot":"","sources":["../../src/api/polling.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,SAAS,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,GAAG,CAAC;CAC1C,GAAG,OAAO,CAAC,GAAG,CAAC,CAuDf"}

package/dist/api/polling.js

@@ -0,0 +1,45 @@
+/**
+ * Polling Utilities
+ *
+ * This module provides utilities for polling HTTP endpoints until completion,
+ * with configurable retry logic and exponential backoff.
+ */
+import { ZapierTimeoutError, ZapierApiError } from "../types/errors";
+export async function pollUntilComplete(options) {
+    const { fetchPoll, maxAttempts = 30, initialDelay = 50, maxDelay = 1000, successStatus = 200, pendingStatus = 202, resultExtractor = (response) => response, } = options;
+    let delay = initialDelay;
+    let errorCount = 0;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const response = await fetchPoll();
+        if (response.status === successStatus) {
+            // Success - reset error count and return results
+            errorCount = 0;
+            const result = await response.json();
+            return resultExtractor(result);
+        }
+        else if (response.status === pendingStatus) {
+            // Still processing - reset error count and wait and retry
+            errorCount = 0;
+            if (attempt < maxAttempts - 1) {
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                delay = Math.min(delay * 2, maxDelay); // Exponential backoff
+                continue;
+            }
+        }
+        else {
+            // Error occurred - increment error count
+            errorCount++;
+            if (errorCount >= 3) {
+                // Too many consecutive errors, fail
+                throw new ZapierApiError(`Poll request failed: ${response.status} ${response.statusText}`, { statusCode: response.status });
+            }
+            // Treat as pending for up to 3 errors - wait and retry
+            if (attempt < maxAttempts - 1) {
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                delay = Math.min(delay * 2, maxDelay); // Exponential backoff
+                continue;
+            }
+        }
+    }
+    throw new ZapierTimeoutError(`Operation timed out after ${maxAttempts} attempts`, { attempts: maxAttempts, maxAttempts: maxAttempts });
+}