@zapier/zapier-sdk 0.4.1 → 0.5.1

package/src/plugins/listActions/index.ts

@@ -0,0 +1,115 @@
+import type { Plugin, GetSdkType } from "../../types/plugin";
+import type { ApiClient } from "../../api";
+import type { ActionItem } from "../../types/domain";
+import { normalizeActionItem } from "../../utils/domain-utils";
+import {
+  ListActionsSchema,
+  type ListActionsOptions,
+  type ListActionsPage,
+} from "./schemas";
+import {
+  ZapierConfigurationError,
+  ZapierAuthenticationError,
+} from "../../types/errors";
+import { createPaginatedFunction } from "../../utils/function-utils";
+import type { GetAppPluginProvides } from "../getApp";
+
+export interface ListActionsPluginProvides {
+  listActions: (options?: ListActionsOptions) => Promise<{
+    data: ActionItem[];
+  }> &
+    AsyncIterable<{ data: ActionItem[]; nextCursor?: string }> & {
+      items(): AsyncIterable<ActionItem>;
+    };
+  context: {
+    meta: {
+      listActions: {
+        inputSchema: typeof ListActionsSchema;
+      };
+    };
+  };
+}
+
+export const listActionsPlugin: Plugin<
+  GetSdkType<GetAppPluginProvides>, // requires getApp in SDK
+  { api: ApiClient }, // requires api in context
+  ListActionsPluginProvides
+> = ({ sdk, context }) => {
+  const listActions = createPaginatedFunction(async function listActionsPage(
+    options: ListActionsOptions & { cursor?: string } & { pageSize: number },
+  ): Promise<ListActionsPage> {
+    const { api } = context;
+
+    // Use the getApp function from the SDK (dependency injection)
+    const app = await sdk.getApp({ appKey: options.appKey });
+
+    const implementationId = app.data.current_implementation_id?.split("@")[0];
+    if (!implementationId) {
+      throw new ZapierConfigurationError(
+        "No current_implementation_id found for app",
+        { configType: "current_implementation_id" },
+      );
+    }
+
+    const searchParams: Record<string, string> = {
+      global: "true",
+      public_only: "true",
+      selected_apis: implementationId,
+    };
+
+    const data = await api.get("/api/v4/implementations/", {
+      searchParams,
+      customErrorHandler: ({ status }) => {
+        if (status === 401) {
+          return new ZapierAuthenticationError(
+            `Authentication failed. Your token may not have permission to access implementations or may be expired. (HTTP ${status})`,
+            { statusCode: status },
+          );
+        }
+        if (status === 403) {
+          return new ZapierAuthenticationError(
+            `Access forbidden. Your token may not have the required scopes to list implementations. (HTTP ${status})`,
+            { statusCode: status },
+          );
+        }
+        return undefined;
+      },
+    });
+
+    let allActions: ActionItem[] = [];
+
+    for (const implementation of data.results || []) {
+      if (implementation.actions) {
+        for (const action of implementation.actions) {
+          const actionWithContext = {
+            ...action,
+            selected_api: action.selected_api || implementation.selected_api,
+          };
+          allActions.push(normalizeActionItem(actionWithContext));
+        }
+      }
+    }
+
+    if (options.actionType) {
+      allActions = allActions.filter(
+        (action) => action.action_type === options.actionType,
+      );
+    }
+
+    return {
+      data: allActions,
+      nextCursor: undefined,
+    };
+  }, ListActionsSchema);
+
+  return {
+    listActions,
+    context: {
+      meta: {
+        listActions: {
+          inputSchema: ListActionsSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/listActions/schemas.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  ActionTypePropertySchema,
+} from "../../types/properties";
+import { withOutputSchema } from "../../utils/schema-utils";
+import { ActionItemSchema } from "../../schemas/Action";
+import type { ActionItem } from "../../types/domain";
+import type { PaginatedSdkFunction } from "../../types/functions";
+
+// Pure Zod schema - no resolver metadata!
+export const ListActionsSchema = withOutputSchema(
+  z
+    .object({
+      appKey: AppKeyPropertySchema.describe(
+        "App key of actions to list (e.g., 'SlackCLIAPI')",
+      ),
+      actionType: ActionTypePropertySchema.optional().describe(
+        "Filter actions by type",
+      ),
+      pageSize: z
+        .number()
+        .min(1)
+        .optional()
+        .describe("Number of actions per page"),
+      maxItems: z
+        .number()
+        .min(1)
+        .optional()
+        .describe("Maximum total items to return across all pages"),
+    })
+    .describe("List all actions for a specific app"),
+  ActionItemSchema,
+);
+
+// Type inferred from schema
+export type ListActionsOptions = z.infer<typeof ListActionsSchema>;
+
+// Page result structure
+export interface ListActionsPage {
+  data: ActionItem[];
+  nextCursor?: string;
+}
+
+// Error union for this function
+export type ListActionsError =
+  | import("../../types/errors").ZapierAuthenticationError
+  | import("../../types/errors").ZapierValidationError
+  | import("../../types/errors").ZapierUnknownError;
+
+// SDK function interface
+export interface ListActionsSdkFunction {
+  listActions: PaginatedSdkFunction<ListActionsOptions, ActionItem>;
+}

package/src/plugins/listApps/index.test.ts

@@ -0,0 +1,357 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ZapierValidationError } from "../../types/errors";
+import { listAppsPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import { apiPlugin } from "../api/index";
+
+const mockAppsResponse = {
+  results: [
+    {
+      id: "SlackCLIAPI@1.0.0",
+      slug: "slack",
+      name: "Slack",
+      description: "Team communication",
+      primary_color: "#4A154B",
+      categories: ["communication"],
+    },
+    {
+      id: "GoogleSheetsCLIAPI@1.0.0",
+      slug: "google-sheets",
+      name: "Google Sheets",
+      description: "Online spreadsheets",
+      primary_color: "#34A853",
+      categories: ["productivity"],
+    },
+  ],
+  meta: {
+    next_cursor: null,
+  },
+};
+
+function createTestSdk() {
+  return createSdk()
+    .addPlugin(apiPlugin, { fetch: global.fetch })
+    .addPlugin(listAppsPlugin as any);
+}
+
+describe("listApps plugin", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("schema validation", () => {
+    it("should pass validation with empty options", async () => {
+      const mockServicesResponse = {
+        results: [
+          {
+            id: "slack_service_id",
+            slug: "slack",
+            name: "Slack",
+            description: "Team communication",
+            current_implementation_id: "SlackCLIAPI@1.0.0",
+          },
+          {
+            id: "sheets_service_id",
+            slug: "google-sheets",
+            name: "Google Sheets",
+            description: "Online spreadsheets",
+            current_implementation_id: "GoogleSheetsCLIAPI@1.0.0",
+          },
+        ],
+        next: null,
+      };
+
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+      // Mock the API client in context
+      (context.api as any).get = vi
+        .fn()
+        .mockResolvedValue(mockServicesResponse);
+
+      const result = await sdk.listApps({});
+      expect(result.data).toHaveLength(2);
+    });
+
+    it("should handle undefined options by converting to empty object", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      // Mock the API client in context
+      (context.api as any).get = vi.fn().mockResolvedValueOnce({
+        results: [
+          {
+            id: "SlackCLIAPI@1.0.0",
+            name: "Slack",
+            description: "Team communication",
+            primary_color: "#4A154B",
+            categories: ["communication"],
+          },
+        ],
+        next: null,
+      });
+
+      const result = await sdk.listApps(undefined as any);
+
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0]).toMatchObject({
+        key: "SlackCLIAPI",
+        title: "Slack",
+      });
+      expect((context.api as any).get).toHaveBeenCalledWith(
+        "/api/v4/implementations-meta/lookup/",
+        {
+          searchParams: { latest_only: "true", limit: "100" },
+        },
+      );
+    });
+
+    it("should throw validation error for invalid pageSize", () => {
+      const sdk = createTestSdk();
+      expect(() => {
+        sdk.listApps({
+          pageSize: 0, // Should be >= 1
+        });
+      }).toThrow(ZapierValidationError);
+
+      expect(() => {
+        sdk.listApps({
+          pageSize: -5, // Should be >= 1
+        });
+      }).toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid maxItems", () => {
+      const sdk = createTestSdk();
+      expect(() => {
+        sdk.listApps({
+          maxItems: 0 as any, // Should be >= 1
+        });
+      }).toThrow(ZapierValidationError);
+
+      expect(() => {
+        sdk.listApps({
+          maxItems: -10 as any, // Should be >= 1
+        });
+      }).toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid appKeys type", () => {
+      const sdk = createTestSdk();
+      expect(() => {
+        sdk.listApps({
+          appKeys: 123 as any,
+        });
+      }).toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with all valid fields", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      // Mock the API client in context
+      (context.api as any).get = vi.fn().mockResolvedValueOnce({
+        results: [
+          {
+            id: "SlackCLIAPI@1.0.0",
+            name: "Slack",
+            description: "Team communication",
+            primary_color: "#4A154B",
+            categories: ["communication"],
+          },
+          {
+            id: "GitHubCLIAPI@1.0.0",
+            name: "GitHub",
+            description: "Code repository hosting",
+            primary_color: "#24292e",
+            categories: ["developer-tools"],
+          },
+        ],
+        next: null,
+      });
+
+      const result = await sdk.listApps({
+        appKeys: ["SlackCLIAPI", "GitHubCLIAPI"],
+        pageSize: 10,
+        maxItems: 50,
+      });
+
+      expect(result.data).toHaveLength(2);
+      expect(result.data[0].key).toBe("SlackCLIAPI");
+      expect(result.data[1].key).toBe("GitHubCLIAPI");
+    });
+  });
+
+  describe("data mapping", () => {
+    it("should return essential app properties", async () => {
+      const mockServicesResponse = {
+        results: [
+          {
+            id: "slack_service_id",
+            slug: "slack",
+            name: "Slack",
+            description: "Team communication",
+            current_implementation_id: "SlackCLIAPI@1.0.0",
+          },
+        ],
+        next: null,
+      };
+
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+      // Mock the API client in context
+      (context.api as any).get = vi
+        .fn()
+        .mockResolvedValue(mockServicesResponse);
+
+      const result = await sdk.listApps({});
+
+      expect(result.data[0]).toHaveProperty("title");
+      expect(result.data[0]).toHaveProperty("key");
+      expect(result.data[0]).toHaveProperty("current_implementation_id");
+      // Version is optional
+      expect(result.data[0]).toHaveProperty("version");
+    });
+  });
+
+  describe("pagination", () => {
+    it("should handle pagination with maxItems", async () => {
+      const mockServicesResponse = {
+        results: [
+          {
+            id: "slack_service_id",
+            slug: "slack",
+            name: "Slack",
+            description: "Team communication",
+            current_implementation_id: "SlackCLIAPI@1.0.0",
+          },
+          {
+            id: "sheets_service_id",
+            slug: "google-sheets",
+            name: "Google Sheets",
+            description: "Online spreadsheets",
+            current_implementation_id: "GoogleSheetsCLIAPI@1.0.0",
+          },
+        ],
+        next: null,
+      };
+
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+      const mockGet = vi.fn().mockResolvedValue(mockServicesResponse);
+      (context.api as any).get = mockGet;
+
+      const result = await sdk.listApps({ maxItems: 5 });
+
+      // Should return all items since maxItems (5) is greater than available items (2)
+      expect(result.data).toHaveLength(2);
+      expect(mockGet).toHaveBeenCalledTimes(1);
+    });
+
+    it("should support async iteration over pages", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+      const mockGet = vi
+        .fn()
+        .mockResolvedValueOnce({
+          results: [
+            {
+              id: "SlackCLIAPI@1.0.0",
+              slug: "slack",
+              name: "Slack",
+              description: "Team communication",
+            },
+          ],
+          next: "https://zapier.com/api/v4/services/?offset=cursor-page-2",
+        })
+        .mockResolvedValueOnce({
+          results: [
+            {
+              id: "GoogleSheetsCLIAPI@1.0.0",
+              slug: "google-sheets",
+              name: "Google Sheets",
+              description: "Online spreadsheets",
+            },
+          ],
+          next: null,
+        });
+      (context.api as any).get = mockGet;
+
+      const pages = [];
+      for await (const page of sdk.listApps({ pageSize: 1 })) {
+        pages.push(page);
+        if (pages.length >= 2) break;
+      }
+
+      expect(pages).toHaveLength(2);
+      expect(pages[0].data).toHaveLength(1);
+      expect(pages[1].data).toHaveLength(1);
+      expect(pages[0].data[0].key).toBe("SlackCLIAPI");
+      expect(pages[1].data[0].key).toBe("GoogleSheetsCLIAPI");
+    });
+
+    it("should support async iteration over individual items", async () => {
+      const mockServicesResponse = {
+        results: [
+          {
+            id: "SlackCLIAPI@1.0.0",
+            slug: "slack",
+            name: "Slack",
+            description: "Team communication",
+          },
+          {
+            id: "GoogleSheetsCLIAPI@1.0.0",
+            slug: "google-sheets",
+            name: "Google Sheets",
+            description: "Online spreadsheets",
+          },
+        ],
+        next: null,
+      };
+
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+      (context.api as any).get = vi
+        .fn()
+        .mockResolvedValue(mockServicesResponse);
+
+      const items = [];
+      for await (const item of sdk.listApps({ maxItems: 2 }).items()) {
+        items.push(item);
+      }
+
+      expect(items).toHaveLength(2);
+      expect(items[0].key).toBe("SlackCLIAPI");
+      expect(items[1].key).toBe("GoogleSheetsCLIAPI");
+    });
+  });
+
+  describe("API integration", () => {
+    it("should pass appKeys filter to API", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+      const mockGet = vi.fn().mockResolvedValue(mockAppsResponse);
+      (context.api as any).get = mockGet;
+
+      await sdk.listApps({ appKeys: ["SlackCLIAPI", "GitHubCLIAPI"] });
+
+      expect(mockGet).toHaveBeenCalledWith(
+        expect.stringContaining("implementations-meta"),
+        expect.objectContaining({
+          searchParams: expect.objectContaining({
+            selected_apis: "SlackCLIAPI,GitHubCLIAPI",
+          }),
+        }),
+      );
+    });
+  });
+
+  describe("plugin integration", () => {
+    it("should provide metadata in context", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect((context.meta as any).listApps).toBeDefined();
+      expect((context.meta as any).listApps.inputSchema).toBeDefined();
+    });
+  });
+});

