@zapier/zapier-sdk 0.4.0 → 0.5.0

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

@@ -0,0 +1,206 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ZapierValidationError } from "../../types/errors";
+import { findFirstAuthenticationPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import type { AuthenticationItem } from "../../types/domain";
+import { ListAuthenticationsSchema } from "../listAuthentications/schemas";
+
+const mockAuthentications: 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,
+  },
+  {
+    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("findFirstAuthentication plugin", () => {
+  let mockListAuthentications: any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockListAuthentications = vi.fn().mockResolvedValue({
+      data: mockAuthentications,
+    });
+  });
+
+  function createTestSdk() {
+    // Create a proper plugin chain: first add a mock listAuthentications plugin, then add findFirstAuthentication
+    const mockListAuthenticationsPlugin = () => ({
+      listAuthentications: mockListAuthentications,
+      context: {
+        meta: {
+          listAuthentications: {
+            inputSchema: ListAuthenticationsSchema,
+          },
+        },
+      },
+    });
+
+    // Build SDK with proper plugin composition
+    return createSdk()
+      .addPlugin(mockListAuthenticationsPlugin)
+      .addPlugin(findFirstAuthenticationPlugin);
+  }
+
+  describe("schema validation", () => {
+    it("should pass validation with empty options", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({});
+      expect(result.data).toBeDefined();
+    });
+
+    it("should pass validation with undefined options", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication();
+      expect(result.data).toBeDefined();
+    });
+
+    it("should throw validation error for invalid appKey type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findFirstAuthentication({
+          appKey: 123 as any, // intentionally wrong type for testing
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid search type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findFirstAuthentication({
+          search: 123 as any,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid parameter types", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.findFirstAuthentication({
+          title: 123 as any,
+          account_id: 456 as any,
+          owner: true as any,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with all valid fields", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({
+        appKey: "slack",
+        search: "workspace",
+        title: "My Slack Workspace",
+        account_id: "acc_123",
+        owner: "me",
+      });
+
+      expect(result.data).toBeDefined();
+    });
+  });
+
+  describe("business logic", () => {
+    it("should return first authentication when found", async () => {
+      const mockAuth = mockAuthentications[0];
+      mockListAuthentications.mockResolvedValue({
+        data: [mockAuth],
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({
+        appKey: "slack",
+      });
+
+      expect(result.data).toEqual(mockAuth);
+    });
+
+    it("should return null when no authentications found", async () => {
+      mockListAuthentications.mockResolvedValue({
+        data: [],
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({
+        appKey: "nonexistent",
+      });
+
+      expect(result.data).toBeNull();
+    });
+
+    it("should return first authentication when multiple found", async () => {
+      const mockAuth = mockAuthentications[0];
+      mockListAuthentications.mockResolvedValue({
+        data: [mockAuth, mockAuthentications[1]],
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.findFirstAuthentication({
+        search: "Slack",
+      });
+
+      expect(result.data).toEqual(mockAuth);
+    });
+  });
+
+  describe("options forwarding", () => {
+    it("should forward all options to listAuthentications", async () => {
+      const sdk = createTestSdk();
+      const options = {
+        appKey: "slack",
+        search: "workspace",
+        title: "My Slack Workspace",
+        account_id: "acc_123",
+        owner: "me",
+      };
+
+      await sdk.findFirstAuthentication(options);
+
+      expect(mockListAuthentications).toHaveBeenCalledWith({
+        ...options,
+        maxItems: 1,
+      });
+    });
+  });
+
+  describe("limit enforcement", () => {
+    it("should automatically set maxItems to 1", async () => {
+      const sdk = createTestSdk();
+      await sdk.findFirstAuthentication({
+        appKey: "slack",
+      });
+
+      expect(mockListAuthentications).toHaveBeenCalledWith({
+        appKey: "slack",
+        maxItems: 1,
+      });
+    });
+  });
+
+  describe("context and metadata", () => {
+    it("should provide context with meta information", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect(context.meta.findFirstAuthentication).toBeDefined();
+      expect(context.meta.findFirstAuthentication.inputSchema).toBeDefined();
+    });
+  });
+});

package/src/plugins/findFirstAuthentication/index.ts

@@ -0,0 +1,55 @@
+import type { Plugin, GetSdkType } from "../../types/plugin";
+import type { AuthenticationItem } from "../../types/domain";
+import {
+  FindFirstAuthenticationSchema,
+  type FindFirstAuthenticationOptions,
+} from "./schemas";
+import { createFunction } from "../../utils/function-utils";
+import type { ListAuthenticationsPluginProvides } from "../listAuthentications";
+
+export interface FindFirstAuthenticationPluginProvides {
+  findFirstAuthentication: (
+    options?: FindFirstAuthenticationOptions,
+  ) => Promise<{ data: AuthenticationItem | null }>;
+  context: {
+    meta: {
+      findFirstAuthentication: {
+        inputSchema: typeof FindFirstAuthenticationSchema;
+      };
+    };
+  };
+}
+
+export const findFirstAuthenticationPlugin: Plugin<
+  GetSdkType<ListAuthenticationsPluginProvides>, // requires listAuthentications in SDK
+  {}, // no context requirements
+  FindFirstAuthenticationPluginProvides
+> = ({ sdk }) => {
+  const findFirstAuthentication = createFunction(
+    async function findFirstAuthentication(
+      options: FindFirstAuthenticationOptions = {},
+    ) {
+      // Use listAuthentications with maxItems 1 to get the first result
+      const authsResponse = await sdk.listAuthentications({
+        ...options,
+        maxItems: 1,
+      });
+
+      return {
+        data: authsResponse.data.length > 0 ? authsResponse.data[0] : null,
+      };
+    },
+    FindFirstAuthenticationSchema,
+  );
+
+  return {
+    findFirstAuthentication,
+    context: {
+      meta: {
+        findFirstAuthentication: {
+          inputSchema: FindFirstAuthenticationSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/findFirstAuthentication/schemas.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+import { AppKeyPropertySchema } from "../../types/properties";
+import type { AuthenticationItem } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const FindFirstAuthenticationSchema = 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 the first authentication matching the criteria");
+
+// Type inferred from schema
+export type FindFirstAuthenticationOptions = z.infer<
+  typeof FindFirstAuthenticationSchema
+>;
+
+// Error union for this function (inherits from listAuthenticationsSafe)
+export type FindFirstAuthenticationError =
+  | import("../../types/errors").ZapierAuthenticationError
+  | import("../../types/errors").ZapierApiError
+  | import("../../types/errors").ZapierValidationError
+  | import("../../types/errors").ZapierUnknownError;
+
+// SDK function interface
+export interface FindFirstAuthenticationSdkFunction {
+  findFirstAuthentication: (
+    options?: FindFirstAuthenticationOptions,
+  ) => Promise<{ data: AuthenticationItem | null }>;
+}

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 }>;
+}