@zapier/zapier-sdk 0.3.0 → 0.4.0

package/src/functions/fetch/index.ts

@@ -0,0 +1,180 @@
+import { getOrCreateApiClient } from "../../api";
+import type { FunctionOptions } from "../../types/domain";
+
+export interface RelayFetchOptions {
+  /** HTTP method */
+  method?: string;
+  /** Request body as a string */
+  body?: string;
+  /** Request headers */
+  headers?: HeadersInit;
+  /** Zapier authentication ID to use for the request */
+  authenticationId?: number;
+  /** URL to send async response to (makes request async) */
+  callbackUrl?: string;
+  /** Optional JSON string authentication template to bypass Notary lookup */
+  authenticationTemplate?: string;
+}
+
+export interface RelayFetchConfig extends FunctionOptions {
+  /** Event callback function */
+  onEvent?: (event: any) => void;
+}
+
+/**
+ * Transforms full URLs into Relay format: /relay/{domain}/{path}
+ *
+ * @param url - The full URL to transform (e.g., "https://api.github.com/user")
+ * @returns The relay path format (e.g., "/relay/api.github.com/user")
+ */
+function transformUrlToRelayPath(url: string | URL): string {
+  const targetUrl = new URL(url);
+
+  // Build the Relay path: /relay/{domain}{pathname}{search}{hash}
+  const relayPath = `/relay/${targetUrl.hostname}${targetUrl.pathname}${targetUrl.search}${targetUrl.hash}`;
+
+  return relayPath;
+}
+
+/**
+ * Fetch function that can make requests to external APIs through Zapier's Relay service
+ *
+ * This function takes full URLs (like https://api.github.com/user) and transforms them
+ * into the relay format (/relay/api.github.com/user) for the API client to route
+ * to relay.zapier.com.
+ *
+ * @param url - The full URL to fetch
+ * @param options - Fetch options with additional Relay-specific parameters
+ * @param config - SDK configuration options
+ * @returns Promise<Response> - The response from the request
+ */
+/**
+ * Schema-compatible wrapper function for the fetch functionality
+ */
+export async function fetch(
+  options: {
+    url: string;
+    method?: string;
+    body?: string;
+    headers?: Record<string, string>;
+    authenticationId?: number;
+    callbackUrl?: string;
+    authenticationTemplate?: string;
+  } & FunctionOptions,
+): Promise<Response> {
+  const {
+    url,
+    method = "GET",
+    body,
+    headers,
+    authenticationId,
+    callbackUrl,
+    authenticationTemplate,
+    ...config
+  } = options;
+
+  return relayFetch(
+    url,
+    {
+      method,
+      body,
+      headers,
+      authenticationId,
+      callbackUrl,
+      authenticationTemplate,
+    },
+    config,
+  );
+}
+
+/**
+ * Internal fetch implementation
+ */
+export async function relayFetch(
+  url: string | URL,
+  options: RelayFetchOptions = {},
+  config: RelayFetchConfig = {},
+): Promise<Response> {
+  const api = getOrCreateApiClient(config);
+
+  // Extract Relay-specific options
+  const {
+    authenticationId,
+    callbackUrl,
+    authenticationTemplate,
+    method = "GET",
+    body,
+    ...fetchOptions
+  } = options;
+
+  // Transform full URL to relay path format
+  const relayPath = transformUrlToRelayPath(url);
+
+  // Build headers for the request
+  const headers: Record<string, string> = {};
+
+  // Copy existing headers
+  if (fetchOptions.headers) {
+    const headerEntries =
+      fetchOptions.headers instanceof Headers
+        ? Array.from(fetchOptions.headers.entries())
+        : Object.entries(fetchOptions.headers);
+
+    for (const [key, value] of headerEntries) {
+      headers[key] = value;
+    }
+  }
+
+  // Add Relay-specific headers
+  if (authenticationId) {
+    headers["X-Relay-Authentication-Id"] = authenticationId.toString();
+  }
+
+  if (callbackUrl) {
+    headers["X-Relay-Callback-Url"] = callbackUrl;
+  }
+
+  if (authenticationTemplate) {
+    headers["X-Authentication-Template"] = authenticationTemplate;
+  }
+
+  // For Relay requests, we need to disable the default authorization and add our own
+  const requestOptions = {
+    headers,
+    authRequired: false, // Disable automatic Authorization header
+    customErrorHandler: (response: Response) => {
+      if (!response.ok) {
+        return new Error(
+          `Relay request failed: ${response.status} ${response.statusText}`,
+        );
+      }
+      return undefined;
+    },
+  };
+
+  // Add X-Relay-Authorization header manually
+  let token = config.token;
+  if (!token && config.getToken) {
+    token = await config.getToken();
+  }
+  if (!token) {
+    const { getTokenFromEnvOrConfig } = await import("../../auth");
+    token = await getTokenFromEnvOrConfig({
+      onEvent: config.onEvent,
+      fetch: config.fetch,
+    });
+  }
+  if (token) {
+    const { getAuthorizationHeader } = await import("../../api/auth");
+    headers["X-Relay-Authorization"] = getAuthorizationHeader(token);
+  }
+
+  // Use the API client's fetch method directly
+  return await api.fetch(relayPath, {
+    method,
+    body,
+    headers: requestOptions.headers,
+    authRequired: requestOptions.authRequired,
+    customErrorHandler: requestOptions.customErrorHandler,
+  });
+}

