@zapier/zapier-sdk 0.0.3 → 0.1.0

package/src/api/index.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 all types
+export type {
+  // API Client Infrastructure Types
+  ApiClient,
+  ApiClientOptions,
+  RequestOptions,
+  PollOptions,
+  DebugLogger,
+  // API Response Model Types
+  Integration,
+  Action,
+  Trigger,
+  Field,
+  Choice,
+  ActionExecutionResult,
+  ActionField,
+  ActionFieldChoice,
+  NeedsRequest,
+  NeedsResponse,
+  Authentication,
+  AuthenticationsResponse,
+} from "./types";
+
+// 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";
+
+// Utility Functions
+export function generateRequestId(): string {
+  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: {
+  baseUrl?: string;
+  token?: string;
+  api?: import("./types").ApiClient;
+  debug?: boolean;
+  fetch?: typeof globalThis.fetch;
+}): import("./types").ApiClient {
+  const {
+    baseUrl = "https://zapier.com",
+    token = process.env.ZAPIER_TOKEN,
+    api: providedApi,
+    debug = false,
+    fetch: customFetch,
+  } = config;
+
+  // Use provided API client or create a new one
+  if (providedApi) {
+    return providedApi;
+  }
+
+  // Import createZapierApi locally to avoid circular imports
+  const { createZapierApi } = require("./client");
+  return createZapierApi({
+    baseUrl,
+    token,
+    debug,
+    fetch: customFetch,
+  });
+}

package/src/api/polling.ts

@@ -0,0 +1,56 @@
+/**
+ * Polling Utilities
+ *
+ * This module provides utilities for polling HTTP endpoints until completion,
+ * with configurable retry logic and exponential backoff.
+ */
+
+export async function pollUntilComplete(options: {
+  fetch: typeof globalThis.fetch;
+  url: string;
+  headers?: Record<string, string>;
+  maxAttempts?: number;
+  initialDelay?: number;
+  maxDelay?: number;
+  successStatus?: number;
+  pendingStatus?: number;
+  resultExtractor?: (response: any) => any;
+}): Promise<any> {
+  const {
+    fetch,
+    url,
+    headers = {},
+    maxAttempts = 30,
+    initialDelay = 50,
+    maxDelay = 1000,
+    successStatus = 200,
+    pendingStatus = 202,
+    resultExtractor = (response) => response,
+  } = options;
+
+  let delay = initialDelay;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const response = await fetch(url, { headers });
+
+    if (response.status === successStatus) {
+      // Success - extract and return results
+      const result = await response.json();
+      return resultExtractor(result);
+    } else if (response.status === pendingStatus) {
+      // Still processing - wait and retry
+      if (attempt < maxAttempts - 1) {
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        delay = Math.min(delay * 2, maxDelay); // Exponential backoff
+        continue;
+      }
+    } else {
+      // Error occurred
+      throw new Error(
+        `Request failed: GET ${url} - ${response.status} ${response.statusText}`,
+      );
+    }
+  }
+
+  throw new Error(`Operation timed out after ${maxAttempts} attempts`);
+}

package/src/api/types.ts

