@zapier/zapier-sdk 0.4.1 → 0.5.0

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

@@ -0,0 +1,197 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  ZapierValidationError,
+  ZapierResourceNotFoundError,
+} from "../../types/errors";
+import { findUniqueAuthenticationPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import type { AuthenticationItem } from "../../types/domain";
+import { ListAuthenticationsSchema } from "../listAuthentications/schemas";
+
+const mockAuthentication: AuthenticationItem = {
+  id: 123,
+  title: "My Slack",
+  date: "2021-01-01",
+  account_id: 123,
+  implementation_id: "api_123",
+  is_expired: "false",
+  expired_at: null,
+  is_invite_only: false,
+  is_private: false,
+  shared_with_all: false,
+};
+
+const mockAuthentications: AuthenticationItem[] = [
+  mockAuthentication,
+  {
+    id: 456,
+    title: "Slack Workspace 2",
+    is_expired: "false",
+    expired_at: null,
+    date: "2021-01-01",
+    account_id: 123,
+    implementation_id: "api_123",
+    is_invite_only: false,
+    is_private: false,
+    shared_with_all: false,
+  },
+];
+
+describe("findUniqueAuthentication plugin", () => {
+  let mockListAuthentications: any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockListAuthentications = vi.fn().mockResolvedValue({
+      data: [mockAuthentication],
+    });
+  });
+
+  function createTestSdk() {
+    // Create a proper plugin chain: first add a mock listAuthentications plugin, then add findUniqueAuthentication
+    const mockListAuthenticationsPlugin = () => ({
+      listAuthentications: mockListAuthentications,
+      context: {
+        meta: {
+          listAuthentications: {
+            inputSchema: ListAuthenticationsSchema,
+          },
+        },
+      },
+    });
+
+    // Build SDK with proper plugin composition
+    return createSdk()
+      .addPlugin(mockListAuthenticationsPlugin)
+      .addPlugin(findUniqueAuthenticationPlugin);
+  }
+
+  describe("schema validation", () => {
+    it("should pass validation with empty options", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.findUniqueAuthentication({});
+      expect(result.data).toBeDefined();
+    });
+
+    it("should throw validation error for invalid appKey type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findUniqueAuthentication({
+          appKey: 123 as any,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid parameter types", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findUniqueAuthentication({
+          search: 123 as any,
+          title: 456 as any,
+          account_id: 789 as any,
+          owner: false as any,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with all valid fields", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.findUniqueAuthentication({
+        appKey: "slack",
+        search: "Workspace",
+        title: "My Slack",
+        account_id: "acc_123",
+        owner: "me",
+      });
+
+      expect(result.data).toBeDefined();
+    });
+  });
+
+  describe("business logic", () => {
+    it("should return the first authentication when exactly one is found", async () => {
+      mockListAuthentications.mockResolvedValue({
+        data: [mockAuthentication],
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.findUniqueAuthentication({
+        appKey: "slack",
+      });
+
+      expect(result.data).toEqual(mockAuthentication);
+    });
+
+    it("should throw ZapierResourceNotFoundError when no authentications found", async () => {
+      mockListAuthentications.mockResolvedValue({
+        data: [],
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findUniqueAuthentication({
+          appKey: "nonexistent",
+        }),
+      ).rejects.toThrow(ZapierResourceNotFoundError);
+
+      await expect(
+        sdk.findUniqueAuthentication({
+          appKey: "nonexistent",
+        }),
+      ).rejects.toThrow(
+        "No authentication found matching the specified criteria",
+      );
+    });
+
+    it("should throw ZapierValidationError when multiple authentications found", async () => {
+      mockListAuthentications.mockResolvedValue({
+        data: mockAuthentications, // Two authentications
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findUniqueAuthentication({
+          search: "Workspace",
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+
+      await expect(
+        sdk.findUniqueAuthentication({
+          search: "Workspace",
+        }),
+      ).rejects.toThrow(
+        "Multiple authentications found matching the specified criteria. Expected exactly one.",
+      );
+    });
+  });
+
+  describe("options forwarding", () => {
+    it("should forward all options to listAuthentications with maxItems=2", async () => {
+      const sdk = createTestSdk();
+      const options = {
+        appKey: "slack",
+        search: "workspace",
+        title: "My Slack Workspace",
+        account_id: "acc_123",
+        owner: "me",
+      };
+
+      await sdk.findUniqueAuthentication(options);
+
+      expect(mockListAuthentications).toHaveBeenCalledWith({
+        ...options,
+        maxItems: 2,
+      });
+    });
+  });
+
+  describe("context and metadata", () => {
+    it("should provide context with meta information", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect(context.meta.findUniqueAuthentication).toBeDefined();
+      expect(context.meta.findUniqueAuthentication.inputSchema).toBeDefined();
+    });
+  });
+});

package/src/plugins/findUniqueAuthentication/index.ts

@@ -0,0 +1,72 @@
+import type { Plugin, GetSdkType } from "../../types/plugin";
+import type { AuthenticationItem } from "../../types/domain";
+import {
+  FindUniqueAuthenticationSchema,
+  type FindUniqueAuthenticationOptions,
+} from "./schemas";
+import {
+  ZapierResourceNotFoundError,
+  ZapierValidationError,
+} from "../../types/errors";
+import { createFunction } from "../../utils/function-utils";
+import type { ListAuthenticationsPluginProvides } from "../listAuthentications";
+
+export interface FindUniqueAuthenticationPluginProvides {
+  findUniqueAuthentication: (
+    options?: FindUniqueAuthenticationOptions,
+  ) => Promise<{ data: AuthenticationItem }>;
+  context: {
+    meta: {
+      findUniqueAuthentication: {
+        inputSchema: typeof FindUniqueAuthenticationSchema;
+      };
+    };
+  };
+}
+
+export const findUniqueAuthenticationPlugin: Plugin<
+  GetSdkType<ListAuthenticationsPluginProvides>, // requires listAuthentications in SDK
+  {}, // no context requirements
+  FindUniqueAuthenticationPluginProvides
+> = ({ sdk }) => {
+  const findUniqueAuthentication = createFunction(
+    async function findUniqueAuthentication(
+      options: FindUniqueAuthenticationOptions = {},
+    ) {
+      // Use listAuthentications with maxItems 2 to check for uniqueness
+      const authsResponse = await sdk.listAuthentications({
+        ...options,
+        maxItems: 2, // Get up to 2 to check for uniqueness
+      });
+
+      if (authsResponse.data.length === 0) {
+        throw new ZapierResourceNotFoundError(
+          "No authentication found matching the specified criteria",
+          { resourceType: "Authentication" },
+        );
+      }
+
+      if (authsResponse.data.length > 1) {
+        throw new ZapierValidationError(
+          "Multiple authentications found matching the specified criteria. Expected exactly one.",
+        );
+      }
+
+      return {
+        data: authsResponse.data[0],
+      };
+    },
+    FindUniqueAuthenticationSchema,
+  );
+
+  return {
+    findUniqueAuthentication,
+    context: {
+      meta: {
+        findUniqueAuthentication: {
+          inputSchema: FindUniqueAuthenticationSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/findUniqueAuthentication/schemas.ts

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { AppKeyPropertySchema } from "../../types/properties";
+import type { AuthenticationItem } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const FindUniqueAuthenticationSchema = z
+  .object({
+    appKey: AppKeyPropertySchema.optional().describe(
+      "App key of authentication to find (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"),
+  })
+  .describe("Find a unique authentication matching the criteria");
+
+// Type inferred from schema
+export type FindUniqueAuthenticationOptions = z.infer<
+  typeof FindUniqueAuthenticationSchema
+>;
+
+// Error union for this function
+export type FindUniqueAuthenticationError =
+  | import("../../types/errors").ZapierAuthenticationError
+  | import("../../types/errors").ZapierApiError
+  | import("../../types/errors").ZapierResourceNotFoundError
+  | import("../../types/errors").ZapierValidationError
+  | import("../../types/errors").ZapierUnknownError;
+
+// SDK function interface
+export interface FindUniqueAuthenticationSdkFunction {
+  findUniqueAuthentication: (
+    options?: FindUniqueAuthenticationOptions,
+  ) => Promise<{ data: AuthenticationItem }>;
+}

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

@@ -0,0 +1,239 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  ZapierValidationError,
+  ZapierResourceNotFoundError,
+} from "../../types/errors";
+import { getActionPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import type { GetActionOptions } from "./schemas";
+import type { ActionItem } from "../../types/domain";
+import type { ApiClient } from "../../api";
+import { ListActionsSchema } from "../listActions/schemas";
+
+const mockActions: ActionItem[] = [
+  {
+    type: "action",
+    key: "user_by_email",
+    title: "Search User by Email",
+    description: "Find a user by email address",
+    app_key: "slack",
+    action_type: "search",
+  },
+  {
+    type: "action",
+    key: "search_messages",
+    title: "Search Messages",
+    description: "Search for messages in channels",
+    app_key: "slack",
+    action_type: "search",
+  },
+  {
+    type: "action",
+    key: "user_by_email",
+    title: "Search User by Email",
+    description: "Find a user by email address",
+    app_key: "slack",
+    action_type: "write", // Different action type for testing mismatch
+  },
+];
+
+describe("getAction plugin", () => {
+  let mockListActions: any;
+  let mockApiClient: ApiClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockListActions = vi.fn().mockResolvedValue({
+      data: mockActions,
+    });
+    mockApiClient = {} as ApiClient;
+  });
+
+  function createTestSdk() {
+    // Create a proper plugin chain with context dependencies
+    const mockListActionsPlugin = () => ({
+      listActions: mockListActions,
+      context: {
+        meta: {
+          listActions: {
+            inputSchema: ListActionsSchema,
+          },
+        },
+      },
+    });
+
+    // Build SDK with proper plugin composition, providing API in initial context
+    return createSdk({}, { api: mockApiClient, meta: {} })
+      .addPlugin(mockListActionsPlugin)
+      .addPlugin(getActionPlugin);
+  }
+
+  describe("schema validation", () => {
+    it("should throw validation error for missing appKey", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          actionType: "search",
+          actionKey: "user_by_email",
+        } as Partial<GetActionOptions> as GetActionOptions),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for missing actionType", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "slack",
+          actionKey: "user_by_email",
+        } as Partial<GetActionOptions> as GetActionOptions),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for missing actionKey", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "slack",
+          actionType: "search",
+        } as Partial<GetActionOptions> as GetActionOptions),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid appKey type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: 123 as any,
+          actionType: "search",
+          actionKey: "user_by_email",
+        } as any),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid actionType", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "slack",
+          actionType: "invalid-type" as any,
+          actionKey: "user_by_email",
+        } as any),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid actionKey type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "slack",
+          actionType: "search",
+          actionKey: 123,
+        } as any),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for empty appKey", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "",
+          actionType: "search",
+          actionKey: "user_by_email",
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for empty actionKey", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "slack",
+          actionType: "search",
+          actionKey: "",
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with all required fields", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.getAction({
+        appKey: "slack",
+        actionType: "search",
+        actionKey: "user_by_email",
+      });
+
+      expect(result.data).toEqual(mockActions[0]);
+    });
+  });
+
+  describe("action lookup", () => {
+    it("should call listActions with correct parameters", async () => {
+      const sdk = createTestSdk();
+      await sdk.getAction({
+        appKey: "slack",
+        actionType: "search",
+        actionKey: "user_by_email",
+      });
+
+      expect(mockListActions).toHaveBeenCalledWith({
+        appKey: "slack",
+      });
+    });
+
+    it("should return the correct action when found", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.getAction({
+        appKey: "slack",
+        actionType: "search",
+        actionKey: "user_by_email",
+      });
+
+      expect(result.data).toEqual(mockActions[0]);
+    });
+
+    it("should throw error when action key not found", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "slack",
+          actionType: "search",
+          actionKey: "nonexistent_action",
+        }),
+      ).rejects.toThrow(ZapierResourceNotFoundError);
+    });
+
+    it("should throw error when action type doesn't match", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "slack",
+          actionType: "write",
+          actionKey: "search_messages", // This action is type "search" in mock
+        }),
+      ).rejects.toThrow(ZapierResourceNotFoundError);
+    });
+
+    it("should handle listActions errors", async () => {
+      mockListActions.mockRejectedValue(new Error("API Error"));
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAction({
+          appKey: "slack",
+          actionType: "search",
+          actionKey: "user_by_email",
+        }),
+      ).rejects.toThrow("API Error");
+    });
+  });
+
+  describe("plugin integration", () => {
+    it("should provide metadata in context", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect(context.meta.getAction).toBeDefined();
+      expect(context.meta.getAction.inputSchema).toBeDefined();
+    });
+  });
+});

