@zapier/zapier-sdk 0.4.1 → 0.5.0

package/src/plugins/request/index.ts

@@ -0,0 +1,103 @@
+import type { Plugin } from "../../types/plugin";
+import type { ApiClient } from "../../api";
+import { RelayRequestSchema, type RelayRequestOptions } from "./schemas";
+import { createFunction } from "../../utils/function-utils";
+
+/**
+ * Transforms full URLs into Relay format: /relay/{domain}/{path}
+ *
+ * @param url - The full URL to transform (e.g., "https://api.github.com/user")
+ * @returns The relay path format (e.g., "/relay/api.github.com/user")
+ */
+function transformUrlToRelayPath(url: string | URL): string {
+  const targetUrl = new URL(url);
+
+  // Build the Relay path: /relay/{host}{pathname}{search}{hash}
+  // Use host instead of hostname to include port if present
+  const relayPath = `/relay/${targetUrl.host}${targetUrl.pathname}${targetUrl.search}${targetUrl.hash}`;
+
+  return relayPath;
+}
+
+export interface RequestPluginProvides {
+  request: (options: RelayRequestOptions) => Promise<Response>;
+  context: {
+    meta: {
+      request: {
+        inputSchema: typeof RelayRequestSchema;
+      };
+    };
+  };
+}
+
+export const requestPlugin: Plugin<
+  {}, // no SDK dependencies
+  { api: ApiClient }, // requires api in context
+  RequestPluginProvides
+> = ({ context }) => {
+  const request = createFunction(async function request(
+    options: RelayRequestOptions,
+  ): Promise<Response> {
+    const { api } = context;
+    const {
+      url,
+      method = "GET",
+      body,
+      headers: optionsHeaders,
+      authenticationId,
+      callbackUrl,
+      authenticationTemplate,
+    } = options;
+
+    // Transform full URL to relay path format
+    const relayPath = transformUrlToRelayPath(url);
+
+    // Build headers for the request
+    const headers: Record<string, string> = {};
+
+    // Copy existing headers
+    if (optionsHeaders) {
+      const headerEntries =
+        optionsHeaders instanceof Headers
+          ? Array.from(optionsHeaders.entries())
+          : Array.isArray(optionsHeaders)
+            ? optionsHeaders
+            : Object.entries(optionsHeaders);
+
+      for (const [key, value] of headerEntries) {
+        headers[key] = value;
+      }
+    }
+
+    // Add Relay-specific headers
+    if (authenticationId) {
+      headers["X-Relay-Authentication-Id"] = authenticationId.toString();
+    }
+
+    if (callbackUrl) {
+      headers["X-Relay-Callback-Url"] = callbackUrl;
+    }
+
+    if (authenticationTemplate) {
+      headers["X-Authentication-Template"] = authenticationTemplate;
+    }
+
+    // Use the API client's fetch method directly - let it handle auth automatically
+    return await api.fetch(relayPath, {
+      method,
+      body,
+      headers,
+    });
+  }, RelayRequestSchema);
+
+  return {
+    request,
+    context: {
+      meta: {
+        request: {
+          inputSchema: RelayRequestSchema,
+        },
+      },
+    },
+  };
+};

package/src/{functions → plugins}/request/schemas.ts

@@ -1,5 +1,4 @@
 import { z } from "zod";
-import type { FunctionOptions } from "../../types/domain";
 
 // Pure Zod schema for the request function
 export const RelayRequestSchema = z
@@ -12,7 +11,7 @@ export const RelayRequestSchema = z
       .enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"])
       .optional()
       .describe("HTTP method"),
-    body: z.string().optional().describe("Request body as a string"),
+    body: z.any().optional().describe("Request body as a string"),
     authenticationId: z
       .number()
       .int()
@@ -29,16 +28,28 @@ export const RelayRequestSchema = z
       .describe(
         "Optional JSON string authentication template to bypass Notary lookup",
       ),
-    headers: z.record(z.string()).optional().describe("Request headers"),
+    headers: z
+      .union([
+        z.record(z.string()),
+        z.instanceof(Headers),
+        z.array(z.tuple([z.string(), z.string()])),
+      ])
+      .optional()
+      .describe("Request headers"),
+  })
+  .extend({
+    relayBaseUrl: z.string().optional().describe("Base URL for Relay service"),
   })
   .describe("Make authenticated HTTP requests through Zapier's Relay service");
 
