@zapier/zapier-sdk 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/zapier-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Complete Zapier SDK - combines all Zapier SDK packages",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -31,13 +31,21 @@
     "access": "restricted"
   },
   "dependencies": {
-    "esbuild": "^0.25.5",
     "zod": "^3.25.67"
   },
+  "peerDependencies": {
+    "@zapier/zapier-sdk-cli-login": "*"
+  },
+  "peerDependenciesMeta": {
+    "@zapier/zapier-sdk-cli-login": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/node": "^24.0.1",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
+    "vitest": "^3.2.3",
     "@zapier/zapier-sdk-cli-login": "0.3.1"
   },
   "scripts": {
@@ -45,6 +53,7 @@
     "clean": "rm -rf dist",
     "rebuild": "pnpm clean && pnpm build",
     "dev": "tsc --watch",
-    "typecheck": "tsc --project tsconfig.build.json --noEmit"
+    "typecheck": "tsc --project tsconfig.build.json --noEmit",
+    "test": "vitest"
   }
 }

package/src/api/client.ts

@@ -15,157 +15,307 @@ import { getAuthorizationHeader } from "./auth";
 import { createDebugLogger, createDebugFetch } from "./debug";
 import { pollUntilComplete } from "./polling";
 import { getTokenFromEnvOrConfig } from "../auth";
+import {
+  ZapierApiError,
+  ZapierAuthenticationError,
+  ZapierValidationError,
+  ZapierNotFoundError,
+  type ApiError,
+} from "../types/errors";
+
+// Configuration for path prefixes that should be treated as subdomains
+type SubdomainConfigMap = typeof SubdomainConfigMap;
+type SubdomainConfig = SubdomainConfigMap[keyof SubdomainConfigMap];
+const SubdomainConfigMap = {
+  // e.g. https://relay.zapier.com
+  relay: {
+    authHeader: "X-Relay-Authorization",
+  },
+} as const;
+
+class ZapierApiClient implements ApiClient {
+  constructor(
+    private readonly options: ApiClientOptions &
+      Required<Pick<ApiClientOptions, "fetch">>,
+  ) {}
+
+  // Helper to parse response data
+  private async parseResult<TOutput = unknown>(
+    response: Response,
+  ): Promise<{ type: "json"; data: TOutput } | { type: "text"; data: string }> {
+    try {
+      return { type: "json", data: await response.json() };
+    } catch {
+      return { type: "text", data: await response.text() };
+    }
+  }
 
-// Set of path prefixes that should be treated as subdomains
-const SUBDOMAIN_PREFIXES = new Set(["relay"]);
+  // Helper to get a token from the different places it could be gotten
+  private async getAuthToken(): Promise<string | undefined> {
+    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,
+    });
+  }
 
-export function createZapierApi(options: ApiClientOptions): ApiClient {
-  const {
-    baseUrl,
-    token,
-    getToken,
-    debug = false,
-    fetch: originalFetch = globalThis.fetch,
-    onEvent,
-  } = options;
+  // Helper to handle responses
+  private async handleResponse<TOutput = unknown>(params: {
+    response: Response;
+    customErrorHandler?: RequestOptions["customErrorHandler"];
+    wasMissingAuthToken?: boolean;
+  }): Promise<string | TOutput> {
+    const { response, customErrorHandler, wasMissingAuthToken } = params;
+    const { data: responseData } = await this.parseResult<TOutput>(response);
+    if (response.ok) {
+      return responseData;
+    }
 
-  const debugLog = createDebugLogger(debug);
-  const fetch = createDebugFetch({ originalFetch, debugLog });
+    const errorInfo = {
+      status: response.status,
+      statusText: response.statusText,
+      data: responseData,
+    };
 
-  // Helper to build full URLs
-  function buildUrl(
-    path: string,
-    searchParams?: Record<string, string>,
-  ): string {
-    // Check if this is a path that needs subdomain routing
-    const pathSegments = path.split("/").filter(Boolean);
-    let finalBaseUrl = baseUrl;
+    // 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)}`,
+          );
+        }
+      }
+    }
 