@@ -0,0 +1,177 @@
+/**
+ * API Client Type Definitions
+ *
+ * This module contains all type definitions related to the Zapier API client,
+ * including configuration options, client interfaces, request/response types,
+ * and API response models.
+ */
+
+// ============================================================================
+// API Client Infrastructure Types
+// ============================================================================
+
+export interface ApiClientOptions {
+  baseUrl: string;
+  token?: string;
+  debug?: boolean;
+  fetch?: typeof globalThis.fetch;
+}
+
+export interface ApiClient {
+  get: (path: string, options?: RequestOptions) => Promise<any>;
+  post: (path: string, data?: any, options?: RequestOptions) => Promise<any>;
+  put: (path: string, data?: any, options?: RequestOptions) => Promise<any>;
+  delete: (path: string, options?: RequestOptions) => Promise<any>;
+  poll: (path: string, options?: PollOptions) => Promise<any>;
+}
+
+export interface RequestOptions {
+  headers?: Record<string, string>;
+  searchParams?: Record<string, string>;
+  authRequired?: boolean;
+  customErrorHandler?: (response: Response) => Error | undefined;
+}
+
+export interface PollOptions extends RequestOptions {
+  maxAttempts?: number;
+  initialDelay?: number;
+  maxDelay?: number;
+  successStatus?: number;
+  pendingStatus?: number;
+  resultExtractor?: (response: any) => any;
+}
+
+export interface DebugLogger {
+  (message: string, data?: any): void;
+}
+
+// ============================================================================
+// API Response Models
+// ============================================================================
+
+export interface Integration {
+  key: string;
+  name: string;
+  description: string;
+  version: string;
+  category?: string;
+  actions: Action[];
+  triggers: Trigger[];
+  current_implementation_id?: string;
+}
+
+export interface Action {
+  key: string;
+  name: string;
+  description: string;
+  appKey: string;
+  type: "create" | "update" | "search" | "delete" | "read";
+  inputFields: Field[];
+  outputFields: Field[];
+}
+
+export interface Trigger {
+  key: string;
+  name: string;
+  description: string;
+  appKey: string;
+  type: "instant" | "polling" | "webhook";
+  outputFields: Field[];
+}
+
+export interface Field {
+  key: string;
+  label: string;
+  type:
+    | "string"
+    | "number"
+    | "boolean"
+    | "datetime"
+    | "file"
+    | "object"
+    | "array";
+  required: boolean;
+  description?: string;
+  choices?: Choice[];
+}
+
+export interface Choice {
+  value: string | number;
+  label: string;
+}
+
+export interface ActionExecutionResult {
+  success: boolean;
+  data?: any;
+  error?: string;
+  metadata?: {
+    executionTime?: number;
+    requestId?: string;
+  };
+}
+
+export interface ActionField {
+  key: string;
+  label?: string;
+  required: boolean;
+  type?: string;
+  helpText?: string;
+  helpTextHtml?: string;
+  choices?: ActionFieldChoice[];
+  default?: string;
+  placeholder?: string;
+  computed?: boolean;
+  customField?: boolean;
+  dependsOn?: string[];
+  format?: string;
+  inputFormat?: string[];
+}
+
+export interface ActionFieldChoice {
+  value: string | number;
+  label: string;
+}
+
+export interface NeedsRequest {
+  selected_api: string;
+  action: string;
+  type_of: string;
+  authentication_id?: number;
+  params?: Record<string, any>;
+}
+
+export interface NeedsResponse {
+  success: boolean;
+  needs?: ActionField[];
+  errors?: string[];
+}
+
+export interface Authentication {
+  id: number;
+  date: string;
+  lastchanged?: string;
+  account_id: number;
+  customuser_id?: number;
+  selected_api: string;
+  destination_selected_api?: string | null;
+  is_invite_only: boolean;
+  is_private: boolean;
+  shared_with_all: boolean;
+  is_stale?: string;
+  is_shared?: string;
+  marked_stale_at?: string | null;
+  label?: string | null;
+  identifier?: string | null;
+  title?: string | null;
+  url?: string;
+  groups?: string;
+  members?: string;
+  permissions?: Record<string, boolean>;
+}
+
+export interface AuthenticationsResponse {
+  count: number;
+  next?: string | null;
+  previous?: string | null;
+  results: Authentication[];
+}

package/src/functions/{bundleCode.ts → bundleCode/index.ts}

