@zapier/zapier-sdk 0.4.1 → 0.5.0

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

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

@@ -0,0 +1,284 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+  ZapierValidationError,
+  ZapierAuthenticationError,
+  ZapierResourceNotFoundError,
+} from "../../types/errors";
+import { getAuthenticationPlugin } from "./index";
+import { createSdk } from "../../sdk";
+import type { ApiClient } from "../../api";
+import type { GetAuthenticationOptions } from "./schemas";
+import type { Authentication } from "../../api/types";
+
+const mockAuthenticationResponse: Authentication = {
+  id: 123,
+  date: "2021-01-01",
+  account_id: 456 as any,
+  selected_api: "SlackCLIAPI@1.21.1",
+  is_invite_only: false,
+  is_private: false,
+  shared_with_all: false,
+  is_stale: "false",
+  marked_stale_at: null,
+  label: "My Slack Workspace",
+  title: "My Slack Workspace",
+};
+
+describe("getAuthentication plugin", () => {
+  let mockApiClient: ApiClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockApiClient = {
+      get: vi.fn().mockResolvedValue(mockAuthenticationResponse),
+    } as Partial<ApiClient> as ApiClient;
+  });
+
+  function createTestSdk() {
+    return createSdk({}, { api: mockApiClient, meta: {} }).addPlugin(
+      getAuthenticationPlugin,
+    );
+  }
+
+  describe("schema validation", () => {
+    it("should throw validation error for missing authenticationId", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAuthentication({} as GetAuthenticationOptions),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for invalid authenticationId type", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAuthentication({
+          authenticationId: "invalid" as any,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for negative authenticationId", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAuthentication({
+          authenticationId: -1,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should throw validation error for zero authenticationId", async () => {
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAuthentication({
+          authenticationId: 0,
+        }),
+      ).rejects.toThrow(ZapierValidationError);
+    });
+
+    it("should pass validation with valid authenticationId", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.getAuthentication({
+        authenticationId: 123,
+      });
+
+      expect(result.data).toBeDefined();
+    });
+  });
+
+  describe("API integration", () => {
+    it("should call the correct API endpoint", async () => {
+      const sdk = createTestSdk();
+      await sdk.getAuthentication({ authenticationId: 123 });
+
+      expect(mockApiClient.get).toHaveBeenCalledWith(
+        "/api/v4/authentications/123/",
+        expect.objectContaining({
+          authRequired: true,
+          customErrorHandler: expect.any(Function),
+        }),
+      );
+    });
+
+    it("should return normalized authentication data", async () => {
+      const sdk = createTestSdk();
+      const result = await sdk.getAuthentication({ authenticationId: 123 });
+
+      expect(result.data).toEqual({
+        id: 123,
+        date: "2021-01-01",
+        account_id: 456 as any,
+        implementation_id: "SlackCLIAPI@1.21.1",
+        is_invite_only: false,
+        is_private: false,
+        shared_with_all: false,
+        is_expired: "false",
+        expired_at: null,
+        label: "My Slack Workspace",
+        title: "My Slack Workspace",
+        app_key: "SlackCLIAPI",
+        version: "1.21.1",
+        user_id: undefined, // customuser_id wasn't in mock data
+        is_stale: "false", // Original field preserved
+        marked_stale_at: null, // Original field preserved
+      });
+    });
+  });
+
+  describe("error handling", () => {
+    it("should throw ZapierAuthenticationError for 401 responses", async () => {
+      const customErrorHandler = vi
+        .fn()
+        .mockReturnValue(
+          new ZapierAuthenticationError(
+            "Authentication failed. Your token may not have permission to access authentications or may be expired. (HTTP 401)",
+            { statusCode: 401 },
+          ),
+        );
+
+      mockApiClient.get = vi.fn().mockImplementation(() => {
+        const error = customErrorHandler({ status: 401 });
+        throw error;
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAuthentication({ authenticationId: 123 }),
+      ).rejects.toThrow(ZapierAuthenticationError);
+    });
+
+    it("should throw ZapierAuthenticationError for 403 responses", async () => {
+      const customErrorHandler = vi
+        .fn()
+        .mockReturnValue(
+          new ZapierAuthenticationError(
+            "Access forbidden. Your token may not have the required scopes to get authentication 123. (HTTP 403)",
+            { statusCode: 403 },
+          ),
+        );
+
+      mockApiClient.get = vi.fn().mockImplementation(() => {
+        const error = customErrorHandler({ status: 403 });
+        throw error;
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAuthentication({ authenticationId: 123 }),
+      ).rejects.toThrow(ZapierAuthenticationError);
+    });
+
+    it("should throw ZapierResourceNotFoundError for 404 responses", async () => {
+      const customErrorHandler = vi.fn().mockReturnValue(
+        new ZapierResourceNotFoundError(
+          "Authentication 123 not found. It may not exist or you may not have access to it. (HTTP 404)",
+          {
+            resourceType: "Authentication",
+            resourceId: "123",
+          },
+        ),
+      );
+
+      mockApiClient.get = vi.fn().mockImplementation(() => {
+        const error = customErrorHandler({ status: 404 });
+        throw error;
+      });
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAuthentication({ authenticationId: 123 }),
+      ).rejects.toThrow(ZapierResourceNotFoundError);
+    });
+
+    it("should handle network errors", async () => {
+      mockApiClient.get = vi.fn().mockRejectedValue(new Error("Network error"));
+
+      const sdk = createTestSdk();
+      await expect(
+        sdk.getAuthentication({ authenticationId: 123 }),
+      ).rejects.toThrow("Network error");
+    });
+  });
+
+  describe("data transformation", () => {
+    it("should map is_stale to is_expired and marked_stale_at to expired_at", async () => {
+      const authWithExpiration = {
+        ...mockAuthenticationResponse,
+        is_stale: "true",
+        marked_stale_at: "2021-06-01",
+      };
+
+      mockApiClient.get = vi.fn().mockResolvedValue(authWithExpiration);
+
+      const sdk = createTestSdk();
+      const result = await sdk.getAuthentication({ authenticationId: 123 });
+
+      expect(result.data.is_expired).toBe("true");
+      expect(result.data.expired_at).toBe("2021-06-01");
+    });
+
+    it("should preserve all original authentication fields", async () => {
+      const authWithAllFields = {
+        id: 123,
+        date: "2021-01-01",
+        lastchanged: "2021-01-02",
+        account_id: 456 as any,
+        customuser_id: 789,
+        selected_api: "SlackCLIAPI@1.21.1",
+        destination_selected_api: "SlackDestAPI@1.0.0",
+        is_invite_only: true,
+        is_private: true,
+        shared_with_all: false,
+        is_stale: "true",
+        is_shared: "false",
+        marked_stale_at: "2021-06-01",
+        label: "Auth Label",
+        title: "Auth Title",
+        identifier: "auth-identifier",
+        url: "https://example.com",
+        groups: "group1,group2",
+        members: "user1,user2",
+        permissions: { read: true, write: false },
+      };
+
+      mockApiClient.get = vi.fn().mockResolvedValue(authWithAllFields);
+
+      const sdk = createTestSdk();
+      const result = await sdk.getAuthentication({ authenticationId: 123 });
+      const auth = result.data;
+
+      // Verify original fields are preserved
+      expect(auth.id).toBe(123);
+      expect(auth.date).toBe("2021-01-01");
+      expect(auth.lastchanged).toBe("2021-01-02");
+      expect(auth.account_id).toBe(456);
+      expect(auth.user_id).toBe(789);
+      expect(auth.implementation_id).toBe("SlackCLIAPI@1.21.1");
+      expect(auth.destination_selected_api).toBe("SlackDestAPI@1.0.0");
+      expect(auth.is_invite_only).toBe(true);
+      expect(auth.is_private).toBe(true);
+      expect(auth.shared_with_all).toBe(false);
+      expect(auth.is_shared).toBe("false");
+      expect(auth.label).toBe("Auth Label");
+      expect(auth.title).toBe("Auth Title");
+      expect(auth.identifier).toBe("auth-identifier");
+      expect(auth.url).toBe("https://example.com");
+      expect(auth.groups).toBe("group1,group2");
+      expect(auth.members).toBe("user1,user2");
+      expect(auth.permissions).toEqual({ read: true, write: false });
+
+      // Verify mapped fields
+      expect(auth.is_expired).toBe("true");
+      expect(auth.expired_at).toBe("2021-06-01");
+    });
+  });
+
+  describe("context and metadata", () => {
+    it("should provide context with meta information", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect((context.meta as any).getAuthentication).toBeDefined();
+      expect((context.meta as any).getAuthentication.inputSchema).toBeDefined();
+    });
+  });
+});

