@zapier/zapier-sdk 0.0.2 → 0.1.0

package/src/functions/getAction/index.ts

@@ -0,0 +1,33 @@
+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
+ *
+ * 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 { appKey, actionKey, actionType } = options;
+
+  const actions = await listActions({
+    ...options,
+    appKey: appKey,
+  });
+
+  const action = actions.find(
+    (a) => a.key === actionKey && a.type === actionType,
+  );
+
+  if (!action) {
+    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>;
+}

package/src/functions/getApp/index.ts

@@ -0,0 +1,41 @@
+import { getOrCreateApiClient } from "../../api";
+import type { Integration } from "../../types/domain";
+import { AppNotFoundError } from "../../types/domain";
+import type { GetAppOptions } from "./schemas";
+
+/**
+ * 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 { appKey } = options;
+
+  const app = await api.get(`/api/v4/apps/${appKey}/`, {
+    customErrorHandler: (response) => {
+      if (response.status === 404) {
+        return new AppNotFoundError(appKey);
+      }
+      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,
+  };
+}
+
+// No registry info here - moved to info.ts for proper tree-shaking

package/src/functions/getApp/info.ts

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

package/src/functions/getApp/schemas.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { AppKeyPropertySchema } from "../../types/properties";
+import type { Integration } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const GetAppSchema = z
+  .object({
+    appKey: AppKeyPropertySchema.describe(
+      "App key or slug to fetch (e.g., google-sheets, slack, github)",
+    ),
+  })
+  .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;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GetAppSdkFunction {
+  getApp: (options: GetAppOptions) => Promise<Integration>;
+}

package/src/functions/listActions/index.ts

@@ -0,0 +1,149 @@
+import { getOrCreateApiClient } from "../../api";
+import type { Action } from "../../types/domain";
+import { getApp } from "../getApp";
+import type { ListActionsOptions } from "./schemas";
+
+/**
+ * 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: Partial<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({
+        appKey: 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;
+}
+
+// No registry info here - moved to info.ts for proper tree-shaking

package/src/functions/listActions/info.ts

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

package/src/functions/listActions/schemas.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  ActionTypePropertySchema,
+} from "../../types/properties";
+import { withOutputSchema } from "../../schema-utils";
+import { ActionItemSchema } from "../../schemas/Action";
+import type { Action } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const ListActionsSchema = withOutputSchema(
+  z
+    .object({
+      appKey: AppKeyPropertySchema.optional(),
+      type: ActionTypePropertySchema.optional().describe(
+        "Filter actions by type",
+      ),
+    })
+    .describe("List all actions for a specific app"),
+  ActionItemSchema,
+);
+
+// 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;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface ListActionsSdkFunction {
+  listActions: (options?: Partial<ListActionsOptions>) => Promise<Action[]>;
+}

package/src/functions/listApps/index.ts

@@ -0,0 +1,60 @@
+import { getOrCreateApiClient } from "../../api";
+import type { Integration } from "../../types/domain";
+import type { ListAppsOptions } from "./schemas";
+
+/**
+ * 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;
+}

package/src/functions/listApps/info.ts

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

package/src/functions/listApps/schemas.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import {
+  LimitPropertySchema,
+  OffsetPropertySchema,
+} from "../../types/properties";
+import { withOutputSchema } from "../../schema-utils";
+import { AppItemSchema } from "../../schemas/App";
+import type { Integration } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const ListAppsSchema = withOutputSchema(
+  z
+    .object({
+      category: z.string().optional().describe("Filter apps by category"),
+      limit: LimitPropertySchema.optional().describe(
+        "Maximum number of items to return (1-200)",
+      ),
+      offset: OffsetPropertySchema.optional().describe(
+        "Number of items to skip for pagination",
+      ),
+    })
+    .describe("List all available apps with optional filtering"),
+  AppItemSchema,
+);
+
+// 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;
+};
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface ListAppsSdkFunction {
+  listApps: (options?: Partial<ListAppsOptions>) => Promise<Integration[]>;
+}

package/src/functions/listAuths/index.ts

@@ -0,0 +1,153 @@
+import { getOrCreateApiClient } from "../../api";
+import type {
+  Authentication,
+  AuthenticationsResponse,
+} from "../../types/domain";
+import { getApp } from "../getApp";
+import type { ListAuthsOptions } from "./schemas";
+
+/**
+ * List available authentications 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<Authentication[]> with pagination metadata
+ */
+export async function listAuths(
+  options: Partial<ListAuthsOptions> = {},
+): Promise<Authentication[]> {
+  const { token } = options;
+
+  if (!token && !process.env.ZAPIER_TOKEN) {
+    throw new Error(
+      "Authentication token is required to list authentications. Please provide token in options or set ZAPIER_TOKEN environment variable.",
+    );
+  }
+
+  const api = getOrCreateApiClient(options);
+
+  // Local function to handle the actual API fetching
+  const listAuthsInternal = async (
+    options: ListAuthsOptions = {},
+  ): Promise<Authentication[]> => {
+    // Build search parameters
+    const searchParams: Record<string, string> = {};
+
+    // Handle appKey filtering by getting the selected_api first
+    if (options.appKey) {
+      try {
+        // Use the standalone getApp function
+        const app = await getApp({
+          appKey: options.appKey,
+          api,
+          token: options.token,
+          baseUrl: options.baseUrl,
+          debug: options.debug,
+          fetch: options.fetch,
+        });
+        const selectedApi = app.current_implementation_id;
+        if (selectedApi) {
+          // Use versionless_selected_api to find auths across all app versions
+          // Extract the base name without the version (e.g., "SlackCLIAPI" from "SlackCLIAPI@1.21.1")
+          const versionlessApi = selectedApi.split("@")[0];
+          searchParams.versionless_selected_api = versionlessApi;
+        }
+      } catch (error) {
+        // If it's an AppNotFoundError, re-throw it
+        if (error instanceof Error && error.name === "AppNotFoundError") {
+          throw error;
+        }
+        // For other errors, continue without app filtering
+        console.warn(
+          `Warning: Could not filter by app ${options.appKey}:`,
+          error instanceof Error ? error.message : "Unknown error",
+        );
+      }
+    }
+
+    // Add other query parameters if provided
+    if (options.account_id) {
+      searchParams.account_id = options.account_id;
+    }
+    if (options.owner) {
+      searchParams.owner = options.owner;
+    }
+    if (options.limit) {
+      searchParams.limit = options.limit.toString();
+    }
+    if (options.offset) {
+      searchParams.offset = options.offset.toString();
+    }
+
+    const data: AuthenticationsResponse = await api.get(
+      "/api/v4/authentications/",
+      {
+        searchParams,
+        customErrorHandler: (response) => {
+          if (response.status === 401) {
+            return new Error(
+              `Authentication failed. Your token may not have permission to access authentications or may be expired. (HTTP ${response.status})`,
+            );
+          }
+          if (response.status === 403) {
+            return new Error(
+              `Access forbidden. Your token may not have the required scopes to list authentications. (HTTP ${response.status})`,
+            );
+          }
+          return undefined;
+        },
+      },
+    );
+
+    // Transform API response
+    const auths = data.results || [];
+
+    // Add pagination metadata to the response
+    if (auths.length > 0) {
+      (auths as any).__pagination = {
+        count: data.count,
+        hasNext: !!data.next,
+        hasPrevious: !!data.previous,
+        nextUrl: data.next,
+        previousUrl: data.previous,
+      };
+    }
+
+    return auths;
+  };
+
+  // If a limit is provided and no specific owner filter, prioritize owned auths
+  if (options.limit && options.owner === undefined) {
+    // First get owned auths
+    const ownedAuths = await listAuthsInternal({
+      ...options,
+      owner: "me",
+    });
+
+    // If we have enough owned auths, just slice and return
+    if (ownedAuths.length >= options.limit) {
+      return ownedAuths.slice(0, options.limit);
+    }
+
+    // Get all auths up to the original limit to fill remaining slots
+    const allAuths = await listAuthsInternal({
+      ...options,
+      owner: undefined,
+    });
+
+    // Filter out auths the user already owns to avoid duplicates
+    const ownedAuthenticationIds = new Set(ownedAuths.map((auth) => auth.id));
+    const additionalAuths = allAuths.filter(
+      (auth) => !ownedAuthenticationIds.has(auth.id),
+    );
+
+    // Combine and slice to the requested limit
+    const combined = [...ownedAuths, ...additionalAuths];
+    return combined.slice(0, options.limit);
+  }
+
+  // Standard implementation for non-prioritized requests
+  return listAuthsInternal(options);
+}

package/src/functions/listAuths/info.ts

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