@zapier/zapier-sdk 0.5.2 → 0.6.0

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

@@ -0,0 +1,439 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { manifestPlugin, loadManifestFromFile } from "./index";
+import { createSdk } from "../../sdk";
+import type { Manifest } from "./schemas";
+
+// Mock fs and path modules
+vi.mock("fs", () => ({
+  readFileSync: vi.fn(),
+}));
+
+vi.mock("path", () => ({
+  resolve: vi.fn((path) => `/resolved/${path}`),
+}));
+
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import type { ApiClient } from "../../api";
+
+const mockReadFileSync = vi.mocked(readFileSync);
+const mockResolve = vi.mocked(resolve);
+
+describe("manifestPlugin", () => {
+  const mockManifest = {
+    apps: {
+      slack: {
+        implementationName: "SlackCLIAPI",
+        version: "1.21.1",
+      },
+      "google-sheets": {
+        implementationName: "GoogleSheetsCLIAPI",
+        version: "2.0.0",
+      },
+    },
+  };
+
+  const mockManifestContent = JSON.stringify(mockManifest);
+
+  let mockApiClient: ApiClient;
+  let mockSdk: any;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+
+    mockApiClient = {
+      get: vi.fn().mockResolvedValue({
+        count: 1,
+        next: null,
+        previous: null,
+        results: [
+          {
+            selected_api: "SlackCLIAPI@1.29.0",
+            app_id: null,
+            service_id: null,
+            auth_type: "oauth",
+            auth_fields: [
+              {
+                key: "access_token",
+                required: true,
+                type: "unicode",
+                computed: true,
+              },
+            ],
+            is_deprecated: false,
+            is_private_only: false,
+            is_invite_only: false,
+            is_beta: false,
+            is_premium: false,
+            is_hidden: false,
+            name: "Slack (1.29.0)",
+            name_clean: "Slack",
+            version: "1.29.0",
+            slug: null,
+            images: {
+              url_16x16:
+                "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=16&ixlib=python-3.0.0&q=50&w=16",
+              url_32x32:
+                "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=32&ixlib=python-3.0.0&q=50&w=32",
+              url_64x64:
+                "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=64&ixlib=python-3.0.0&q=50&w=64",
+              url_128x128:
+                "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=128&ixlib=python-3.0.0&q=50&w=128",
+            },
+            primary_color: null,
+            secondary_color: null,
+            classification: "third-party",
+            current_implementation: "SlackCLIAPI@1.30.0",
+            is_adoptable: true,
+            is_usable: true,
+            update_cta_level: "info",
+            update_cta_message:
+              "This version is legacy. Consider updating to the latest version for better support.",
+            badges: [
+              {
+                label: "Legacy",
+                color: "primary",
+                tooltip_markdown:
+                  "This version is legacy. Consider updating to the latest version for better support.",
+              },
+            ],
+          },
+        ],
+      }),
+    } as Partial<ApiClient> as ApiClient;
+
+    mockSdk = {
+      listApps: vi.fn().mockReturnValue({
+        items: vi.fn().mockReturnValue(
+          [
+            {
+              title: "Slack",
+              key: "slack",
+              current_implementation_id: "SlackCLIAPI@1.30.0",
+              description: "Team communication platform",
+            },
+          ][Symbol.iterator](),
+        ),
+      }),
+    };
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  const apiPlugin = () => ({
+    context: {
+      api: mockApiClient,
+    },
+  });
+
+  const listAppsMockPlugin = () => ({
+    listApps: mockSdk.listApps,
+    context: {
+      meta: {
+        listApps: {
+          inputSchema: {} as any,
+        },
+      },
+    },
+  });
+
+  function createTestSdk(options: any = {}) {
+    return createSdk(options)
+      .addPlugin(apiPlugin)
+      .addPlugin(listAppsMockPlugin)
+      .addPlugin(manifestPlugin);
+  }
+
+  describe("plugin initialization", () => {
+    it("should provide manifest context with direct manifest", () => {
+      const sdk = createTestSdk({ manifest: mockManifest });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toEqual(mockManifest);
+
+      expect(context.getVersionedImplementationId).toBeInstanceOf(Function);
+      expect(context.getImplementation).toBeInstanceOf(Function);
+    });
+
+    it("should provide manifest context with manifestPath", () => {
+      mockReadFileSync.mockReturnValue(mockManifestContent);
+
+      const sdk = createTestSdk({ manifestPath: "manifest.json" });
+      const context = sdk.getContext();
+
+      expect(mockResolve).toHaveBeenCalledWith("manifest.json");
+      expect(mockReadFileSync).toHaveBeenCalledWith(
+        "/resolved/manifest.json",
+        "utf8",
+      );
+      expect(context.manifest).toEqual(mockManifest);
+    });
+
+    it("should provide null manifest when no manifest or path provided", () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      expect(context.manifest).toBeNull();
+    });
+
+    it("should prioritize direct manifest over manifestPath", () => {
+      mockReadFileSync.mockReturnValue(
+        '{"apps": {"other": {"implementationName": "Other", "version": "1.0.0"}}}',
+      );
+
+      const sdk = createTestSdk({
+        manifest: mockManifest,
+        manifestPath: "manifest.json",
+      });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toEqual(mockManifest);
+      expect(mockReadFileSync).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("getVersionedImplementationId function", () => {
+    it("should return versioned implementation ID when app exists in manifest", async () => {
+      const sdk = createTestSdk({ manifest: mockManifest });
+      const context = sdk.getContext();
+
+      const result = await context.getVersionedImplementationId("slack");
+      expect(result).toBe("SlackCLIAPI@1.21.1");
+    });
+
+    it("should fetch and return versioned implementation ID when app not in manifest", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      const result = await context.getVersionedImplementationId("slack");
+      expect(result).toBe("SlackCLIAPI@1.30.0");
+    });
+
+    it("should return null when app does not exist", async () => {
+      mockSdk.listApps = vi.fn().mockReturnValue({
+        items: vi.fn().mockReturnValue([][Symbol.iterator]()),
+      });
+
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      const result = await context.getVersionedImplementationId("nonexistent");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("getImplementation function", () => {
+    it("should return app from manifest when available", async () => {
+      const sdk = createTestSdk({ manifest: mockManifest });
+      const context = sdk.getContext();
+
+      const result = await context.getImplementation("slack");
+      expect(result).toBeDefined();
+      expect(mockApiClient.get).toHaveBeenCalledWith(
+        "/api/v4/implementations/",
+        {
+          searchParams: {
+            selected_apis: "SlackCLIAPI@1.21.1",
+          },
+        },
+      );
+    });
+
+    it("should fetch app from API when not in manifest", async () => {
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      const result = await context.getImplementation("slack");
+      expect(result).toBeDefined();
+      expect(result?.title).toBe("Slack");
+      expect(result?.current_implementation_id).toBe("SlackCLIAPI@1.30.0");
+    });
+
+    it("should return null when app cannot be fetched", async () => {
+      mockSdk.listApps = vi.fn().mockReturnValue({
+        items: vi.fn().mockReturnValue([][Symbol.iterator]()),
+      });
+
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      const result = await context.getImplementation("nonexistent");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("manifest parsing", () => {
+    it("should parse valid manifest content", () => {
+      const sdk = createTestSdk({ manifest: mockManifest });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toEqual(mockManifest);
+    });
+
+    it("should handle manifest with missing version", () => {
+      const manifestWithoutVersion: Manifest = {
+        apps: {
+          slack: {
+            implementationName: "SlackCLIAPI",
+          },
+        },
+      };
+
+      const sdk = createTestSdk({ manifest: manifestWithoutVersion });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toEqual(manifestWithoutVersion);
+    });
+
+    it("should handle empty manifest", () => {
+      const sdk = createTestSdk({ manifest: {} });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toEqual({});
+    });
+  });
+
+  describe("file loading", () => {
+    it("should load manifest from file successfully", () => {
+      mockReadFileSync.mockReturnValue(mockManifestContent);
+
+      const sdk = createTestSdk({ manifestPath: "manifest.json" });
+      const context = sdk.getContext();
+
+      expect(mockResolve).toHaveBeenCalledWith("manifest.json");
+      expect(mockReadFileSync).toHaveBeenCalledWith(
+        "/resolved/manifest.json",
+        "utf8",
+      );
+      expect(context.manifest).toEqual(mockManifest);
+    });
+
+    it("should handle file read errors gracefully", () => {
+      mockReadFileSync.mockImplementation(() => {
+        throw new Error("File not found");
+      });
+
+      const sdk = createTestSdk({ manifestPath: "nonexistent.json" });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toBeNull();
+      expect(console.warn).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Failed to load manifest from nonexistent.json",
+        ),
+        expect.any(Error),
+      );
+    });
+
+    it("should handle invalid JSON gracefully", () => {
+      mockReadFileSync.mockReturnValue("invalid json content");
+
+      const sdk = createTestSdk({ manifestPath: "invalid.json" });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toBeNull();
+      expect(console.warn).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Failed to parse manifest from /resolved/invalid.json",
+        ),
+        expect.any(SyntaxError),
+      );
+    });
+
+    it("should handle JSON without apps property", () => {
+      mockReadFileSync.mockReturnValue('{"other": "data"}');
+
+      const sdk = createTestSdk({ manifestPath: "no-apps.json" });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toBeNull();
+    });
+
+    it("should handle JSON with invalid apps format", () => {
+      mockReadFileSync.mockReturnValue('{"apps": "not an object"}');
+
+      const sdk = createTestSdk({ manifestPath: "invalid-apps.json" });
+      const context = sdk.getContext();
+
+      expect(context.manifest).toBeNull();
+    });
+  });
+
+  describe("integration with SDK", () => {
+    it("should work with createSdk", async () => {
+      const sdk = createSdk({ manifest: mockManifest })
+        .addPlugin(apiPlugin)
+        .addPlugin(listAppsMockPlugin)
+        .addPlugin(manifestPlugin);
+      const context = sdk.getContext();
+
+      expect(context.manifest).toEqual(mockManifest);
+      const versionedId = await context.getVersionedImplementationId("slack");
+      expect(versionedId).toBe("SlackCLIAPI@1.21.1");
+    });
+  });
+});
+
+describe("loadManifestFromFile", () => {
+  const mockManifestContent = JSON.stringify({
+    apps: {
+      slack: {
+        implementationName: "SlackCLIAPI",
+        version: "1.21.1",
+      },
+      "google-sheets": {
+        implementationName: "GoogleSheetsCLIAPI",
+        version: "2.0.0",
+      },
+    },
+  });
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("should load and parse manifest from file", () => {
+    mockReadFileSync.mockReturnValue(mockManifestContent);
+
+    const result = loadManifestFromFile("manifest.json");
+
+    expect(mockResolve).toHaveBeenCalledWith("manifest.json");
+    expect(mockReadFileSync).toHaveBeenCalledWith(
+      "/resolved/manifest.json",
+      "utf8",
+    );
+    expect(result).toEqual({
+      apps: {
+        slack: {
+          implementationName: "SlackCLIAPI",
+          version: "1.21.1",
+        },
+        "google-sheets": {
+          implementationName: "GoogleSheetsCLIAPI",
+          version: "2.0.0",
+        },
+      },
+    });
+  });
+
+  it("should handle file read errors", () => {
+    mockReadFileSync.mockImplementation(() => {
+      throw new Error("File not found");
+    });
+
+    const result = loadManifestFromFile("nonexistent.json");
+
+    expect(result).toBeNull();
+  });
+
+  it("should handle invalid JSON content", () => {
+    mockReadFileSync.mockReturnValue("invalid json");
+
+    const result = loadManifestFromFile("invalid.json");
+
+    expect(result).toBeNull();
+  });
+});

package/src/plugins/manifest/index.ts

@@ -0,0 +1,171 @@
+import { readFileSync } from "fs";
+import { resolve } from "path";
+import type {
+  GetImplementation,
+  GetManifestEntry,
+  GetVersionedImplementationId,
+  Manifest,
+} from "./schemas";
+import { ManifestSchema, ManifestPluginOptionsSchema } from "./schemas";
+import type { GetSdkType, Plugin } from "../../types/plugin";
+import { z } from "zod";
+import { ApiClient } from "../../api";
+import { ListAppsPluginProvides } from "../listApps";
+import { ImplementationsResponse } from "../../api/types";
+import {
+  normalizeImplementationToAppItem,
+  splitVersionedKey,
+} from "../../utils/domain-utils";
+
+export type ManifestPluginOptions = z.infer<typeof ManifestPluginOptionsSchema>;
+
+export interface ManifestPluginProvides {
+  context: {
+    manifest: Manifest | null;
+    getVersionedImplementationId: GetVersionedImplementationId;
+    getManifestEntry: GetManifestEntry;
+    getImplementation: GetImplementation;
+  };
+}
+
+/**
+ * Parse manifest content from a string
+ */
+function parseManifestContent(
+  content: string,
+  source: string,
+): Manifest | null {
+  try {
+    const parsed = JSON.parse(content);
+
+    if (parsed?.apps && typeof parsed?.apps === "object") {
+      const result = ManifestSchema.safeParse(parsed);
+      if (result.success) {
+        return result.data;
+      }
+      console.warn(`⚠️ Invalid manifest format in ${source}: ${result.error}`);
+    }
+
+    return null;
+  } catch (error) {
+    console.warn(`⚠️ Failed to parse manifest from ${source}:`, error);
+    return null;
+  }
+}
+
+/**
+ * Load manifest from a file path synchronously
+ * Supports local files (Node.js only)
+ */
+export function loadManifestFromFile(filePath: string): Manifest | null {
+  try {
+    // Resolve relative paths relative to current working directory
+    const resolvedPath = resolve(filePath);
+    const content = readFileSync(resolvedPath, "utf8");
+    return parseManifestContent(content, resolvedPath);
+  } catch (error) {
+    console.warn(`⚠️ Failed to load manifest from ${filePath}:`, error);
+    return null;
+  }
+}
+
+const emitWarning = (appKey: string) => {
+  console.warn(
+    `\n${"⚠️".padEnd(3)} ${"WARNING".padEnd(8)} No manifest version found for '${appKey}'`,
+  );
+  console.warn(
+    `   ${"↳".padEnd(3)} Using a manifest ensures version locking and prevents unexpected behavior due to version changes.`,
+  );
+  console.warn(
+    `   ${"↳".padEnd(3)} Generate/update the manifest with: \`zapier-sdk update-manifest ${appKey}\`\n`,
+  );
+};
+
+export const manifestPlugin: Plugin<
+  GetSdkType<ListAppsPluginProvides>,
+  { api: ApiClient },
+  ManifestPluginProvides
+> = (params) => {
+  const { sdk, context } = params;
+  const { api, options } = context;
+  const { manifestPath = ".zapierrc", manifest } = options || {};
+
+  const resolvedManifest = (() => {
+    // If manifest is provided directly, use it
+    if (manifest) {
+      return manifest;
+    }
+    // If manifestPath is provided, load from file
+    if (manifestPath) {
+      return loadManifestFromFile(manifestPath);
+    }
+    return null;
+  })();
+
+  const getManifestEntry = (appKey: string) => {
+    return resolvedManifest?.apps?.[appKey] || null;
+  };
+
+  const getImplementation = async (appKey: string) => {
+    let selectedApi = null;
+    const manifestImplementation = resolvedManifest?.apps?.[appKey];
+    const [versionlessAppKey, version] = splitVersionedKey(appKey);
+
+    // Use versioned app key if provided
+    if (version) {
+      selectedApi = `${versionlessAppKey}@${version}`;
+      // Otherwise, use manifest entry if available
+    } else if (manifestImplementation) {
+      selectedApi = `${manifestImplementation.implementationName}@${manifestImplementation.version || "latest"}`;
+    }
+
+    if (selectedApi) {
+      const searchParams = {
+        selected_apis: selectedApi,
+      };
+      const implementationData: ImplementationsResponse = await api.get(
+        "/api/v4/implementations/",
+        {
+          searchParams,
+        },
+      );
+      const implementationResults = implementationData.results[0];
+      if (!implementationResults) return null;
+      return normalizeImplementationToAppItem(implementationResults);
+    }
+    emitWarning(appKey);
+
+    const appsIterator = sdk.listApps({ appKeys: [appKey] }).items();
+
+    const apps = [];
+    for await (const app of appsIterator) {
+      apps.push(app);
+      break; // Only need the first result
+    }
+
+    if (apps.length === 0) {
+      return null;
+    }
+    const app = apps[0];
+    return app;
+  };
+
+  const getVersionedImplementationId = async (appKey: string) => {
+    const manifestEntry = getManifestEntry(appKey);
+    if (manifestEntry) {
+      return `${manifestEntry.implementationName}@${manifestEntry.version || "latest"}`;
+    }
+    const implementation = await getImplementation(appKey);
+    if (!implementation) return null;
+    return implementation.current_implementation_id;
+  };
+
+  return {
+    context: {
+      manifest: resolvedManifest,
+      getVersionedImplementationId,
+      getManifestEntry,
+      getImplementation,
+    },
+  };
+};

package/src/plugins/manifest/schemas.ts

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { AppItem } from "../../types/domain";
+
+export type ManifestEntry = {
+  implementationName: string;
+  version?: string;
+};
+
+export type GetManifestEntry = (appKey: string) => ManifestEntry | null;
+
+export type GetVersionedImplementationId = (
+  appKey: string,
+) => Promise<string | null>;
+
+export type GetImplementation = (appKey: string) => Promise<AppItem | null>;
+
+export type Manifest = {
+  apps: Record<string, ManifestEntry>;
+};
+
+/**
+ * Manifest schema for version locking
+ * Maps app keys to their locked version information
+ */
+export const ManifestSchema = z
+  .object({
+    apps: z.record(
+      z.string(),
+      z.object({
+        implementationName: z
+          .string()
+          .describe(
+            "Base implementation name without version (e.g., 'SlackCLIAPI')",
+          ),
+        version: z.string().describe("Version string (e.g., '1.21.1')"),
+      }),
+    ),
+  })
+  .describe("Manifest mapping app keys to version information");
+
+export const ManifestPluginOptionsSchema = z.object({
+  manifestPath: z.string().optional().describe("Path to manifest file"),
+  manifest: z
+    .record(
+      z.string(),
+      z.object({
+        implementationName: z.string(),
+        version: z.string().optional(),
+      }),
+    )
+    .optional()
+    .describe("Direct manifest object"),
+});