-// Type inferred from schema + function config
-export type RelayRequestOptions = z.infer<typeof RelayRequestSchema> &
-  FunctionOptions & {
-    /** Base URL for Relay service */
-    relayBaseUrl?: string;
-  };
+// Type inferred from schema
+export type RelayRequestOptions = z.infer<typeof RelayRequestSchema>;
+
+// Error union for this function
+export type RelayRequestError =
+  | import("../../types/errors").ZapierApiError
+  | import("../../types/errors").ZapierValidationError
+  | import("../../types/errors").ZapierUnknownError;
 
 // SDK function interface
 export interface RelayRequestSdkFunction {

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

@@ -0,0 +1,387 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ZapierValidationError, ZapierActionError } from "../../types/errors";
+import { runActionPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import type { ApiClient } from "../../api";
+import type { RunActionOptions } from "./schemas";
+import type { ActionItem } from "../../types/domain";
+
+const mockAction: ActionItem = {
+  type: "action",
+  key: "send_message",
+  title: "Send Message",
+  description: "Send a message to a channel",
+  app_key: "slack",
+  action_type: "write",
+};
+
+const mockActionResponse = {
+  results: [
+    {
+      id: "msg_123",
+      text: "Hello, world!",
+      channel: "#general",
+      user: "user_456",
+    },
+  ],
+  meta: {
+    next_cursor: null,
+  },
+};
+
+describe("runAction plugin", () => {
+  let mockApiClient: ApiClient;
+  let mockGetAction: any;
+  let mockGetApp: any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockApiClient = {
+      post: vi.fn().mockResolvedValue({ data: { id: "run_123" } }),
+      poll: vi.fn().mockResolvedValue({ results: mockActionResponse.results }),
+    } as Partial<ApiClient> as ApiClient;
+
+    mockGetAction = vi.fn().mockResolvedValue({
+      data: mockAction,
+    });
+
+    mockGetApp = vi.fn().mockResolvedValue({
+      data: { current_implementation_id: "SlackCLIAPI" },
+    });
+  });
+
+  function createTestSdk() {
+    return createSdk(
+      { getAction: mockGetAction, getApp: mockGetApp }, // Provide getAction and getApp in SDK
+      { api: mockApiClient, meta: {} },
+    ).addPlugin(runActionPlugin as any);
+  }
+
+  describe("schema validation", () => {
+    it("should throw validation error for missing appKey", () => {
+      const sdk = createTestSdk();
+      expect(() => {
+        sdk.runAction({
+          actionType: "write",
+          actionKey: "send_message",
+          inputs: { message: "Hello" },
+        } as Partial<RunActionOptions> as RunActionOptions);
+      }).toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for missing actionType", () => {
+      const sdk = createTestSdk();
+      expect(() => {
+        sdk.runAction({
+          appKey: "slack",
+          actionKey: "send_message",
+          inputs: { message: "Hello" },
+        } as Partial<RunActionOptions> as RunActionOptions);
+      }).toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for missing actionKey", () => {
+      const sdk = createTestSdk();
+      expect(() => {
+        sdk.runAction({
+          appKey: "slack",
+          actionType: "write",
+          inputs: { message: "Hello" },
+        } as Partial<RunActionOptions> as RunActionOptions);
+      }).toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with all required fields", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+      });
+
+      expect(result.data).toHaveLength(1);
+      expect(result.data[0]).toEqual(mockActionResponse.results[0]);
+    });
+  });
+
+  describe("action execution", () => {
+    it("should validate action exists using getAction", async () => {
+      const sdk = createTestSdk();
+      await sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+      });
+
+      expect(mockGetAction).toHaveBeenCalledWith({
+        appKey: "slack",
+        actionKey: "send_message",
+        actionType: "write",
+      });
+    });
+
+    it("should throw error when action type doesn't match", async () => {
+      // Mock getAction to return an action with different type
+      mockGetAction.mockResolvedValue({
+        data: { ...mockAction, action_type: "read" },
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.runAction({
+          appKey: "slack",
+          actionType: "write", // Different from mocked action type
+          actionKey: "send_message",
+          inputs: { message: "Hello" },
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should execute action with correct API call", async () => {
+      const sdk = createTestSdk();
+      await sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello", channel: "#general" },
+        authenticationId: 12345,
+      });
+
+      expect(mockApiClient.post).toHaveBeenCalledWith("/api/actions/v1/runs", {
+        data: {
+          selected_api: "SlackCLIAPI",
+          action_key: "send_message",
+          action_type: "write",
+          inputs: { message: "Hello", channel: "#general" },
+          authentication_id: 12345,
+        },
+      });
+
+      expect(mockApiClient.poll).toHaveBeenCalledWith(
+        "/api/actions/v1/runs/run_123",
+        {
+          successStatus: 200,
+          pendingStatus: 202,
+          resultExtractor: expect.any(Function),
+        },
+      );
+    });
+
+    it("should execute action without authentication ID", async () => {
+      const sdk = createTestSdk();
+      await sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+      });
+
+      expect(mockApiClient.post).toHaveBeenCalledWith("/api/actions/v1/runs", {
+        data: {
+          selected_api: "SlackCLIAPI",
+          action_key: "send_message",
+          action_type: "write",
+          inputs: { message: "Hello" },
+        },
+      });
+    });
+
+    it("should handle pagination cursor", async () => {
+      const sdk = createTestSdk();
+      const runActionResult = sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+      });
+
+      // Simulate pagination by getting an iterator
+      const iterator = runActionResult[Symbol.asyncIterator]();
+      await iterator.next();
+
+      expect(mockApiClient.post).toHaveBeenCalledWith(
+        "/api/actions/v1/runs",
+        expect.objectContaining({
+          data: expect.objectContaining({
+            inputs: { message: "Hello" },
+            selected_api: "SlackCLIAPI",
+            action_key: "send_message",
+            action_type: "write",
+          }),
+        }),
+      );
+    });
+
+    it("should return results in correct format", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+      });
+
+      expect(result.data).toEqual(mockActionResponse.results);
+    });
+
+    it("should handle single result (not array)", async () => {
+      const singleResult = { id: "msg_123", text: "Hello" };
+      mockApiClient.post = vi
+        .fn()
+        .mockResolvedValue({ data: { id: "run_123" } });
+      mockApiClient.poll = vi.fn().mockResolvedValue({
+        results: [singleResult], // Poll returns the actual results
+      });
+
+      const sdk = createTestSdk();
+      const result = await sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+      });
+
+      expect(result.data).toEqual([singleResult]); // Should be wrapped in array
+    });
+  });
+
+  describe("error handling", () => {
+    it("should handle action execution errors", async () => {
+      mockApiClient.post = vi
+        .fn()
+        .mockResolvedValue({ data: { id: "run_123" } });
+      mockApiClient.poll = vi.fn().mockResolvedValue({
+        results: [],
+        errors: [
+          { title: "Invalid inputs", detail: "Message cannot be empty" },
+        ],
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.runAction({
+          appKey: "slack",
+          actionType: "write",
+          actionKey: "send_message",
+          inputs: { message: "" }, // Invalid input
+        }),
+      ).rejects.toThrow(ZapierActionError);
+    });
+
+    it("should handle server errors", async () => {
+      mockApiClient.post = vi.fn().mockImplementation((_url, options) => {
+        const error = options.customErrorHandler?.({
+          status: 500,
+          data: { message: "Internal server error" },
+        });
+        if (error) throw error;
+        throw new Error("Server Error");
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.runAction({
+          appKey: "slack",
+          actionType: "write",
+          actionKey: "send_message",
+          inputs: { message: "Hello" },
+        }),
+      ).rejects.toThrow();
+    });
+
+    it("should propagate getAction errors", async () => {
+      mockGetAction.mockRejectedValue(new Error("Action not found"));
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.runAction({
+          appKey: "slack",
+          actionType: "write",
+          actionKey: "nonexistent",
+          inputs: { message: "Hello" },
+        }),
+      ).rejects.toThrow("Action not found");
+    });
+
+    it("should handle unexpected errors during execution", async () => {
+      mockApiClient.post = vi
+        .fn()
+        .mockRejectedValue(new Error("Network error"));
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.runAction({
+          appKey: "slack",
+          actionType: "write",
+          actionKey: "send_message",
+          inputs: { message: "Hello" },
+        }),
+      ).rejects.toThrow("Network error");
+    });
+  });
+
+  describe("pagination", () => {
+    it("should support maxItems limit", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+        maxItems: 1,
+      });
+
+      expect(result.data).toHaveLength(1);
+    });
+
+    it("should support async iteration over pages", async () => {
+      const sdk = createTestSdk();
+      const runActionResult = sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+      });
+
+      const pages = [];
+      for await (const page of runActionResult) {
+        pages.push(page);
+        break; // Just get first page for testing
+      }
+
+      expect(pages).toHaveLength(1);
+      expect(pages[0].data).toEqual(mockActionResponse.results);
+    });
+
+    it("should support async iteration over individual items", async () => {
+      const sdk = createTestSdk();
+      const runActionResult = sdk.runAction({
+        appKey: "slack",
+        actionType: "write",
+        actionKey: "send_message",
+        inputs: { message: "Hello" },
+        maxItems: 1,
+      });
+
+      const items = [];
+      for await (const item of runActionResult.items()) {
+        items.push(item);
+      }
+
+      expect(items).toHaveLength(1);
+      expect(items[0]).toEqual(mockActionResponse.results[0]);
+    });
+  });
+
+  describe("context and metadata", () => {
+    it("should provide context with meta information", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect((context.meta as any).runAction).toBeDefined();
+      expect((context.meta as any).runAction.inputSchema).toBeDefined();
+    });
+  });
+});