@zapier/zapier-sdk 0.0.2 → 0.0.3

package/src/functions/generateTypes.ts

@@ -0,0 +1,309 @@
+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;
+}
+
+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, auth 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;
+
+  // 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 (authId) {
+    for (const action of actions) {
+      try {
+        const fields = await listFields({
+          ...options,
+          app: action.appKey,
+          action: action.key,
+          type: action.type,
+          authId: authId,
+        });
+        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}Actions } from './path/to/this/file'
+ *   const sdk: ActionsSdk & { actions: ${appName}Actions } = createActionsSdk(...)
+ */
+
+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 actions interface
+  output += `export interface ${appName}Actions {\n`;
+  output += `  run: {\n`;
+  output += `    ${appKey}: {\n`;
+
+  Object.keys(actionsByType).forEach((actionType) => {
+    const typeName = `${appName}${capitalize(actionType)}Actions`;
+    output += `      ${actionType}: ${typeName}\n`;
+  });
+
+  output += `    }\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'
+
+export interface ${appName}Actions {
+  run: {
+    ${appKey}: {
+      // No actions available
+    }
+  }
+}
+`;
+}
+
+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
+  return actionKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+}
+
+function sanitizeFieldName(fieldKey: string): string {
+  // Ensure the field name is a valid TypeScript identifier
+  return fieldKey.replace(/[^a-zA-Z0-9_$]/g, "_");
+}
+
+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/getAction.ts

@@ -0,0 +1,34 @@
+import type { Action, FunctionConfig } from "../types";
+import { listActions } from "./listActions";
+
+export interface GetActionOptions extends FunctionConfig {
+  app: string;
+  action: string;
+  type: string;
+}
+
+/**
+ * Get a specific action by app, action key, and type
+ *
+ * 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, action key, type, and API configuration options
+ * @returns Promise<Action>
+ */
+export async function getAction(options: GetActionOptions): Promise<Action> {
+  const { app, action: actionKey, type } = options;
+
+  const actions = await listActions({
+    ...options,
+    appKey: app,
+  });
+
+  const action = actions.find((a) => a.key === actionKey && a.type === type);
+
+  if (!action) {
+    throw new Error(`Action not found: ${actionKey} with type ${type}`);
+  }
+
+  return action;
+}

package/src/functions/getApp.ts

@@ -0,0 +1,47 @@
+import { getOrCreateApiClient } from "../api";
+import type { Integration, FunctionConfig } from "../types";
+
+export interface GetAppOptions extends FunctionConfig {
+  key: string;
+}
+
+/**
+ * Get a specific app by key
+ *
+ * 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 and API configuration options
+ * @returns Promise<Integration>
+ */
+export async function getApp(options: GetAppOptions): Promise<Integration> {
+  const api = getOrCreateApiClient(options);
+
+  const { key } = options;
+
+  const app = await api.get(`/api/v4/apps/${key}/`, {
+    customErrorHandler: (response) => {
+      if (response.status === 404) {
+        const AppNotFoundError = class extends Error {
+          constructor(appKey: string) {
+            super(`App not found: ${appKey}`);
+            this.name = "AppNotFoundError";
+          }
+        };
+        return new AppNotFoundError(key);
+      }
+      return undefined;
+    },
+  });
+
+  return {
+    key: app.slug,
+    name: app.name,
+    description: app.description,
+    version: "1.0.0",
+    category: app.category?.name,
+    actions: [],
+    triggers: [],
+    current_implementation_id: app.current_implementation_id,
+  };
+}

package/src/functions/listActions.ts