@@ -1,11 +1,4 @@
-export interface BundleCodeOptions {
-  input: string;
-  output?: string;
-  target?: string;
-  cjs?: boolean;
-  minify?: boolean;
-  string?: boolean;
-}
+import type { BundleCodeOptions } from "./schemas";
 
 /**
  * Bundle TypeScript code into executable JavaScript

package/src/functions/bundleCode/info.ts

@@ -0,0 +1,9 @@
+import { bundleCode } from "./index";
+import { BundleCodeSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const bundleCodeInfo = {
+  name: bundleCode.name,
+  inputSchema: BundleCodeSchema,
+  implementation: bundleCode,
+};

package/src/functions/bundleCode/schemas.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import { OutputPropertySchema } from "../../types/properties";
+
+// Pure Zod schema - no resolver metadata!
+export const BundleCodeSchema = z
+  .object({
+    input: z.string().min(1).describe("Input TypeScript file path to bundle"),
+    output: OutputPropertySchema.optional().describe(
+      "Output file path (defaults to input with .js extension)",
+    ),
+    string: z
+      .boolean()
+      .default(false)
+      .describe("Return bundled code as string instead of writing to file"),
+    minify: z.boolean().default(false).describe("Minify the bundled output"),
+    target: z.string().default("es2017").describe("ECMAScript target version"),
+    cjs: z
+      .boolean()
+      .default(false)
+      .describe("Output CommonJS format instead of ESM"),
+  })
+  .describe("Bundle TypeScript code into executable JavaScript");
+
+// Type inferred from schema (no additional function config needed for bundleCode)
+export type BundleCodeOptions = z.infer<typeof BundleCodeSchema>;
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface BundleCodeSdkFunction {
+  bundleCode: (options: BundleCodeOptions) => Promise<string>;
+}

package/src/functions/{generateTypes.ts → generateTypes/index.ts}

@@ -1,12 +1,7 @@
-import type { Action, ActionField, FunctionConfig } from "../types";
-import { listActions } from "./listActions";
-import { listFields } from "./listFields";
-
-export interface GenerateTypesOptions extends FunctionConfig {
-  appKey: string;
-  authId?: number;
-  output?: string;
-}
+import type { Action, ActionField } from "../../types/domain";
+import { listActions } from "../listActions";
+import { listFields } from "../listFields";
+import type { GenerateTypesOptions } from "./schemas";
 
 interface ActionWithActionFields extends Omit<Action, "inputFields"> {
   inputFields: ActionField[];
@@ -18,13 +13,17 @@ interface ActionWithActionFields extends Omit<Action, "inputFields"> {
  * This function can be used standalone without instantiating a full SDK,
  * which enables better tree-shaking in applications that only need this functionality.
  *
- * @param options - App key, auth ID, output path, and API configuration options
+ * @param options - App key, authentication ID, output path, and API configuration options
  * @returns Promise<string> - Generated TypeScript code
  */
 export async function generateTypes(
   options: GenerateTypesOptions,
 ): Promise<string> {
-  const { appKey, authId, output = `./types/${appKey}.d.ts` } = options;
+  const {
+    appKey,
+    authenticationId,
+    output = `./types/${appKey}.d.ts`,
+  } = options;
 
   // Parse app identifier (support app@version format)
   const { app, version } = parseAppIdentifier(appKey);
@@ -51,15 +50,15 @@ export async function generateTypes(
   // Fetch input fields for each action
   const actionsWithFields: ActionWithActionFields[] = [];
 
-  if (authId) {
+  if (authenticationId) {
     for (const action of actions) {
       try {
         const fields = await listFields({
           ...options,
-          app: action.appKey,
-          action: action.key,
-          type: action.type,
-          authId: authId,
+          appKey: action.appKey,
+          actionKey: action.key,
+          actionType: action.type,
+          authenticationId: authenticationId,
         });
         actionsWithFields.push({ ...action, inputFields: fields });
       } catch {
@@ -137,8 +136,15 @@ ${versionComment}
  * Generated on: ${new Date().toISOString()}
  * 
  * Usage:
- *   import type { ${appName}Actions } from './path/to/this/file'
- *   const sdk: ActionsSdk & { actions: ${appName}Actions } = createActionsSdk(...)
+ *   import type { ${appName}Sdk } from './path/to/this/file'
+ *   const sdk = createZapierSdk() as unknown as ${appName}Sdk
+ *   
+ *   // Direct usage (per-call auth):
+ *   await sdk.apps.${appKey}.search.user_by_email({ authenticationId: 123, inputs: { email } })
+ *   
+ *   // Factory usage (pinned auth):
+ *   const my${appName} = sdk.apps.${appKey}({ authenticationId: 123 })
+ *   await my${appName}.search.user_by_email({ inputs: { email } })
  */
 
 import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
@@ -197,17 +203,28 @@ import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapi
     output += `}\n\n`;
   });
 
-  // Generate the main app actions interface
-  output += `export interface ${appName}Actions {\n`;
-  output += `  run: {\n`;
-  output += `    ${appKey}: {\n`;
+  // Generate the main app SDK interface with factory pattern support
 
+  // Generate the app proxy interface (actions grouped by type)
+  output += `interface ${appName}AppProxy {\n`;
   Object.keys(actionsByType).forEach((actionType) => {
     const typeName = `${appName}${capitalize(actionType)}Actions`;
-    output += `      ${actionType}: ${typeName}\n`;
+    output += `  ${actionType}: ${typeName}\n`;
   });
+  output += `}\n\n`;
+
+  // Generate the factory function interface
+  output += `interface ${appName}AppFactory {\n`;
+  output += `  (options: { authenticationId: number }): ${appName}AppProxy\n`;
+  output += `}\n\n`;
 
-  output += `    }\n`;
+  // Combine factory and direct access
+  output += `type ${appName}AppWithFactory = ${appName}AppFactory & ${appName}AppProxy\n\n`;
+
+  // Generate the main SDK interface
+  output += `export interface ${appName}Sdk {\n`;
+  output += `  apps: {\n`;
+  output += `    ${appKey}: ${appName}AppWithFactory\n`;
   output += `  }\n`;
   output += `}\n`;
 
@@ -231,11 +248,19 @@ ${versionComment}
 
 import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
 
-export interface ${appName}Actions {
-  run: {
-    ${appKey}: {
-      // No actions available
-    }
+interface ${appName}AppProxy {
+  // No actions available
+}
+
+interface ${appName}AppFactory {
+  (options: { authenticationId: number }): ${appName}AppProxy
+}
+
+type ${appName}AppWithFactory = ${appName}AppFactory & ${appName}AppProxy
+
+export interface ${appName}Sdk {
+  apps: {
+    ${appKey}: ${appName}AppWithFactory
   }
 }
 `;
@@ -247,12 +272,26 @@ function capitalize(str: string): string {
 
 function sanitizeActionName(actionKey: string): string {
   // Ensure the action name is a valid TypeScript identifier
-  return actionKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+  let sanitized = actionKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+
+  // If it starts with a number, prepend an underscore
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+
+  return sanitized;
 }
 
 function sanitizeFieldName(fieldKey: string): string {
   // Ensure the field name is a valid TypeScript identifier
-  return fieldKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+  let sanitized = fieldKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+
+  // If it starts with a number, prepend an underscore
+  if (/^[0-9]/.test(sanitized)) {
+    sanitized = "_" + sanitized;
+  }
+
+  return sanitized;
 }
 
 function escapeComment(comment: string): string {

package/src/functions/generateTypes/info.ts

@@ -0,0 +1,9 @@
+import { generateTypes } from "./index";
+import { GenerateTypesSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const generateTypesInfo = {
+  name: generateTypes.name,
+  inputSchema: GenerateTypesSchema,
+  implementation: generateTypes,
+};

package/src/functions/generateTypes/schemas.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  AuthenticationIdPropertySchema,
+  OutputPropertySchema,
+  DebugPropertySchema,
+} from "../../types/properties";
+
+// Pure Zod schema - no resolver metadata!
+export const GenerateTypesSchema = z
+  .object({
+    appKey: AppKeyPropertySchema.describe("App key to generate SDK code for"),
+    authenticationId: AuthenticationIdPropertySchema.optional(),
+    output: OutputPropertySchema.optional().describe(
+      "Output file path (defaults to generated/<appKey>.ts)",
+    ),
+    debug: DebugPropertySchema.describe(
+      "Enable debug logging during generation",
+    ),
+  })
+  .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;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GenerateTypesSdkFunction {
+  generateTypes: (options: GenerateTypesOptions) => Promise<string>;
+}

package/src/functions/{getAction.ts → getAction/index.ts}

@@ -1,11 +1,6 @@
-import type { Action, FunctionConfig } from "../types";
-import { listActions } from "./listActions";
-
-export interface GetActionOptions extends FunctionConfig {
-  app: string;
-  action: string;
-  type: string;
-}
+import type { Action } from "../../types/domain";
+import { listActions } from "../listActions";
+import type { GetActionOptions } from "./schemas";
 
 /**
  * Get a specific action by app, action key, and type
@@ -17,18 +12,22 @@ export interface GetActionOptions extends FunctionConfig {
  * @returns Promise<Action>
  */
 export async function getAction(options: GetActionOptions): Promise<Action> {
-  const { app, action: actionKey, type } = options;
+  const { appKey, actionKey, actionType } = options;
 
   const actions = await listActions({
     ...options,
-    appKey: app,
+    appKey: appKey,
   });
 
-  const action = actions.find((a) => a.key === actionKey && a.type === type);
+  const action = actions.find(
+    (a) => a.key === actionKey && a.type === actionType,
+  );
 
   if (!action) {
-    throw new Error(`Action not found: ${actionKey} with type ${type}`);
+    throw new Error(`Action not found: ${actionKey} with type ${actionType}`);
   }
 
   return action;
 }
+
+// No registry info here - moved to info.ts for proper tree-shaking

package/src/functions/getAction/info.ts

@@ -0,0 +1,9 @@
+import { getAction } from "./index";
+import { GetActionSchema } from "./schemas";
+
+// Function registry info - imports both function and schema
+export const getActionInfo = {
+  name: getAction.name,
+  inputSchema: GetActionSchema,
+  implementation: getAction,
+};

package/src/functions/getAction/schemas.ts

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  ActionTypePropertySchema,
+  ActionKeyPropertySchema,
+} from "../../types/properties";
+import type { Action } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const GetActionSchema = z
+  .object({
+    appKey: AppKeyPropertySchema,
+    actionType: ActionTypePropertySchema,
+    actionKey: ActionKeyPropertySchema,
+  })
+  .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;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GetActionSdkFunction {
+  getAction: (options: GetActionOptions) => Promise<Action>;
+}