package/src/plugins/getAction/index.ts

@@ -0,0 +1,57 @@
+import type { Plugin, GetSdkType } from "../../types/plugin";
+import type { ApiClient } from "../../api";
+import type { ActionItem } from "../../types/domain";
+import { GetActionSchema, type GetActionOptions } from "./schemas";
+import { ZapierResourceNotFoundError } from "../../types/errors";
+import { createFunction } from "../../utils/function-utils";
+import type { ListActionsPluginProvides } from "../listActions";
+
+export interface GetActionPluginProvides {
+  getAction: (options: GetActionOptions) => Promise<{ data: ActionItem }>;
+  context: {
+    meta: {
+      getAction: {
+        inputSchema: typeof GetActionSchema;
+      };
+    };
+  };
+}
+
+export const getActionPlugin: Plugin<
+  GetSdkType<ListActionsPluginProvides>, // requires listActions in SDK
+  { api: ApiClient }, // requires api in context
+  GetActionPluginProvides
+> = ({ sdk }) => {
+  const getAction = createFunction(async function getAction(
+    options: GetActionOptions,
+  ) {
+    const { actionKey, actionType, appKey } = options;
+
+    // Use the listActions function from the SDK to search for the specific action
+    const actionsResult = await sdk.listActions({ appKey });
+
+    // Search through all actions to find the matching one
+    for (const action of actionsResult.data) {
+      if (action.key === actionKey && action.action_type === actionType) {
+        return { data: action };
+      }
+    }
+
+    // If we get here, action was not found
+    throw new ZapierResourceNotFoundError(
+      `Action not found: ${actionKey} with type ${actionType}`,
+      { resourceType: "Action", resourceId: `${actionKey} (${actionType})` },
+    );
+  }, GetActionSchema);
+
+  return {
+    getAction,
+    context: {
+      meta: {
+        getAction: {
+          inputSchema: GetActionSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/getAction/schemas.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import {
+  AppKeyPropertySchema,
+  ActionTypePropertySchema,
+  ActionKeyPropertySchema,
+} from "../../types/properties";
+import type { ActionItem } 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
+export type GetActionOptions = z.infer<typeof GetActionSchema>;
+
+// Error union for this function (inherits from listActionsSafe + resource not found)
+export type GetActionError =
+  | import("../../types/errors").ZapierAuthenticationError
+  | import("../../types/errors").ZapierApiError
+  | import("../../types/errors").ZapierAppNotFoundError
+  | import("../../types/errors").ZapierValidationError
+  | import("../../types/errors").ZapierResourceNotFoundError
+  | import("../../types/errors").ZapierUnknownError;
+
+// SDK function interface
+export interface GetActionSdkFunction {
+  getAction: (options: GetActionOptions) => Promise<{ data: ActionItem }>;
+}