@@ -0,0 +1,151 @@
+import { getOrCreateApiClient } from "../api";
+import type { Action, FunctionConfig } from "../types";
+import { getApp } from "./getApp";
+
+export interface ListActionsOptions extends FunctionConfig {
+  appKey?: string;
+  type?: string;
+}
+
+/**
+ * List available actions with optional filtering
+ *
+ * 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 - Filtering and API configuration options
+ * @returns Promise<Action[]> with pagination metadata
+ */
+export async function listActions(
+  options: ListActionsOptions = {},
+): Promise<Action[]> {
+  const api = getOrCreateApiClient(options);
+
+  // If filtering by appKey, use optimized approach with selected_apis parameter
+  if (options.appKey) {
+    try {
+      // Use the standalone getApp function
+      const appData = await getApp({
+        key: options.appKey,
+        api,
+        token: options.token,
+        baseUrl: options.baseUrl,
+        debug: options.debug,
+        fetch: options.fetch,
+      });
+
+      // Extract implementation name from current_implementation_id (e.g., "SlackCLIAPI@1.20.0" -> "SlackCLIAPI")
+      const implementationId = appData.current_implementation_id?.split("@")[0];
+      if (!implementationId) {
+        throw new Error("No current_implementation_id found for app");
+      }
+
+      const searchParams = {
+        global: "true",
+        public_only: "true",
+        selected_apis: implementationId,
+      };
+
+      const data = await api.get("/api/v4/implementations/", {
+        searchParams,
+      });
+      const actions: Action[] = [];
+
+      // Transform implementations to actions
+      for (const implementation of data.results || []) {
+        if (implementation.actions) {
+          for (const action of implementation.actions) {
+            const transformedAction: Action = {
+              key: action.key,
+              name: action.name || action.label,
+              description: action.description || "",
+              appKey: implementation.slug || "",
+              type: action.type || action.type_of || "read",
+              inputFields: [], // Would need additional API call for detailed fields
+              outputFields: [],
+            };
+
+            // Apply type filter if provided
+            if (options?.type && transformedAction.type !== options.type) {
+              continue;
+            }
+
+            actions.push(transformedAction);
+          }
+        }
+      }
+
+      // Add pagination metadata for app-specific queries
+      if (actions.length > 0) {
+        (actions as any).__pagination = {
+          count: data.count,
+          hasNext: !!data.next,
+          hasPrevious: !!data.previous,
+          nextUrl: data.next,
+          previousUrl: data.previous,
+        };
+      }
+
+      return actions;
+    } catch (error) {
+      // If it's an AppNotFoundError, don't try fallback - just re-throw
+      if (error instanceof Error && error.name === "AppNotFoundError") {
+        throw error;
+      }
+      // Fallback to original approach if optimized approach fails
+      console.warn(
+        "Optimized app lookup failed, falling back to full scan:",
+        error,
+      );
+    }
+  }
+
+  // Original approach for general queries or when optimization fails
+  const searchParams = {
+    global: "true",
+    public_only: "true",
+  };
+
+  const data = await api.get("/api/v4/implementations/", { searchParams });
+  const actions: Action[] = [];
+
+  // Transform implementations to actions
+  for (const implementation of data.results || []) {
+    if (implementation.actions) {
+      for (const action of implementation.actions) {
+        const transformedAction: Action = {
+          key: action.key,
+          name: action.name || action.label,
+          description: action.description || "",
+          appKey: implementation.slug || "",
+          type: action.type || action.type_of || "read",
+          inputFields: [], // Would need additional API call for detailed fields
+          outputFields: [],
+        };
+
+        // Apply filters
+        if (options?.appKey && transformedAction.appKey !== options.appKey) {
+          continue;
+        }
+        if (options?.type && transformedAction.type !== options.type) {
+          continue;
+        }
+
+        actions.push(transformedAction);
+      }
+    }
+  }
+
+  // Add pagination metadata for general queries
+  if (actions.length > 0) {
+    (actions as any).__pagination = {
+      count: data.count,
+      hasNext: !!data.next,
+      hasPrevious: !!data.previous,
+      nextUrl: data.next,
+      previousUrl: data.previous,
+    };
+  }
+
+  return actions;
+}

package/src/functions/listApps.ts

@@ -0,0 +1,65 @@
+import { getOrCreateApiClient } from "../api";
+import type { Integration, FunctionConfig } from "../types";
+
+export interface ListAppsOptions extends FunctionConfig {
+  category?: string;
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * List available apps with optional filtering
+ *
+ * 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 - Filtering, pagination, and API configuration options
+ * @returns Promise<Integration[]> with pagination metadata
+ */
+export async function listApps(
+  options: ListAppsOptions = {},
+): Promise<Integration[]> {
+  const api = getOrCreateApiClient(options);
+
+  // Build search parameters
+  const searchParams: Record<string, string> = {};
+  if (options.category) {
+    searchParams.category = options.category;
+  }
+  if (options.limit) {
+    searchParams.limit = options.limit.toString();
+  }
+  if (options.offset) {
+    searchParams.offset = options.offset.toString();
+  }
+
+  const data = await api.get("/api/v4/apps/", { searchParams });
+
+  // Transform API response to our Integration interface
+  const apps =
+    data.results?.map(
+      (app: any): Integration => ({
+        key: app.slug,
+        name: app.name,
+        description: app.description,
+        version: "1.0.0", // API doesn't provide version
+        category: app.category?.name,
+        actions: [], // Will be populated separately
+        triggers: [],
+        current_implementation_id: app.current_implementation_id,
+      }),
+    ) || [];
+
+  // Add pagination metadata to the response
+  if (apps.length > 0) {
+    (apps as any).__pagination = {
+      count: data.count,
+      hasNext: !!data.next,
+      hasPrevious: !!data.previous,
+      nextUrl: data.next,
+      previousUrl: data.previous,
+    };
+  }
+
+  return apps;
+}