-    if (pathSegments.length > 0 && SUBDOMAIN_PREFIXES.has(pathSegments[0])) {
-      // Transform paths to use subdomain routing
-      // /prefix/domain/path -> prefix.zapier.com/domain/path
-      const subdomain = pathSegments[0];
-      const baseUrlObj = new URL(baseUrl);
-      baseUrlObj.hostname = `${subdomain}.${baseUrlObj.hostname}`;
-      finalBaseUrl = baseUrlObj.toString();
+    // Parse the error response
+    const { message, errors } = this.parseErrorResponse(errorInfo);
+
+    const errorOptions = {
+      statusCode: response.status,
+      errors,
+    };
 
-      // Remove the subdomain prefix from the path
-      path = "/" + pathSegments.slice(1).join("/");
+    // Use appropriate error type based on status code
+    if (response.status === 404) {
+      throw new ZapierNotFoundError(message, errorOptions);
     }
 
-    const url = new URL(path, finalBaseUrl);
-    if (searchParams) {
-      Object.entries(searchParams).forEach(([key, value]) => {
-        url.searchParams.set(key, value);
-      });
+    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);
     }
-    return url.toString();
+
+    if (response.status === 400) {
+      throw new ZapierValidationError(message, errorOptions);
+    }
+
+    // Generic API error for other status codes
+    throw new ZapierApiError(message, errorOptions);
   }
 
-  // Helper to build headers
-  async function buildHeaders(
-    options: RequestOptions = {},
-  ): Promise<Record<string, string>> {
-    const headers: Record<string, string> = {
-      ...options.headers,
-    };
+  private hasErrorArray<TOutput = unknown>(
+    data: TOutput | string,
+  ): data is { errors: unknown[] } & Exclude<TOutput, string> {
+    return (
+      typeof data === "object" &&
+      data !== null &&
+      "errors" in data &&
+      Array.isArray(data.errors)
+    );
+  }
 
-    // Add auth header if token provided and not explicitly disabled
-    if (options.authRequired !== false) {
-      let resolvedToken = token;
+  // Helper to check if data has API errors
+  private isApiErrorArray(dataArray: unknown[]): dataArray is ApiError[] {
+    const data = dataArray[0];
+    return (
+      typeof data === "object" &&
+      data !== null &&
+      "message" in data &&
+      "code" in data &&
+      "title" in data &&
+      "detail" in data
+    );
+  }
 
-      // Token resolution precedence: explicit token > getToken() > env/config fallback
-      if (!resolvedToken && getToken) {
-        resolvedToken = await getToken();
+  // Do our best to extract an error message from the response data
+  private extractErrorMessage<TOutput = unknown>(
+    data: TOutput | string,
+  ): string | undefined {
+    if (typeof data === "string") {
+      return data;
+    }
+    if (typeof data === "object" && data !== null) {
+      if ("message" in data && typeof data.message === "string") {
+        return data.message;
       }
-
-      if (!resolvedToken) {
-        resolvedToken = await getTokenFromEnvOrConfig({
-          onEvent,
-          fetch: originalFetch,
-        });
+      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 (resolvedToken) {
-        headers.Authorization = getAuthorizationHeader(resolvedToken);
+      if ("errors" in data && Array.isArray(data.errors)) {
+        if (this.isApiErrorArray(data.errors)) {
+          return data.errors[0].detail || data.errors[0].title;
+        }
       }
     }
-
-    return headers;
+    return undefined;
   }
 
-  // Helper to handle responses
-  async function handleResponse(
-    response: Response,
-    customErrorHandler?: (response: Response) => Error | undefined,
-    hadAuthToken?: boolean,
-  ): Promise<any> {
-    if (!response.ok) {
-      // Check for custom error handling first
-      if (customErrorHandler) {
-        const customError = customErrorHandler(response);
-        if (customError) {
-          throw customError;
-        }
+  // Helper to parse API error response
+  private parseErrorResponse<TOutput = unknown>(errorInfo: {
+    status: number;
+    statusText: string;
+    data: TOutput | string;
+  }): { message: string; errors?: ApiError[] } {
+    // 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}` };
       }
 
-      // If we get a 4xx error and no auth token was provided, give helpful message
-      if (response.status >= 400 && response.status < 500 && !hadAuthToken) {
-        throw new Error(
-          `Authentication required (HTTP ${response.status}). Please provide a token in options or set ZAPIER_TOKEN environment variable.`,
-        );
+      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),
+            })),
+          };
+        }
       }
 
-      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
-    }
-
-    // Try to parse JSON, fall back to text if that fails
-    try {
-      return await response.json();
+      return { message: errorMessage };
     } catch {
-      return await response.text();
+      return { message: fallbackMessage };
     }
   }
 
