@zapier/zapier-sdk 0.0.2 → 0.1.0

package/src/{types.ts → api/types.ts}

@@ -1,3 +1,54 @@
+/**
+ * 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;
@@ -49,19 +100,6 @@ export interface Choice {
   label: string;
 }
 
-export interface ListOptions {
-  category?: string;
-  appKey?: string;
-  type?: string;
-  limit?: number;
-  offset?: number;
-}
-
-export interface ActionExecutionOptions {
-  inputs?: Record<string, any>;
-  authId?: number;
-}
-
 export interface ActionExecutionResult {
   success: boolean;
   data?: any;
@@ -108,40 +146,6 @@ export interface NeedsResponse {
   errors?: string[];
 }
 
-// Future extensibility types
-export interface Workflow {
-  id: string;
-  name: string;
-  description: string;
-  steps: WorkflowStep[];
-}
-
-export interface WorkflowStep {
-  id: string;
-  type: "trigger" | "action";
-  appKey: string;
-  actionKey?: string;
-  triggerKey?: string;
-}
-
-export interface Interface {
-  key: string;
-  name: string;
-  fields: Field[];
-}
-
-export interface Table {
-  key: string;
-  name: string;
-  columns: TableColumn[];
-}
-
-export interface TableColumn {
-  key: string;
-  name: string;
-  type: string;
-}
-
 export interface Authentication {
   id: number;
   date: string;
@@ -171,74 +175,3 @@ export interface AuthenticationsResponse {
   previous?: string | null;
   results: Authentication[];
 }
-
-export interface AuthenticationListOptions {
-  account_id?: string;
-  owner?: string;
-  appKey?: string;
-  limit?: number;
-  offset?: number;
-}
-
-// Custom error classes for better error handling
-export class ZapierSdkError extends Error {
-  constructor(
-    message: string,
-    public code?: string,
-  ) {
-    super(message);
-    this.name = "ZapierSdkError";
-  }
-}
-
-export class AppNotFoundError extends ZapierSdkError {
-  constructor(appKey: string) {
-    super(`App "${appKey}" not found`);
-    this.name = "AppNotFoundError";
-    this.code = "APP_NOT_FOUND";
-  }
-}
-
-export class ActionNotFoundError extends ZapierSdkError {
-  constructor(appKey: string, actionKey: string) {
-    super(`Action "${actionKey}" not found in app "${appKey}"`);
-    this.name = "ActionNotFoundError";
-    this.code = "ACTION_NOT_FOUND";
-  }
-}
-
-export class AuthenticationError extends ZapierSdkError {
-  constructor(message: string) {
-    super(message);
-    this.name = "AuthenticationError";
-    this.code = "AUTHENTICATION_ERROR";
-  }
-}
-
-// Auth configuration types
-export interface AuthObject {
-  id: number;
-}
-
-// Common SDK interfaces
-export interface BaseSdkOptions {
-  token?: string;
-  authentications?: {
-    [appKey: string]: AuthObject[];
-  };
-  fetch?: typeof fetch;
-  baseUrl?: string;
-  debug?: boolean;
-}
-
-export interface CombinedSdk {
-  [namespace: string]: any;
-}
-
-// Factory function type for creating individual SDKs
-export type SdkFactory<T = any> = (options: BaseSdkOptions) => T;
-
-// Utility function to combine multiple SDKs
-export function combineSdks(sdks: Record<string, any>): CombinedSdk {
-  return { ...sdks };
-}

package/src/functions/bundleCode/index.ts

@@ -0,0 +1,78 @@
+import type { BundleCodeOptions } from "./schemas";
+
+/**
+ * Bundle TypeScript code into executable JavaScript
+ *
+ * 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 - Bundling configuration options
+ * @returns Promise<string> - Bundled JavaScript code
+ */
+export async function bundleCode(options: BundleCodeOptions): Promise<string> {
+  const {
+    input,
+    output,
+    target = "es2020",
+    cjs = false,
+    minify = false,
+    string: returnString = false,
+  } = options;
+
+  // Dynamically import esbuild
+  const { buildSync } = await import("esbuild");
+  const fs = await import("fs");
+  const path = await import("path");
+
+  // Resolve input path
+  const resolvedInput = path.resolve(process.cwd(), input);
+
+  try {
+    // Bundle with esbuild
+    const result = buildSync({
+      entryPoints: [resolvedInput],
+      bundle: true,
+      platform: "node",
+      target: target,
+      format: cjs ? "cjs" : "esm",
+      minify: minify,
+      write: false,
+      external: [], // Bundle everything
+      banner: {
+        js: "#!/usr/bin/env node",
+      },
+    });
+
+    if (result.errors.length > 0) {
+      throw new Error(
+        `Bundle failed: ${result.errors.map((e) => e.text).join(", ")}`,
+      );
+    }
+
+    const bundledCode = result.outputFiles?.[0]?.text;
+    if (!bundledCode) {
+      throw new Error("No output generated");
+    }
+
+    let finalOutput = bundledCode;
+
+    if (returnString) {
+      // Output as quoted string for node -e using JSON.stringify
+      finalOutput = JSON.stringify(bundledCode);
+    }
+
+    // Write to file if output path specified
+    if (output) {
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, finalOutput, "utf8");
+    }
+
+    return finalOutput;
+  } catch (error) {
+    throw new Error(
+      `Bundle failed: ${
+        error instanceof Error ? error.message : "Unknown error"
+      }`,
+    );
+  }
+}

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/index.ts

