@zapier/zapier-sdk 0.4.1 → 0.5.0

package/src/plugins/listAuthentications/index.ts

@@ -0,0 +1,136 @@
+import type { Plugin, GetSdkType } from "../../types/plugin";
+import type { ApiClient } from "../../api";
+import type { AuthenticationsResponse } from "../../api/types";
+import type { AuthenticationItem } from "../../types/domain";
+import {
+  ListAuthenticationsSchema,
+  type ListAuthenticationsOptions,
+  type ListAuthenticationsPage,
+} from "./schemas";
+import { normalizeAuthenticationItem } from "../../utils/domain-utils";
+import { ZapierAuthenticationError } from "../../types/errors";
+import {
+  createPaginatedFunction,
+  extractCursor,
+} from "../../utils/function-utils";
+import type { GetAppPluginProvides } from "../getApp";
+
+export interface ListAuthenticationsPluginProvides {
+  listAuthentications: (options?: ListAuthenticationsOptions) => Promise<{
+    data: AuthenticationItem[];
+  }> &
+    AsyncIterable<{ data: AuthenticationItem[]; nextCursor?: string }> & {
+      items(): AsyncIterable<AuthenticationItem>;
+    };
+  context: {
+    meta: {
+      listAuthentications: {
+        inputSchema: typeof ListAuthenticationsSchema;
+      };
+    };
+  };
+}
+
+export const listAuthenticationsPlugin: Plugin<
+  GetSdkType<GetAppPluginProvides>, // requires getApp in SDK
+  { api: ApiClient }, // requires api in context
+  ListAuthenticationsPluginProvides
+> = ({ sdk, context }) => {
+  const listAuthentications = createPaginatedFunction(
+    async function listAuthenticationsPage(
+      options: ListAuthenticationsOptions & { cursor?: string } & {
+        pageSize: number;
+      },
+    ): Promise<ListAuthenticationsPage> {
+      const { api } = context;
+
+      // Build search parameters
+      const searchParams: Record<string, string> = {};
+
+      // Handle appKey filtering by getting the selected_api first
+      if (options.appKey) {
+        const app = await sdk.getApp({
+          appKey: options.appKey,
+        });
+
+        const selectedApi = app.data.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;
+        }
+      }
+
+      // Add other query parameters if provided
+      // Use title as search if no explicit search provided
+      if (options.search) {
+        searchParams.search = options.search;
+      } else if (options.title) {
+        searchParams.search = options.title;
+      }
+      if (options.account_id) {
+        searchParams.account_id = options.account_id;
+      }
+      if (options.owner) {
+        searchParams.owner = options.owner;
+      }
+      // pageSize is now guaranteed to be set by the higher-order function
+      searchParams.limit = options.pageSize.toString();
+      if (options.cursor) {
+        // Convert cursor back to offset for the API
+        searchParams.offset = options.cursor;
+      }
+
+      const data: AuthenticationsResponse = await api.get(
+        "/api/v4/authentications/",
+        {
+          searchParams,
+          customErrorHandler: ({ status }) => {
+            if (status === 401) {
+              return new ZapierAuthenticationError(
+                `Authentication failed. Your token may not have permission to access authentications 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 authentications. (HTTP ${status})`,
+                { statusCode: status },
+              );
+            }
+            return undefined;
+          },
+          authRequired: true,
+        },
+      );
+
+      // Transform API response and filter by exact title match if specified
+      let auths = (data.results || []).map((auth) =>
+        normalizeAuthenticationItem(auth),
+      );
+
+      // Filter by exact title match if specified
+      if (options.title) {
+        auths = auths.filter((auth) => auth.title === options.title);
+      }
+
+      return {
+        data: auths,
+        nextCursor: extractCursor(data),
+      };
+    },
+    ListAuthenticationsSchema,
+  );
+
+  return {
+    listAuthentications,
+    context: {
+      meta: {
+        listAuthentications: {
+          inputSchema: ListAuthenticationsSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/listAuthentications/schemas.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { AppKeyPropertySchema } from "../../types/properties";
+import type { PaginatedSdkFunction } from "../../types/functions";
+import type { AuthenticationItem } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const ListAuthenticationsSchema = z
+  .object({
+    appKey: AppKeyPropertySchema.optional().describe(
+      "App key of authentications to list (e.g., 'SlackCLIAPI')",
+    ),
+    search: z
+      .string()
+      .optional()
+      .describe("Search term to filter authentications by title"),
+    title: z
+      .string()
+      .optional()
+      .describe("Filter authentications by exact title match"),
+    account_id: z.string().optional().describe("Filter by account ID"),
+    owner: z.string().optional().describe("Filter by owner"),
+    pageSize: z
+      .number()
+      .min(1)
+      .optional()
+      .describe("Number of authentications per page"),
+    maxItems: z
+      .number()
+      .min(1)
+      .optional()
+      .describe("Maximum total items to return across all pages"),
+  })
+  .describe("List available authentications with optional filtering");
+
+// Type inferred from schema
+export type ListAuthenticationsOptions = z.infer<
+  typeof ListAuthenticationsSchema
+>;
+
+// Page result structure
+export interface ListAuthenticationsPage {
+  data: AuthenticationItem[];
+  nextCursor?: string;
+}
+
+// Error union for this function
+export type ListAuthenticationsError =
+  | import("../../types/errors").ZapierAuthenticationError
+  | import("../../types/errors").ZapierApiError
+  | import("../../types/errors").ZapierAppNotFoundError
+  | import("../../types/errors").ZapierValidationError
+  | import("../../types/errors").ZapierUnknownError;
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface ListAuthenticationsSdkFunction {
+  listAuthentications: PaginatedSdkFunction<
+    ListAuthenticationsOptions,
+    AuthenticationItem
+  >;
+}

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

@@ -0,0 +1,408 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  ZapierValidationError,
+  ZapierConfigurationError,
+  ZapierApiError,
+} from "../../types/errors";
+import { listInputFieldsPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import type { ApiClient } from "../../api";
+import type { ListInputFieldsOptions } from "./schemas";
+import type { NeedsResponse, Need } from "../../api/types";
+
+const mockNeeds: Need[] = [
+  {
+    key: "message",
+    label: "Message",
+    help_text: "The message to send",
+    required: true,
+    type: "string",
+    placeholder: "Enter your message",
+    default: "",
+  },
+  {
+    key: "channel",
+    label: "Channel",
+    help_text: "The channel to send to",
+    required: true,
+    type: "string",
+    choices: [
+      { value: "#general", label: "General", sample: "#general" },
+      { value: "#random", label: "Random", sample: "#random" },
+    ],
+  },
+  {
+    key: "tags",
+    label: "Tags",
+    help_text: "List of tags",
+    type: "string",
+    list: true,
+  },
+];
+
+const mockNeedsResponse: NeedsResponse = {
+  success: true,
+  needs: mockNeeds,
+};
+
+describe("listInputFields plugin", () => {
+  let mockApiClient: ApiClient;
+  let mockGetApp: any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockApiClient = {
+      post: vi.fn().mockResolvedValue(mockNeedsResponse),
+    } as Partial<ApiClient> as ApiClient;
+
+    mockGetApp = vi.fn().mockResolvedValue({
+      data: { current_implementation_id: "SlackCLIAPI@1.21.1" },
+    });
+  });
+
+  function createTestSdk() {
+    return createSdk(
+      { getApp: mockGetApp },
+      { api: mockApiClient, meta: {} },
+    ).addPlugin(listInputFieldsPlugin as any);
+  }
+
+  describe("schema validation", () => {
+    it("should throw validation error for missing required fields", () => {
+      const sdk = createTestSdk();
+      expect(() => {
+        sdk.listInputFields({
+          // Missing required fields
+        } as ListInputFieldsOptions);
+      }).toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid field types", () => {
+      const sdk = createTestSdk();
+      expect(() => {
+        sdk.listInputFields({
+          appKey: 123 as any,
+          actionType: "write",
+          actionKey: "send_message",
+        });
+      }).toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with all required fields", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+      });
+
+      expect(result.data).toBeDefined();
+    });
+
+    it("should pass validation with optional fields", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        authenticationId: 123,
+        inputs: { channel: "#general" },
+      });
+
+      expect(result.data).toBeDefined();
+    });
+  });
+
+  describe("API integration", () => {
+    it("should call the correct API endpoint", async () => {
+      const sdk = createTestSdk();
+      await sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+      });
+
+      expect(mockApiClient.post).toHaveBeenCalledWith(
+        "/api/v4/implementations/needs/",
+        {
+          selected_api: "SlackCLIAPI@1.21.1",
+          action: "send_message",
+          type_of: "write",
+          params: {},
+        },
+      );
+    });
+
+    it("should include authentication_id when provided", async () => {
+      const sdk = createTestSdk();
+      await sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        authenticationId: 123,
+      });
+
+      expect(mockApiClient.post).toHaveBeenCalledWith(
+        "/api/v4/implementations/needs/",
+        {
+          selected_api: "SlackCLIAPI@1.21.1",
+          action: "send_message",
+          type_of: "write",
+          params: {},
+          authentication_id: 123,
+        },
+      );
+    });
+
+    it("should exclude authentication_id when null", async () => {
+      const sdk = createTestSdk();
+      await sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        authenticationId: null,
+      });
+
+      expect(mockApiClient.post).toHaveBeenCalledWith(
+        "/api/v4/implementations/needs/",
+        {
+          selected_api: "SlackCLIAPI@1.21.1",
+          action: "send_message",
+          type_of: "write",
+          params: {},
+          // No authentication_id
+        },
+      );
+    });
+
+    it("should include inputs when provided", async () => {
+      const sdk = createTestSdk();
+      const inputs = { channel: "#general", message: "test" };
+
+      await sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs,
+      });
+
+      expect(mockApiClient.post).toHaveBeenCalledWith(
+        "/api/v4/implementations/needs/",
+        {
+          selected_api: "SlackCLIAPI@1.21.1",
+          action: "send_message",
+          type_of: "write",
+          params: inputs,
+        },
+      );
+    });
+  });
+
+  describe("data transformation", () => {
+    it("should transform needs to input field items correctly", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+      });
+
+      expect(result.data).toHaveLength(3);
+
+      // Check message field transformation
+      expect(result.data[0]).toEqual(
+        expect.objectContaining({
+          id: "message",
+          title: "Message",
+          description: "The message to send",
+          is_required: true,
+          value_type: "STRING",
+          placeholder: "Enter your message",
+          default_value: "",
+        }),
+      );
+
+      // Check channel field with choices (SELECT format)
+      expect(result.data[1]).toEqual(
+        expect.objectContaining({
+          id: "channel",
+          title: "Channel",
+          description: "The channel to send to",
+          is_required: true,
+          value_type: "STRING",
+          format: "SELECT",
+          choices: [
+            { value: "#general", label: "General", sample: "#general" },
+            { value: "#random", label: "Random", sample: "#random" },
+          ],
+        }),
+      );
+
+      // Check array field
+      expect(result.data[2]).toEqual(
+        expect.objectContaining({
+          id: "tags",
+          title: "Tags",
+          description: "List of tags",
+          value_type: "ARRAY",
+          items: { type: "STRING" },
+        }),
+      );
+    });
+
+    it("should handle different field types correctly", async () => {
+      const complexNeeds: Need[] = [
+        {
+          key: "count",
+          type: "integer",
+          label: "Count",
+          required: false,
+        },
+        {
+          key: "price",
+          type: "decimal",
+          label: "Price",
+        },
+        {
+          key: "enabled",
+          type: "boolean",
+          label: "Enabled",
+        },
+        {
+          key: "config",
+          type: "dict",
+          label: "Configuration",
+        },
+        {
+          key: "description",
+          type: "text",
+          label: "Description",
+        },
+      ];
+
+      mockApiClient.post = vi.fn().mockResolvedValue({
+        success: true,
+        needs: complexNeeds,
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+      });
+
+      expect(result.data[0].value_type).toBe("INTEGER");
+      expect(result.data[1].value_type).toBe("NUMBER");
+      expect(result.data[2].value_type).toBe("BOOLEAN");
+      expect(result.data[3].value_type).toBe("OBJECT");
+      expect(result.data[4].value_type).toBe("STRING");
+      expect(result.data[4].format).toBe("MULTILINE");
+    });
+  });
+
+  describe("error handling", () => {
+    it("should throw ZapierConfigurationError when app has no current_implementation_id", async () => {
+      mockGetApp.mockResolvedValue({
+        data: { current_implementation_id: undefined },
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.listInputFields({
+          appKey: "invalid",
+          actionType: "write",
+          actionKey: "send_message",
+        }),
+      ).rejects.toThrow(ZapierConfigurationError);
+    });
+
+    it("should throw ZapierApiError when API response indicates failure", async () => {
+      mockApiClient.post = vi.fn().mockResolvedValue({
+        success: false,
+        errors: ["Invalid action", "Missing parameter"],
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.listInputFields({
+          appKey: "slack",
+          actionType: "write",
+          actionKey: "invalid_action",
+        }),
+      ).rejects.toThrow(ZapierApiError);
+
+      await expect(
+        sdk.listInputFields({
+          appKey: "slack",
+          actionType: "write",
+          actionKey: "invalid_action",
+        }),
+      ).rejects.toThrow(
+        "Failed to get action fields: Invalid action, Missing parameter",
+      );
+    });
+
+    it("should handle API errors gracefully", async () => {
+      mockApiClient.post = vi
+        .fn()
+        .mockRejectedValue(new Error("Network error"));
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.listInputFields({
+          appKey: "slack",
+          actionType: "write",
+          actionKey: "send_message",
+        }),
+      ).rejects.toThrow("Network error");
+    });
+  });
+
+  describe("context and metadata", () => {
+    it("should provide context with meta information", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect((context.meta as any).listInputFields).toBeDefined();
+      expect((context.meta as any).listInputFields.inputSchema).toBeDefined();
+    });
+  });
+
+  describe("pagination", () => {
+    it("should support async iteration over pages", async () => {
+      const sdk = createTestSdk();
+      const listInputFieldsResult = sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+      });
+
+      const pages = [];
+      for await (const page of listInputFieldsResult) {
+        pages.push(page);
+        break; // Just get first page for testing
+      }
+
+      expect(pages).toHaveLength(1);
+      expect(pages[0].data).toHaveLength(3);
+    });
+
+    it("should support async iteration over individual items", async () => {
+      const sdk = createTestSdk();
+      const listInputFieldsResult = sdk.listInputFields({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+      });
+
+      const items = [];
+      for await (const item of listInputFieldsResult.items()) {
+        items.push(item);
+      }
+
+      expect(items).toHaveLength(3);
+      expect(items[0].id).toBe("message");
+    });
+  });
+});