package/src/functions/fetch/info.ts

@@ -0,0 +1,8 @@
+import { fetch } from "./index";
+import { RelayFetchSchema } from "./schemas";
+
+export const fetchInfo = {
+  name: "fetch",
+  inputSchema: RelayFetchSchema,
+  implementation: fetch,
+};

package/src/functions/fetch/schemas.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { FunctionOptions } from "../../types/domain";
+
+// Pure Zod schema for the fetch function
+export const RelayFetchSchema = z
+  .object({
+    url: z
+      .string()
+      .url()
+      .describe("The URL to fetch (will be proxied through Relay)"),
+    method: z
+      .enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"])
+      .optional()
+      .describe("HTTP method"),
+    body: z.string().optional().describe("Request body as a string"),
+    authenticationId: z
+      .number()
+      .int()
+      .optional()
+      .describe("Zapier authentication ID to use for the request"),
+    callbackUrl: z
+      .string()
+      .url()
+      .optional()
+      .describe("URL to send async response to (makes request async)"),
+    authenticationTemplate: z
+      .string()
+      .optional()
+      .describe(
+        "Optional JSON string authentication template to bypass Notary lookup",
+      ),
+    headers: z.record(z.string()).optional().describe("Request headers"),
+  })
+  .describe("Make authenticated HTTP requests through Zapier's Relay service");
+
+// Type inferred from schema + function config
+export type RelayFetchOptions = z.infer<typeof RelayFetchSchema> &
+  FunctionOptions & {
+    /** Base URL for Relay service */
+    relayBaseUrl?: string;
+  };
+
+// SDK function interface
+export interface RelayFetchSdkFunction {
+  fetch: (options: RelayFetchOptions) => Promise<Response>;
+}

package/src/functions/findFirstAuthentication/schemas.ts

@@ -6,7 +6,7 @@ import {
 } from "../../types/properties";
 import { withOutputSchema } from "../../schema-utils";
 import { AuthItemSchema } from "../../schemas/Auth";
