@zapier/zapier-sdk 0.18.3 → 0.19.0

package/dist/api/client.integration.test.js

@@ -1,318 +0,0 @@
-/**
- * Integration tests for API client handler override mechanism
- */
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { createZapierApi } from "./client";
-describe("Handler Override Mechanism Integration", () => {
-    let mockFetch;
-    beforeEach(() => {
-        mockFetch = vi.fn();
-    });
-    describe("listApps handler override", () => {
-        it("should invoke handler instead of making HTTP request to /api/v0/apps", async () => {
-            // Mock the nested API call that the handler makes
-            mockFetch.mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({
-                    results: [
-                        {
-                            api: "slack",
-                            name: "Slack",
-                            id: "SlackAPI@1.0.0",
-                            logo_url: "https://example.com/slack.png",
-                            categories: ["communication"],
-                        },
-                    ],
-                    next: null,
-                }),
-            });
-            const api = createZapierApi({
-                fetch: mockFetch,
-                token: "test-token",
-                baseUrl: "https://api.zapier.com",
-            });
-            // Call the path with handler override
-            const result = await api.get("/api/v0/apps", {
-                searchParams: { implementationIds: "SlackAPI@1.0.0" },
-            });
-            // Assert: No direct call to /api/v0/apps (handler intercepted it)
-            const fetchCalls = mockFetch.mock.calls;
-            const appsEndpointCalls = fetchCalls.filter((call) => typeof call[0] === "string" && call[0].includes("/api/v0/apps"));
-            expect(appsEndpointCalls).toHaveLength(0);
-            // Assert: Handler made nested call to lookup endpoint
-            const lookupCalls = fetchCalls.filter((call) => typeof call[0] === "string" &&
-                call[0].includes("/zapier/api/v4/implementations-meta/lookup/"));
-            expect(lookupCalls.length).toBeGreaterThan(0);
-            // Assert: Result has correct structure from handler
-            expect(result).toHaveProperty("data");
-            expect(result).toHaveProperty("nextCursor");
-            expect(Array.isArray(result.data)).toBe(true);
-            expect(result.data).toHaveLength(1);
-            expect(result.data[0]).toMatchObject({
-                key: "SlackAPI",
-                title: "Slack",
-                implementation_id: "SlackAPI@1.0.0",
-            });
-        });
-        it("should pass httpClient to handler for nested API calls", async () => {
-            // Mock response for the nested lookup call
-            mockFetch.mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({
-                    results: [
-                        {
-                            api: "github",
-                            name: "GitHub",
-                            id: "GitHubAPI@2.1.0",
-                            logo_url: "https://example.com/github.png",
-                            categories: ["developer-tools"],
-                        },
-                    ],
-                    next: null,
-                }),
-            });
-            const api = createZapierApi({
-                fetch: mockFetch,
-                token: "test-token",
-                baseUrl: "https://api.zapier.com",
-            });
-            // Request with multiple implementation IDs
-            await api.get("/api/v0/apps", {
-                searchParams: {
-                    implementationIds: "GitHubAPI@2.1.0,SlackAPI@1.0.0",
-                },
-            });
-            // Verify that nested API call was made
-            expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining("/zapier/api/v4/implementations-meta/lookup/"), expect.any(Object));
-            // Verify the request includes proper configuration
-            const fetchCall = mockFetch.mock.calls[0];
-            expect(fetchCall[0]).toContain("selected_apis=GitHubAPI%402.1.0%2CSlackAPI%401.0.0");
-            expect(fetchCall[1]).toHaveProperty("method", "GET");
-        });
-        it("should handle search augmentation through handler", async () => {
-            // Mock search endpoint response
-            mockFetch
-                .mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({
-                    results: [
-                        {
-                            api: "gmail",
-                            name: "Gmail",
-                            id: "GmailAPI@1.5.0",
-                            logo_url: "https://example.com/gmail.png",
-                            categories: ["email"],
-                        },
-                    ],
-                    next: null,
-                }),
-            })
-                // Mock lookup endpoint response
-                .mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({
-                    results: [
-                        {
-                            api: "slack",
-                            name: "Slack",
-                            id: "SlackAPI@1.0.0",
-                            logo_url: "https://example.com/slack.png",
-                            categories: ["communication"],
-                        },
-                        {
-                            api: "gmail",
-                            name: "Gmail",
-                            id: "GmailAPI@1.5.0",
-                            logo_url: "https://example.com/gmail.png",
-                            categories: ["email"],
-                        },
-                    ],
-                    next: null,
-                }),
-            });
-            const api = createZapierApi({
-                fetch: mockFetch,
-                token: "test-token",
-                baseUrl: "https://api.zapier.com",
-            });
-            // Request with search term and specific implementation
-            const result = await api.get("/api/v0/apps", {
-                searchParams: {
-                    implementationIds: "SlackAPI@1.0.0",
-                    search: "email",
-                },
-            });
-            // Verify search endpoint was called
-            const searchCalls = mockFetch.mock.calls.filter((call) => typeof call[0] === "string" &&
-                call[0].includes("/zapier/api/v4/implementations-meta/search/"));
-            expect(searchCalls.length).toBeGreaterThan(0);
-            // Verify lookup endpoint was called with augmented IDs
-            const lookupCalls = mockFetch.mock.calls.filter((call) => typeof call[0] === "string" &&
-                call[0].includes("/zapier/api/v4/implementations-meta/lookup/"));
-            expect(lookupCalls.length).toBeGreaterThan(0);
-            // Verify result contains both original and search results
-            expect(result.data).toHaveLength(2);
-        });
-        it("should handle pagination through handler", async () => {
-            // Mock first page response
-            mockFetch.mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({
-                    results: [
-                        {
-                            api: "app1",
-                            name: "App 1",
-                            id: "App1API@1.0.0",
-                            logo_url: "https://example.com/app1.png",
-                            categories: ["productivity"],
-                        },
-                    ],
-                    next: "https://example.com/api?offset=20",
-                }),
-            });
-            const api = createZapierApi({
-                fetch: mockFetch,
-                token: "test-token",
-                baseUrl: "https://api.zapier.com",
-            });
-            const result = await api.get("/api/v0/apps", {
-                searchParams: { pageSize: "10" },
-            });
-            // Verify pagination cursor is extracted
-            expect(result.nextCursor).toBe("20");
-            // Mock second page response
-            mockFetch.mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({
-                    results: [
-                        {
-                            api: "app2",
-                            name: "App 2",
-                            id: "App2API@1.0.0",
-                            logo_url: "https://example.com/app2.png",
-                            categories: ["productivity"],
-                        },
-                    ],
-                    next: null,
-                }),
-            });
-            // Request second page
-            const secondPageResult = await api.get("/api/v0/apps", {
-                searchParams: { cursor: "20" },
-            });
-            expect(secondPageResult.nextCursor).toBeUndefined();
-        });
-        it("should handle errors from handler correctly", async () => {
-            // Mock an error response from nested API call
-            mockFetch.mockResolvedValueOnce({
-                ok: false,
-                status: 404,
-                statusText: "Not Found",
-                json: async () => ({
-                    errors: [
-                        {
-                            message: "Implementation not found",
-                        },
-                    ],
-                }),
-            });
-            const api = createZapierApi({
-                fetch: mockFetch,
-                token: "test-token",
-                baseUrl: "https://api.zapier.com",
-            });
-            // Request should propagate the error from handler
-            await expect(api.get("/api/v0/apps", {
-                searchParams: { implementationIds: "NonExistentAPI" },
-            })).rejects.toThrow();
-        });
-        it("should handle empty search results correctly", async () => {
-            // Mock empty search response
-            mockFetch.mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({
-                    results: [],
-                    next: null,
-                }),
-            });
-            const api = createZapierApi({
-                fetch: mockFetch,
-                token: "test-token",
-                baseUrl: "https://api.zapier.com",
-            });
-            const result = await api.get("/api/v0/apps", {
-                searchParams: {
-                    implementationIds: "",
-                    search: "nonexistentapp",
-                },
-            });
-            // Should return empty results without calling lookup endpoint
-            expect(result.data).toEqual([]);
-            expect(result.nextCursor).toBeUndefined();
-            // Verify only search endpoint was called, not lookup
-            const lookupCalls = mockFetch.mock.calls.filter((call) => typeof call[0] === "string" &&
-                call[0].includes("/zapier/api/v4/implementations-meta/lookup/"));
-            expect(lookupCalls).toHaveLength(0);
-        });
-    });
-    describe("standard path handling (non-override)", () => {
-        it("should make normal HTTP requests for paths without handler override", async () => {
-            mockFetch.mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({ result: "direct HTTP response" }),
-            });
-            const api = createZapierApi({
-                fetch: mockFetch,
-                token: "test-token",
-                baseUrl: "https://api.zapier.com",
-            });
-            // Request to a path without handler override
-            await api.get("/zapier/some-other-endpoint");
-            // Verify HTTP request was made directly
-            expect(mockFetch).toHaveBeenCalledWith(expect.stringContaining("/zapier/some-other-endpoint"), expect.any(Object));
-        });
-    });
-    describe("handler override type safety", () => {
-        it("should handle handler request transformation correctly", async () => {
-            // Mock response for lookup
-            mockFetch.mockResolvedValueOnce({
-                ok: true,
-                status: 200,
-                json: async () => ({
-                    results: [],
-                    next: null,
-                }),
-            });
-            const api = createZapierApi({
-                fetch: mockFetch,
-                token: "test-token",
-                baseUrl: "https://api.zapier.com",
-            });
-            // Test that string implementationIds are properly handled
-            const result = await api.get("/api/v0/apps", {
-                searchParams: {
-                    implementationIds: "App1,App2,App3",
-                    pageSize: "15",
-                },
-            });
-            // Verify the handler received and processed the request
-            expect(result).toHaveProperty("data");
-            expect(Array.isArray(result.data)).toBe(true);
-            // Check that lookup endpoint was called with proper params
-            const lookupCall = mockFetch.mock.calls.find((call) => typeof call[0] === "string" &&
-                call[0].includes("/zapier/api/v4/implementations-meta/lookup/"));
-            expect(lookupCall).toBeDefined();
-            // Commas are URL-encoded as %2C
-            expect(lookupCall[0]).toContain("selected_apis=App1%2CApp2%2CApp3");
-            expect(lookupCall[0]).toContain("limit=15");
-        });
-    });
-});

