@zapier/zapier-sdk 0.4.0 → 0.5.0

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

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

@@ -0,0 +1,127 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  ZapierValidationError,
+  ZapierAppNotFoundError,
+} from "../../types/errors";
+import { getAppPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import { apiPlugin } from "../api/index";
+import { listAppsPlugin } from "../listApps";
+
+function createTestSdk() {
+  return createSdk()
+    .addPlugin(apiPlugin, { fetch: global.fetch })
+    .addPlugin(listAppsPlugin)
+    .addPlugin(getAppPlugin);
+}
+
+describe("getApp plugin", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("schema validation", () => {
+    it("should throw validation error for missing appKey", async () => {
+      const sdk = createTestSdk();
+      await expect(sdk.getApp({} as any)).rejects.toThrow(
+        ZapierValidationError,
+      );
+    });
+
+    it("should throw validation error for invalid appKey type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getApp({
+          appKey: 123 as any,
+        } as any),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for empty string appKey", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getApp({
+          appKey: "",
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with valid appKey", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      // Mock the API client in context to respond to listApps implementation
+      (context.api as any).get = vi.fn().mockResolvedValue({
+        results: [
+          {
+            id: "SlackCLIAPI@1.0.0",
+            name: "Slack",
+            description: "Team communication",
+            primary_color: "#4A154B",
+            categories: ["communication"],
+          },
+        ],
+        next: null,
+      });
+
+      const result = await sdk.getApp({
+        appKey: "slack",
+      });
+
+      expect(result.data.title).toBe("Slack");
+      expect(result.data.key).toBe("SlackCLIAPI");
+      expect(result.data.current_implementation_id).toBe("SlackCLIAPI@1.0.0");
+      expect(result.data.version).toBe("1.0.0");
+    });
+  });
+
+  describe("error handling", () => {
+    it("should throw ZapierAppNotFoundError when app does not exist", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      // Mock API to return empty results (app not found)
+      (context.api as any).get = vi.fn().mockResolvedValue({
+        results: [],
+        next: null,
+      });
+
+      await expect(
+        sdk.getApp({
+          appKey: "nonexistent-app",
+        }),
+      ).rejects.toThrow(ZapierAppNotFoundError);
+    });
+  });
+
+  describe("data mapping", () => {
+    it("should return essential app properties", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      // Mock the API client in context to respond to listApps implementation
+      (context.api as any).get = vi.fn().mockResolvedValue({
+        results: [
+          {
+            id: "TestCLIAPI@1.0.0",
+            name: "Test App",
+            description: "Test description",
+            primary_color: "#FF0000",
+            categories: ["testing"],
+          },
+        ],
+        next: null,
+      });
+
+      const result = await sdk.getApp({
+        appKey: "test",
+      });
+
+      expect(result.data.title).toBeDefined();
+      expect(result.data.key).toBeDefined();
+      expect(result.data.current_implementation_id).toBeDefined();
+      expect(result.data.title).toBe("Test App");
+      expect(result.data.key).toBe("TestCLIAPI");
+    });
+  });
+});

package/src/plugins/getApp/index.ts

@@ -0,0 +1,66 @@
+import type { Plugin } from "../../types/plugin";
+import { createFunction } from "../../utils/function-utils";
+import { GetAppSchema } from "./schemas";
+import type { GetAppOptions } from "./schemas";
+import type { AppItem } from "../../types/domain";
+import { ZapierAppNotFoundError } from "../../types/errors";
+import type { ListAppsPluginProvides } from "../listApps";
+import type { GetSdkType } from "../../types/plugin";
+
+// GetApp plugin provides interface - getApp goes directly to SDK root
+export interface GetAppPluginProvides {
+  getApp: (options: GetAppOptions) => Promise<{ data: AppItem }>;
+  context: {
+    meta: {
+      getApp: {
+        inputSchema: typeof GetAppSchema;
+      };
+    };
+  };
+}
+
+// GetApp plugin depends on listApps SDK function
+export const getAppPlugin: Plugin<
+  GetSdkType<ListAppsPluginProvides>, // depends on listApps
+  {}, // no additional context dependencies
+  GetAppPluginProvides
+> = ({ sdk }) => {
+  const getApp = createFunction(async function getApp(options: GetAppOptions) {
+    const { appKey } = options;
+
+    // Use listApps to get the app by key
+    const appsIterator = sdk
+      .listApps({
+        ...options,
+        appKeys: [appKey],
+      })
+      .items();
+
+    // Get the first (and should be only) result
+    const apps = [];
+    for await (const app of appsIterator) {
+      apps.push(app);
+      break; // Only need the first result
+    }
+
+    if (apps.length === 0) {
+      throw new ZapierAppNotFoundError(appKey);
+    }
+
+    return {
+      data: apps[0],
+    };
+  }, GetAppSchema);
+
+  // Return flat structure - getApp goes directly to SDK
+  return {
+    getApp,
+    context: {
+      meta: {
+        getApp: {
+          inputSchema: GetAppSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/getApp/schemas.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { AppKeyPropertySchema } from "../../types/properties";
+import { withOutputSchema } from "../../utils/schema-utils";
+import { AppItemSchema } from "../../schemas/App";
+import type { AppItem } from "../../types/domain";
+import {
+  ZapierApiError,
+  ZapierAppNotFoundError,
+  ZapierValidationError,
+} from "../../types/errors";
+
+// Error types (now imported from types/errors)
+
+// Union of all possible errors for getApp
+export type GetAppError =
+  | ZapierAppNotFoundError
+  | ZapierApiError
+  | ZapierValidationError;
+
+// Pure Zod schema - no resolver metadata!
+export const GetAppSchema = withOutputSchema(
+  z
+    .object({
+      appKey: AppKeyPropertySchema.describe(
+        "App key of app to fetch (e.g., 'SlackCLIAPI')",
+      ),
+    })
+    .describe("Get detailed information about a specific app"),
+  AppItemSchema,
+);
+
+// Type inferred from schema
+export type GetAppOptions = z.infer<typeof GetAppSchema>;
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GetAppSdkFunction {
+  getApp: (options: GetAppOptions) => Promise<{ data: AppItem }>;
+}