-import type { Authentication } from "../../types/domain";
+import type { Authentication, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const FindFirstAuthenticationSchema = withOutputSchema(
@@ -39,18 +39,8 @@ export const FindFirstAuthenticationSchema = withOutputSchema(
 // Type inferred from schema + function config
 export type FindFirstAuthenticationOptions = z.infer<
   typeof FindFirstAuthenticationSchema
-> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface FindFirstAuthenticationSdkFunction {

package/src/functions/findUniqueAuthentication/schemas.ts

@@ -6,7 +6,7 @@ import {
 } from "../../types/properties";
 import { withOutputSchema } from "../../schema-utils";
 import { AuthItemSchema } from "../../schemas/Auth";
-import type { Authentication } from "../../types/domain";
+import type { Authentication, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const FindUniqueAuthenticationSchema = withOutputSchema(
@@ -39,18 +39,8 @@ export const FindUniqueAuthenticationSchema = withOutputSchema(
 // Type inferred from schema + function config
 export type FindUniqueAuthenticationOptions = z.infer<
   typeof FindUniqueAuthenticationSchema
-> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface FindUniqueAuthenticationSdkFunction {

package/src/functions/generateTypes/index.ts

@@ -7,6 +7,14 @@ interface ActionWithActionFields extends Omit<Action, "inputFields"> {
   inputFields: ActionField[];
 }
 
+/**
+ * Generate the fetch method signature for app proxies
+ */
+function generateFetchMethodSignature(): string {
+  return `  /** Make authenticated HTTP requests through Zapier's Relay service */
+  fetch: (options: Omit<z.infer<typeof RelayFetchSchema>, 'authenticationId'>) => Promise<Response>`;
+}
+
 /**
  * Generate TypeScript types for a specific app
  *
@@ -148,6 +156,8 @@ ${versionComment}
  */
 
 import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
+import { z } from 'zod'
+import { RelayFetchSchema } from '@zapier/zapier-sdk'
 
 `;
 
@@ -211,6 +221,8 @@ import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapi
     const typeName = `${appName}${capitalize(actionType)}Actions`;
     output += `  ${actionType}: ${typeName}\n`;
   });
+  // Always include fetch method for authenticated HTTP requests
+  output += generateFetchMethodSignature() + "\n";
   output += `}\n\n`;
 
   // Generate the factory function interface
@@ -247,9 +259,12 @@ ${versionComment}
  */
 
 import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
+import { z } from 'zod'
+import { RelayFetchSchema } from '@zapier/zapier-sdk'
 
 interface ${appName}AppProxy {
   // No actions available
+${generateFetchMethodSignature()}
 }
 
 interface ${appName}AppFactory {

package/src/functions/generateTypes/schemas.ts

@@ -5,6 +5,7 @@ import {
   OutputPropertySchema,
   DebugPropertySchema,
 } from "../../types/properties";
+import type { FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const GenerateTypesSchema = z
@@ -21,16 +22,8 @@ export const GenerateTypesSchema = z
   .describe("Generate TypeScript SDK code for a specific app");
 
 // Type inferred from schema + function config
-export type GenerateTypesOptions = z.infer<typeof GenerateTypesSchema> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+export type GenerateTypesOptions = z.infer<typeof GenerateTypesSchema> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface GenerateTypesSdkFunction {

package/src/functions/getAction/schemas.ts

@@ -4,7 +4,7 @@ import {
   ActionTypePropertySchema,
   ActionKeyPropertySchema,
 } from "../../types/properties";
-import type { Action } from "../../types/domain";
+import type { Action, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const GetActionSchema = z
@@ -16,18 +16,8 @@ export const GetActionSchema = z
   .describe("Get detailed information about a specific action");
 
 // Type inferred from schema + function config
-export type GetActionOptions = z.infer<typeof GetActionSchema> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+export type GetActionOptions = z.infer<typeof GetActionSchema> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface GetActionSdkFunction {

package/src/functions/getApp/schemas.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { AppKeyPropertySchema } from "../../types/properties";
-import type { Integration } from "../../types/domain";
+import type { Integration, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const GetAppSchema = z
@@ -12,18 +12,7 @@ export const GetAppSchema = z
   .describe("Get detailed information about a specific app");
 
 // Type inferred from schema + function config
-export type GetAppOptions = z.infer<typeof GetAppSchema> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+export type GetAppOptions = z.infer<typeof GetAppSchema> & FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface GetAppSdkFunction {

package/src/functions/getAuthentication/index.ts

@@ -17,7 +17,6 @@ export async function getAuthentication(
 ): Promise<Authentication> {
   const { authenticationId } = options;
   const api = getOrCreateApiClient(options);
-  api.requireAuthTo("get authentication");
 
   const data: Authentication = await api.get(
     `/api/v4/authentications/${authenticationId}/`,

package/src/functions/getAuthentication/schemas.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { withOutputSchema } from "../../schema-utils";
 import { AuthItemSchema } from "../../schemas/Auth";
-import type { Authentication } from "../../types/domain";
+import type { Authentication, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const GetAuthenticationSchema = withOutputSchema(
@@ -18,22 +18,8 @@ export const GetAuthenticationSchema = withOutputSchema(
 );
 
 // Type inferred from schema + function config
-export type GetAuthenticationOptions = z.infer<
-  typeof GetAuthenticationSchema
-> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Function to dynamically resolve authentication token */
-  getToken?: () => Promise<string | undefined>;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+export type GetAuthenticationOptions = z.infer<typeof GetAuthenticationSchema> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface GetAuthenticationSdkFunction {

package/src/functions/listActions/schemas.ts

@@ -5,7 +5,7 @@ import {
 } from "../../types/properties";
 import { withOutputSchema } from "../../schema-utils";
 import { ActionItemSchema } from "../../schemas/Action";
-import type { Action } from "../../types/domain";
+import type { Action, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const ListActionsSchema = withOutputSchema(
@@ -21,18 +21,8 @@ export const ListActionsSchema = withOutputSchema(
 );
 
 // Type inferred from schema + function config
-export type ListActionsOptions = z.infer<typeof ListActionsSchema> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+export type ListActionsOptions = z.infer<typeof ListActionsSchema> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface ListActionsSdkFunction {

package/src/functions/listApps/schemas.ts

@@ -5,7 +5,7 @@ import {
 } from "../../types/properties";
 import { withOutputSchema } from "../../schema-utils";
 import { AppItemSchema } from "../../schemas/App";
-import type { Integration } from "../../types/domain";
+import type { Integration, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const ListAppsSchema = withOutputSchema(
@@ -24,18 +24,7 @@ export const ListAppsSchema = withOutputSchema(
 );
 
 // Type inferred from schema + function config
-export type ListAppsOptions = z.infer<typeof ListAppsSchema> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+export type ListAppsOptions = z.infer<typeof ListAppsSchema> & FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface ListAppsSdkFunction {

package/src/functions/listAuthentications/index.ts

@@ -19,7 +19,6 @@ export async function listAuthentications(
   options: Partial<ListAuthenticationsOptions> = {},
 ): Promise<Authentication[]> {
   const api = getOrCreateApiClient(options);
-  api.requireAuthTo("list authentications");
 
   // Local function to handle the actual API fetching
   const listAuthenticationsInternal = async (

package/src/functions/listAuthentications/schemas.ts

@@ -6,7 +6,7 @@ import {
 } from "../../types/properties";
 import { withOutputSchema } from "../../schema-utils";
 import { AuthItemSchema } from "../../schemas/Auth";
-import type { Authentication } from "../../types/domain";
+import type { Authentication, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const ListAuthenticationsSchema = withOutputSchema(
@@ -39,20 +39,8 @@ export const ListAuthenticationsSchema = withOutputSchema(
 // Type inferred from schema + function config
 export type ListAuthenticationsOptions = z.infer<
   typeof ListAuthenticationsSchema
-> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Function to dynamically resolve authentication token */
-  getToken?: () => Promise<string | undefined>;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface ListAuthenticationsSdkFunction {

package/src/functions/listFields/schemas.ts

@@ -8,7 +8,7 @@ import {
 } from "../../types/properties";
 import { withOutputSchema } from "../../schema-utils";
 import { FieldItemSchema } from "../../schemas/Field";
-import type { ActionField } from "../../types/domain";
+import type { ActionField, FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const ListFieldsSchema = withOutputSchema(
@@ -27,18 +27,8 @@ export const ListFieldsSchema = withOutputSchema(
 );
 
 // Type inferred from schema + function config
-export type ListFieldsOptions = z.infer<typeof ListFieldsSchema> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+export type ListFieldsOptions = z.infer<typeof ListFieldsSchema> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface ListFieldsSdkFunction {

package/src/functions/runAction/index.ts

@@ -25,7 +25,6 @@ export async function runAction(
   } = options;
 
   const api = getOrCreateApiClient(options);
-  api.requireAuthTo("run actions");
 
   // Validate that the action exists
   const actionData = await getAction({

package/src/functions/runAction/schemas.ts

@@ -6,7 +6,10 @@ import {
   AuthenticationIdPropertySchema,
   InputsPropertySchema,
 } from "../../types/properties";
-import type { ActionExecutionResult } from "../../types/domain";
+import type {
+  ActionExecutionResult,
+  FunctionOptions,
+} from "../../types/domain";
 
 // Pure Zod schema - no resolver metadata!
 export const RunActionSchema = z
@@ -22,20 +25,8 @@ export const RunActionSchema = z
   .describe("Execute an action with the given inputs");
 
 // Type inferred from schema + function config
-export type RunActionOptions = z.infer<typeof RunActionSchema> & {
-  /** Base URL for Zapier API */
-  baseUrl?: string;
-  /** Authentication token */
-  token?: string;
-  /** Function to dynamically resolve authentication token */
-  getToken?: () => Promise<string | undefined>;
-  /** Optional pre-instantiated API client */
-  api?: any;
-  /** Enable debug logging */
-  debug?: boolean;
-  /** Custom fetch implementation */
-  fetch?: typeof globalThis.fetch;
-};
+export type RunActionOptions = z.infer<typeof RunActionSchema> &
+  FunctionOptions;
 
 // SDK function interface - ready to be mixed into main SDK interface
 export interface RunActionSdkFunction {

package/src/index.ts

@@ -27,9 +27,11 @@ export { runAction } from "./functions/runAction";
 export { listFields } from "./functions/listFields";
 export { generateTypes } from "./functions/generateTypes";
 export { bundleCode } from "./functions/bundleCode";
+export { fetch, relayFetch } from "./functions/fetch";
+export { RelayFetchSchema } from "./functions/fetch/schemas";
 
 // Export the main combined SDK
 export { createZapierSdk, ZapierSdkOptions } from "./sdk";
 
-// Export SDK type from types (not sdk.ts to avoid circular imports)
-export type { ZapierSdk } from "./types/sdk";
+// Export SDK types from types (not sdk.ts to avoid circular imports)
+export type { BaseZapierSdk, ZapierSdk } from "./types/sdk";