@@ -0,0 +1,348 @@
+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[];
+}
+
+/**
+ * Generate TypeScript types for a specific app
+ *
+ * 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, authentication ID, output path, and API configuration options
+ * @returns Promise<string> - Generated TypeScript code
+ */
+export async function generateTypes(
+  options: GenerateTypesOptions,
+): Promise<string> {
+  const {
+    appKey,
+    authenticationId,
+    output = `./types/${appKey}.d.ts`,
+  } = options;
+
+  // Parse app identifier (support app@version format)
+  const { app, version } = parseAppIdentifier(appKey);
+
+  // Fetch all actions for the app
+  const actions = await listActions({
+    ...options,
+    appKey: app,
+  });
+
+  if (actions.length === 0) {
+    const typeDefinitions = generateEmptyTypesFile(app, version);
+
+    if (output) {
+      const fs = await import("fs");
+      const path = await import("path");
+      fs.mkdirSync(path.dirname(output), { recursive: true });
+      fs.writeFileSync(output, typeDefinitions, "utf8");
+    }
+
+    return typeDefinitions;
+  }
+
+  // Fetch input fields for each action
+  const actionsWithFields: ActionWithActionFields[] = [];
+
+  if (authenticationId) {
+    for (const action of actions) {
+      try {
+        const fields = await listFields({
+          ...options,
+          appKey: action.appKey,
+          actionKey: action.key,
+          actionType: action.type,
+          authenticationId: authenticationId,
+        });
+        actionsWithFields.push({ ...action, inputFields: fields });
+      } catch {
+        // If we can't get fields for an action, include it without fields
+        actionsWithFields.push({ ...action, inputFields: [] });
+      }
+    }
+  } else {
+    // Convert actions to have empty input fields (will generate generic types)
+    actions.forEach((action) => {
+      actionsWithFields.push({ ...action, inputFields: [] });
+    });
+  }
+
+  // Generate TypeScript types
+  const typeDefinitions = generateTypeDefinitions(
+    app,
+    actionsWithFields,
+    version,
+  );
+
+  // Write to file if output path specified
+  if (output) {
+    const fs = await import("fs");
+    const path = await import("path");
+    fs.mkdirSync(path.dirname(output), { recursive: true });
+    fs.writeFileSync(output, typeDefinitions, "utf8");
+  }
+
+  return typeDefinitions;
+}
+
+function parseAppIdentifier(identifier: string): {
+  app: string;
+  version?: string;
+} {
+  const parts = identifier.split("@");
+  return {
+    app: parts[0],
+    version: parts[1],
+  };
+}
+
+function generateTypeDefinitions(
+  appKey: string,
+  actions: ActionWithActionFields[],
+  version?: string,
+): string {
+  // Handle empty actions
+  if (actions.length === 0) {
+    return generateEmptyTypesFile(appKey, version);
+  }
+
+  // Group actions by type
+  const actionsByType = actions.reduce(
+    (acc, action) => {
+      if (!acc[action.type]) {
+        acc[action.type] = [];
+      }
+      acc[action.type].push(action);
+      return acc;
+    },
+    {} as Record<string, ActionWithActionFields[]>,
+  );
+
+  const appName = capitalize(appKey);
+  const versionComment = version
+    ? ` * Generated for ${appKey}@${version}`
+    : ` * Generated for ${appKey}`;
+
+  let output = `/* eslint-disable @typescript-eslint/naming-convention */
+/**
+ * Auto-generated TypeScript types for Zapier ${appKey} actions
+${versionComment}
+ * Generated on: ${new Date().toISOString()}
+ * 
+ * Usage:
+ *   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'
+
+`;
+
+  // Generate input types for each action
+  actions.forEach((action) => {
+    if (action.inputFields.length > 0) {
+      const inputTypeName = `${appName}${capitalize(action.type)}${capitalize(
+        sanitizeActionName(action.key),
+      )}Inputs`;
+
+      output += `interface ${inputTypeName} {\n`;
+
+      action.inputFields.forEach((field) => {
+        const isOptional = !field.required;
+        const fieldType = mapFieldTypeToTypeScript(field);
+        const description = field.helpText
+          ? `  /** ${escapeComment(field.helpText)} */\n`
+          : "";
+
+        output += `${description}  ${sanitizeFieldName(field.key)}${
+          isOptional ? "?" : ""
+        }: ${fieldType}\n`;
+      });
+
+      output += `}\n\n`;
+    }
+  });
+
+  // Generate action type interfaces for each action type
+  Object.entries(actionsByType).forEach(([actionType, typeActions]) => {
+    const typeName = `${appName}${capitalize(actionType)}Actions`;
+
+    output += `interface ${typeName} {\n`;
+
+    typeActions.forEach((action: ActionWithActionFields) => {
+      const actionName = sanitizeActionName(action.key);
+      const description = action.description
+        ? `  /** ${escapeComment(action.description)} */\n`
+        : "";
+
+      // Generate type-safe action method signature
+      if (action.inputFields.length > 0) {
+        const inputTypeName = `${appName}${capitalize(action.type)}${capitalize(
+          sanitizeActionName(action.key),
+        )}Inputs`;
+        output += `${description}  ${actionName}: (options: { inputs: ${inputTypeName} } & Omit<ActionExecutionOptions, 'inputs'>) => Promise<ActionExecutionResult>\n`;
+      } else {
+        // No specific input fields available - use generic Record<string, any> for inputs
+        output += `${description}  ${actionName}: (options?: { inputs?: Record<string, any> } & ActionExecutionOptions) => Promise<ActionExecutionResult>\n`;
+      }
+    });
+
+    output += `}\n\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 += `}\n\n`;
+
+  // Generate the factory function interface
+  output += `interface ${appName}AppFactory {\n`;
+  output += `  (options: { authenticationId: number }): ${appName}AppProxy\n`;
+  output += `}\n\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`;
+
+  return output;
+}
+
+function generateEmptyTypesFile(appKey: string, version?: string): string {
+  const appName = capitalize(appKey);
+  const versionComment = version
+    ? ` * Generated for ${appKey}@${version}`
+    : ` * Generated for ${appKey}`;
+
+  return `/* eslint-disable @typescript-eslint/naming-convention */
+/**
+ * Auto-generated TypeScript types for Zapier ${appKey} actions
+${versionComment}
+ * Generated on: ${new Date().toISOString()}
+ * 
+ * No actions found for this app.
+ */
+
+import type { ActionExecutionOptions, ActionExecutionResult } from '@zapier/zapier-sdk'
+
+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
+  }
+}
+`;
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1).replace(/[-_]/g, "");
+}
+
+function sanitizeActionName(actionKey: string): string {
+  // Ensure the action name is a valid TypeScript identifier
+  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
+  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 {
+  // Escape comment text to prevent breaking the JSDoc comment
+  return comment.replace(/\*\//g, "*\\/").replace(/\r?\n/g, " ");
+}
+
+function mapFieldTypeToTypeScript(field: ActionField): string {
+  // Handle choices (enum-like fields)
+  if (field.choices && field.choices.length > 0) {
+    const choiceValues = field.choices
+      .filter(
+        (choice) =>
+          choice.value !== undefined &&
+          choice.value !== null &&
+          choice.value !== "",
+      )
+      .map((choice) =>
+        typeof choice.value === "string" ? `"${choice.value}"` : choice.value,
+      );
+
+    if (choiceValues.length > 0) {
+      return choiceValues.join(" | ");
+    }
+    // If all choices were filtered out, fall through to default type handling
+  }
+
+  // Map Zapier field types to TypeScript types
+  switch (field.type?.toLowerCase()) {
+    case "string":
+    case "text":
+    case "email":
+    case "url":
+    case "password":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "datetime":
+    case "date":
+      return "string"; // ISO date strings
+    case "file":
+      return "string"; // File URL or content
+    case "array":
+      return "any[]";
+    case "object":
+      return "Record<string, any>";
+    default:
+      // Default to string for unknown types, with union for common cases
+      return "string | number | boolean";
+  }
+}

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>;
+}