-  // Plain fetch method that matches the standard fetch signature
-  async function plainFetch(
-    input: string | URL,
-    init?: RequestInit & {
-      searchParams?: Record<string, string>;
-      authRequired?: boolean;
-      customErrorHandler?: (response: Response) => Error | undefined;
-    },
-  ): Promise<Response> {
-    const url =
-      typeof input === "string" && !input.startsWith("http")
-        ? buildUrl(input, init?.searchParams)
-        : input.toString();
-
-    const headers = await buildHeaders(init as RequestOptions);
-
-    // Merge headers from init with our built headers
-    const finalHeaders = {
-      ...headers,
-      ...(init?.headers
-        ? init.headers instanceof Headers
-          ? Object.fromEntries(init.headers.entries())
-          : (init.headers as Record<string, string>)
-        : {}),
+  // Check if this is a path that needs subdomain routing
+  // e.g. /relay/workflows -> relay.zapier.com/workflows
+  private applySubdomainBehavior(path: string): {
+    url: URL;
+    subdomainConfig?: SubdomainConfig;
+  } {
+    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] as keyof typeof SubdomainConfigMap;
+      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,
     };
+  }
 
-    return await fetch(url, {
-      ...init,
-      headers: finalHeaders,
-    });
+  // Helper to build full URLs and return routing info
+  private buildUrl(
+    path: string,
+    searchParams?: Record<string, string>,
+  ): {
+    url: string;
+    subdomainConfig?: SubdomainConfig;
+  } {
+    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
+  private async buildHeaders(
+    options: RequestOptions = {},
+    subdomainConfig?: (typeof SubdomainConfigMap)[keyof typeof SubdomainConfigMap],
+  ): Promise<Headers> {
+    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 function fetchJson(
+  private async fetchJson<TOutput = unknown>(
     method: string,
     path: string,
-    data?: any,
+    data?: TOutput,
     options: RequestOptions = {},
-  ): Promise<any> {
+  ): Promise<TOutput> {
     const headers = { ...options.headers };
 
     // Add Content-Type for JSON requests with body data
@@ -173,70 +323,156 @@ export function createZapierApi(options: ApiClientOptions): ApiClient {
       headers["Content-Type"] = "application/json";
     }
 
-    const response = await plainFetch(path, {
+    // 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 ? JSON.stringify(data) : undefined,
+      body: data != null ? JSON.stringify(data) : undefined,
       headers,
-      searchParams: options.searchParams,
-      authRequired: options.authRequired,
+    });
+
+    // plainFetch already handled all auth and headers
+    const result = await this.handleResponse<TOutput>({
+      response,
       customErrorHandler: options.customErrorHandler,
+      wasMissingAuthToken,
     });
 
-    const hadAuthToken = !!(await buildHeaders(options)).Authorization;
-    return handleResponse(response, options.customErrorHandler, hadAuthToken);
+    if (typeof result === "string") {
+      throw new ZapierValidationError(
+        `Response could not be parsed as JSON: ${result}`,
+      );
+    }
+
+    return result;
   }
 
-  return {
-    async get(path: string, options: RequestOptions = {}): Promise<any> {
-      return fetchJson("GET", path, undefined, options);
+  // Plain fetch method for API paths (must start with /)
+  private async plainFetch(
+    path: string,
+    fetchOptions?: RequestInit & {
+      searchParams?: Record<string, string>;
+      authRequired?: boolean;
     },
+  ): Promise<Response> {
+    if (!path.startsWith("/")) {
+      throw new ZapierValidationError(
+        `plainFetch expects a path starting with '/', got: ${path}`,
+      );
+    }
 
-    async post(
-      path: string,
-      data?: any,
-      options: RequestOptions = {},
-    ): Promise<any> {
-      return fetchJson("POST", path, data, options);
-    },
+    if (fetchOptions?.body && typeof fetchOptions.body === "object") {
+      fetchOptions.body = JSON.stringify(fetchOptions.body);
+    }
 
-    async put(
-      path: string,
-      data?: any,
-      options: RequestOptions = {},
-    ): Promise<any> {
-      return fetchJson("PUT", path, data, options);
-    },
+    const { url, subdomainConfig } = this.buildUrl(
+      path,
+      fetchOptions?.searchParams,
+    );
 
-    async delete(path: string, options: RequestOptions = {}): Promise<any> {
-      return fetchJson("DELETE", path, undefined, options);
-    },
+    const builtHeaders = await this.buildHeaders(
+      fetchOptions as RequestOptions,
+      subdomainConfig,
+    );
+    const inputHeaders = new Headers(fetchOptions?.headers ?? {});
 
-    async poll(path: string, options: PollOptions = {}): Promise<any> {
-      const url = buildUrl(path, options.searchParams);
-      const headers = await buildHeaders(options);
-
-      return pollUntilComplete({
-        fetch,
-        url,
-        headers,
-        maxAttempts: options.maxAttempts,
-        initialDelay: options.initialDelay,
-        maxDelay: options.maxDelay,
-        successStatus: options.successStatus,
-        pendingStatus: options.pendingStatus,
-        resultExtractor: options.resultExtractor,
-      });
-    },
+    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,
+    });
+  }
 
-    async fetch(
-      input: string | URL,
-      init?: RequestInit & {
-        searchParams?: Record<string, string>;
-        authRequired?: boolean;
-        customErrorHandler?: (response: Response) => Error | undefined;
-      },
-    ): Promise<Response> {
-      return plainFetch(input, init);
+  public fetch = async (
+    path: string,
+    init?: RequestInit & {
+      searchParams?: Record<string, string>;
+      authRequired?: boolean;
     },
+  ): Promise<Response> => {
+    return this.plainFetch(path, init);
+  };
+
+  public get = async <TOutput = unknown>(
+    path: string,
+    options: RequestOptions = {},
+  ): Promise<TOutput> => {
+    return this.fetchJson<TOutput>("GET", path, undefined, options);
+  };
+
+  public post = async <TOutput = unknown>(
+    path: string,
+    data?: TOutput,
+    options: RequestOptions = {},
+  ): Promise<TOutput> => {
+    return this.fetchJson<TOutput>("POST", path, data, options);
+  };
+
+  public put = async <TOutput = unknown>(
+    path: string,
+    data?: TOutput,
+    options: RequestOptions = {},
+  ): Promise<TOutput> => {
+    return this.fetchJson<TOutput>("PUT", path, data, options);
+  };
+
+  public delete = async <TOutput = unknown>(
+    path: string,
+    options: RequestOptions = {},
+  ): Promise<TOutput> => {
+    return this.fetchJson<TOutput>("DELETE", path, undefined, options);
+  };
+
+  public poll = async <TOutput = unknown>(
+    path: string,
+    options: PollOptions = {},
+  ): Promise<TOutput> => {
+    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,
+    });
   };
 }
+
+export const createZapierApi = (options: ApiClientOptions): ApiClient => {
+  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,
+  });
+};