package/src/plugins/getAuthentication/index.ts

@@ -0,0 +1,86 @@
+import type { Plugin } from "../../types/plugin";
+import type { ApiClient } from "../../api";
+import type { Authentication } from "../../api/types";
+import type { AuthenticationItem } from "../../types/domain";
+import {
+  GetAuthenticationSchema,
+  type GetAuthenticationOptions,
+} from "./schemas";
+import {
+  ZapierAuthenticationError,
+  ZapierResourceNotFoundError,
+} from "../../types/errors";
+import { createFunction } from "../../utils/function-utils";
+import { normalizeAuthenticationItem } from "../../utils/domain-utils";
+
+export interface GetAuthenticationPluginProvides {
+  getAuthentication: (
+    options: GetAuthenticationOptions,
+  ) => Promise<{ data: AuthenticationItem }>;
+  context: {
+    meta: {
+      getAuthentication: {
+        inputSchema: typeof GetAuthenticationSchema;
+      };
+    };
+  };
+}
+
+export const getAuthenticationPlugin: Plugin<
+  {}, // no SDK dependencies
+  { api: ApiClient }, // requires api in context
+  GetAuthenticationPluginProvides
+> = ({ context }) => {
+  const getAuthentication = createFunction(async function getAuthentication(
+    options: GetAuthenticationOptions,
+  ) {
+    const { api } = context;
+    const { authenticationId } = options;
+
+    const data: Authentication = await api.get(
+      `/api/v4/authentications/${authenticationId}/`,
+      {
+        customErrorHandler: ({ status }: { status: number }) => {
+          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 get authentication ${authenticationId}. (HTTP ${status})`,
+              { statusCode: status },
+            );
+          }
+          if (status === 404) {
+            return new ZapierResourceNotFoundError(
+              `Authentication ${authenticationId} not found. It may not exist or you may not have access to it. (HTTP ${status})`,
+              {
+                resourceType: "Authentication",
+                resourceId: String(authenticationId),
+              },
+            );
+          }
+          return undefined;
+        },
+        authRequired: true,
+      },
+    );
+
+    return {
+      data: normalizeAuthenticationItem(data),
+    };
+  }, GetAuthenticationSchema);
+
+  return {
+    getAuthentication,
+    context: {
+      meta: {
+        getAuthentication: {
+          inputSchema: GetAuthenticationSchema,
+        },
+      },
+    },
+  };
+};

package/src/plugins/getAuthentication/schemas.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import type { AuthenticationItem } from "../../types/domain";
+
+// Pure Zod schema - no resolver metadata!
+export const GetAuthenticationSchema = z
+  .object({
+    authenticationId: z
+      .number()
+      .int()
+      .positive()
+      .describe("Authentication ID to retrieve"),
+  })
+  .describe("Get a specific authentication by ID");
+
+// Type inferred from schema
+export type GetAuthenticationOptions = z.infer<typeof GetAuthenticationSchema>;
+
+// Error union for this function
+export type GetAuthenticationError =
+  | import("../../types/errors").ZapierAuthenticationError
+  | import("../../types/errors").ZapierResourceNotFoundError
+  | import("../../types/errors").ZapierApiError
+  | import("../../types/errors").ZapierValidationError
+  | import("../../types/errors").ZapierUnknownError;
+
+// SDK function interface - ready to be mixed into main SDK interface
+export interface GetAuthenticationSdkFunction {
+  getAuthentication: (
+    options: GetAuthenticationOptions,
+  ) => Promise<{ data: AuthenticationItem }>;
+}

package/src/plugins/getProfile/index.ts

@@ -0,0 +1,55 @@
+import type { GetProfileOptions } from "./schemas";
+import type { UserProfile, ApiClient } from "../../api/types";
+import { createFunction } from "../../utils/function-utils";
+import type { Plugin } from "../../types/plugin";
+import type { UserProfileItem } from "../../types/domain";
+import { GetProfileSchema } from "./schemas";
+
+// GetProfile plugin provides interface - getProfile goes directly to SDK root
+export interface GetProfilePluginProvides {
+  getProfile: (
+    options?: GetProfileOptions,
+  ) => Promise<{ data: UserProfileItem }>;
+  context: {
+    meta: {
+      getProfile: {
+        inputSchema: typeof GetProfileSchema;
+      };
+    };
+  };
+}
+
+// Direct plugin function - takes options + sdk + context in one object
+export const getProfilePlugin: Plugin<
+  {}, // no SDK dependencies
+  { api: ApiClient }, // requires api in context
+  GetProfilePluginProvides
+> = ({ context }) => {
+  const getProfile = createFunction(async function getProfile() {
+    const profile: UserProfile = await context.api.get("/api/v4/profile/", {
+      authRequired: true,
+    });
+
+    // Remove user_id since that's our internal user ID which could confuse things!
+    const { user_id: _unusedUserId, ...data } = profile;
+
+    return {
+      data: {
+        ...data, // Pass through all API response fields
+        full_name: `${profile.first_name} ${profile.last_name}`, // Computed field
+      },
+    };
+  }, GetProfileSchema);
+
+  // Return flat structure - getProfile goes directly to SDK
+  return {
+    getProfile,
+    context: {
+      meta: {
+        getProfile: {
+          inputSchema: GetProfileSchema,
+        },
+      },
+    },
+  };
+};