package/dist/api/client.js

@@ -1,374 +0,0 @@
-/**
- * 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 { resolveAuthToken } from "../auth";
-import { getZapierBaseUrl } from "../utils/url-utils";
-import { ZapierApiError, ZapierAuthenticationError, ZapierValidationError, ZapierNotFoundError, } from "../types/errors";
-import { matchRoute } from "./router";
-// Configuration for paths
-const pathConfig = {
-    // e.g. /relay -> https://sdkapi.zapier.com/api/v0/sdk/relay/...
-    "/relay": {
-        authHeader: "X-Relay-Authorization",
-        pathPrefix: "/api/v0/sdk/relay",
-    },
-    // e.g. /zapier -> https://sdkapi.zapier.com/api/v0/sdk/zapier/...
-    "/zapier": {
-        authHeader: "Authorization",
-        pathPrefix: "/api/v0/sdk/zapier",
-    },
-};
-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,
-                }),
-                initialDelay: options.initialDelay,
-                timeoutMs: options.timeoutMs,
-                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() {
-        return resolveAuthToken({
-            token: this.options.token,
-            getToken: this.options.getToken,
-            onEvent: this.options.onEvent,
-            fetch: this.options.fetch,
-            baseUrl: this.options.baseUrl,
-            authBaseUrl: this.options.authBaseUrl,
-            authClientId: this.options.authClientId,
-        });
-    }
-    // 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;
-                }
-                else if (data.errors.length > 0) {
-                    // Handle simple string errors array
-                    const firstError = data.errors[0];
-                    if (typeof firstError === "string") {
-                        return firstError;
-                    }
-                    // For non-string errors, stringify them
-                    try {
-                        return JSON.stringify(firstError);
-                    }
-                    catch {
-                        return String(firstError);
-                    }
-                }
-            }
-        }
-        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 };
-        }
-    }
-    // Apply any special routing logic for configured paths.
-    applyPathConfiguration(path) {
-        // Find matching path configuration.
-        const matchingPathKey = Object.keys(pathConfig).find((configPath) => path === configPath || path.startsWith(configPath + "/"));
-        const config = matchingPathKey ? pathConfig[matchingPathKey] : undefined;
-        // Check if baseUrl is a Zapier-inferred base URL.
-        const zapierBaseUrl = getZapierBaseUrl(this.options.baseUrl);
-        // Let's remain compatible with a base URL that is set to a Zapier-inferred
-        // domain, rather than requiring the base URL to go to our proxy. Later, the
-        // proxy will be removed, so this should make that transition easier.
-        if (zapierBaseUrl === this.options.baseUrl) {
-            // If baseUrl is already the Zapier base URL, use sdkapi subdomain.
-            const originalBaseUrl = new URL(this.options.baseUrl);
-            const finalBaseUrl = `https://sdkapi.${originalBaseUrl.hostname}`;
-            // Only prepend pathPrefix if there's a matching config with pathPrefix.
-            let finalPath = path;
-            if (config &&
-                "pathPrefix" in config &&
-                config.pathPrefix &&
-                matchingPathKey) {
-                // Strip the matching path key, and use the pathPrefix instead.
-                const pathWithoutPrefix = path.slice(matchingPathKey.length) || "/";
-                finalPath = `${config.pathPrefix}${pathWithoutPrefix}`;
-            }
-            return {
-                url: new URL(finalPath, finalBaseUrl),
-                pathConfig: config,
-            };
-        }
-        // For a base URL that isn't a Zapier-inferred domain, use the whole base URL.
-        const baseUrl = new URL(this.options.baseUrl);
-        const fullPath = baseUrl.pathname.replace(/\/$/, "") + path;
-        return {
-            url: new URL(fullPath, baseUrl.origin),
-            pathConfig: config,
-        };
-    }
-    // Helper to build full URLs and return routing info
-    buildUrl(path, searchParams) {
-        const { url, pathConfig: config } = this.applyPathConfiguration(path);
-        if (searchParams) {
-            Object.entries(searchParams).forEach(([key, value]) => {
-                url.searchParams.set(key, value);
-            });
-        }
-        return { url: url.toString(), pathConfig: config };
-    }
-    // Helper to build headers
-    async buildHeaders(options = {}, pathConfig) {
-        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 = pathConfig && pathConfig.authHeader
-                ? pathConfig.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 = {}) {
-        // Check if this path has a handler override
-        const routeMatch = matchRoute(method, path);
-        if (routeMatch) {
-            // Invoke the handler instead of making an HTTP request
-            // Merge params from all sources: body, searchParams, and route params
-            const handlerRequest = {
-                ...(typeof data === "object" ? data : {}),
-                ...options.searchParams,
-                ...routeMatch.params,
-            };
-            return routeMatch.handler({
-                request: handlerRequest,
-                deps: {
-                    httpClient: this,
-                },
-            });
-        }
-        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, pathConfig } = this.buildUrl(path, fetchOptions?.searchParams);
-        const builtHeaders = await this.buildHeaders(fetchOptions, pathConfig);
-        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 { debug = false, fetch: originalFetch = globalThis.fetch } = options;
-    const debugLog = createDebugLogger(debug);
-    const debugFetch = createDebugFetch({ originalFetch, debugLog });
-    return new ZapierApiClient({
-        ...options,
-        debug,
-        fetch: debugFetch,
-    });
-};