package/src/plugins/listApps/index.ts

@@ -0,0 +1,121 @@
+import type { Plugin } from "../../types/plugin";
+import type { ApiClient } from "../../api/types";
+import { createPaginatedFunction } from "../../utils/function-utils";
+import { ListAppsSchema } from "./schemas";
+import type { ListAppsOptions, ListAppsPage } from "./schemas";
+import type { AppItem } from "../../types/domain";
+import {
+  groupAppKeysByType,
+  normalizeImplementationMetaToAppItem,
+  splitVersionedKey,
+} from "../../utils/domain-utils";
+import { extractCursor } from "../../utils/function-utils";
+import type { ImplementationsMetaResponse } from "../../api/types";
+// ListApps plugin provides interface - listApps goes directly to SDK root
+export interface ListAppsPluginProvides {
+  listApps: (options?: ListAppsOptions) => Promise<{ data: AppItem[] }> &
+    AsyncIterable<{ data: AppItem[]; nextCursor?: string }> & {
+      items(): AsyncIterable<AppItem>;
+    };
+  context: {
+    meta: {
+      listApps: {
+        inputSchema: typeof ListAppsSchema;
+      };
+    };
+  };
+}
+
+// Direct plugin function - takes options + sdk + context in one object
+export const listAppsPlugin: Plugin<
+  {}, // no SDK dependencies
+  { api: ApiClient }, // requires api in context
+  ListAppsPluginProvides
+> = ({ context }) => {
+  const listApps = createPaginatedFunction(async function listAppsPage(
+    options: ListAppsOptions & { cursor?: string } & { pageSize: number },
+  ): Promise<ListAppsPage> {
+    const api = context.api;
+    const opts = options;
+
+    const appKeys = [...(opts.appKeys ?? [])].map(
+      (key) => splitVersionedKey(key)[0],
+    );
+
+    if (opts.search) {
+      const searchParams: Record<string, string> = {};
+
+      searchParams.term = opts.search;
+
+      const searchEnvelope: ImplementationsMetaResponse = await api.get(
+        "/api/v4/implementations-meta/search/",
+        {
+          searchParams,
+        },
+      );
+
+      const implementations = searchEnvelope.results.map(
+        normalizeImplementationMetaToAppItem,
+      );
+
+      const appKeysSet = new Set(appKeys);
+
+      for (const implementation of implementations) {
+        if (!appKeysSet.has(implementation.key)) {
+          appKeysSet.add(implementation.key);
+          appKeys.push(implementation.key);
+        }
+      }
+    }
+
+    const searchParams: Record<string, string> = {};
+
+    if (opts.pageSize) {
+      searchParams.limit = opts.pageSize.toString();
+    }
+
+    searchParams.latest_only = "true";
+
+    if (opts.cursor) {
+      searchParams.offset = opts.cursor;
+    }
+
+    if (appKeys.length > 0) {
+      const groupedAppKeys = groupAppKeysByType(appKeys);
+
+      if (groupedAppKeys.selectedApi.length > 0) {
+        searchParams.selected_apis = groupedAppKeys.selectedApi.join(",");
+      }
+
+      if (groupedAppKeys.slug.length > 0) {
+        searchParams.slugs = groupedAppKeys.slug.join(",");
+      }
+    }
+
+    const implementationsEnvelope: ImplementationsMetaResponse = await api.get(
+      "/api/v4/implementations-meta/lookup/",
+      {
+        searchParams,
+      },
+    );
+
+    return {
+      data: implementationsEnvelope.results.map(
+        normalizeImplementationMetaToAppItem,
+      ),
+      nextCursor: extractCursor(implementationsEnvelope),
+    };
+  }, ListAppsSchema);
+
+  // Return flat structure - listApps goes directly to SDK
+  return {
+    listApps,
+    context: {
+      meta: {
+        listApps: {
+          inputSchema: ListAppsSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/listApps/schemas.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+import type { AppItem } from "../../types/domain";
+import type { PaginatedSdkFunction } from "../../types/functions";
+import { ZapierApiError, ZapierValidationError } from "../../types/errors";
+import { AppItemSchema } from "../../schemas/App";
+import { withOutputSchema } from "../../utils/schema-utils";
+
+// Union of all possible errors for listApps
+export type ListAppsError = ZapierApiError | ZapierValidationError;
+
+// A page of results returned when awaiting listApps
+export interface ListAppsPage {
+  data: AppItem[];
+  nextCursor?: string;
+}
+
+// Pure Zod schema - no pagination metadata exposed
+export const ListAppsSchema = withOutputSchema(
+  z
+    .object({
+      appKeys: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "Filter apps by app keys (e.g., 'SlackCLIAPI' or slug like 'github')",
+        ),
+      search: z.string().optional().describe("Search for apps by name"),
+      pageSize: z
+        .number()
+        .min(1)
+        .optional()
+        .describe("Number of apps per page"),
+      maxItems: z
+        .number()
+        .min(1)
+        .optional()
+        .describe("Maximum total items to return across all pages"),
+    })
+    .describe("List all available apps with optional filtering"),
+  AppItemSchema,
+);
+
+// Type inferred from schema
+export type ListAppsOptions = z.infer<typeof ListAppsSchema>;
+
+// SDK function interface
+export interface ListAppsSdkFunction {
+  listApps: PaginatedSdkFunction<ListAppsOptions | undefined, AppItem>;
+}