@zapier/zapier-sdk 0.4.1 → 0.5.0

package/src/utils/array-utils.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect } from "vitest";
+import { toArrayFromAsync } from "./array-utils";
+
+describe("array-utils", () => {
+  describe("fromAsync", () => {
+    it("should convert async generator to array", async () => {
+      async function* generateNumbers() {
+        yield 1;
+        yield 2;
+        yield 3;
+      }
+
+      const result = await toArrayFromAsync(generateNumbers());
+      expect(result).toEqual([1, 2, 3]);
+    });
+
+    it("should handle empty async generator", async () => {
+      async function* generateNothing() {
+        // yield nothing
+      }
+
+      const result = await toArrayFromAsync(generateNothing());
+      expect(result).toEqual([]);
+    });
+
+    it("should handle async generator with async operations", async () => {
+      async function* generateWithDelay() {
+        for (let i = 1; i <= 3; i++) {
+          await new Promise((resolve) => setTimeout(resolve, 1)); // Small delay
+          yield i * 10;
+        }
+      }
+
+      const result = await toArrayFromAsync(generateWithDelay());
+      expect(result).toEqual([10, 20, 30]);
+    });
+
+    it("should handle async generator that yields different types", async () => {
+      async function* generateMixed() {
+        yield "hello";
+        yield 42;
+        yield { name: "test" };
+        yield [1, 2, 3];
+      }
+
+      const result = await toArrayFromAsync(generateMixed());
+      expect(result).toEqual(["hello", 42, { name: "test" }, [1, 2, 3]]);
+    });
+
+    it("should handle async generator with error", async () => {
+      async function* generateWithError() {
+        yield 1;
+        yield 2;
+        throw new Error("Test error");
+      }
+
+      await expect(toArrayFromAsync(generateWithError())).rejects.toThrow(
+        "Test error",
+      );
+    });
+
+    it("should handle async iterable from array with Symbol.asyncIterator", async () => {
+      const asyncIterable = {
+        async *[Symbol.asyncIterator]() {
+          for (const item of ["a", "b", "c"]) {
+            yield item;
+          }
+        },
+      };
+
+      const result = await toArrayFromAsync(asyncIterable);
+      expect(result).toEqual(["a", "b", "c"]);
+    });
+
+    it("should handle large async generator efficiently", async () => {
+      async function* generateLargeSequence() {
+        for (let i = 0; i < 1000; i++) {
+          yield i;
+        }
+      }
+
+      const result = await toArrayFromAsync(generateLargeSequence());
+      expect(result).toHaveLength(1000);
+      expect(result[0]).toBe(0);
+      expect(result[999]).toBe(999);
+    });
+
+    it("should handle async generator that yields promises (promises are auto-awaited)", async () => {
+      async function* generatePromises() {
+        yield Promise.resolve("first");
+        yield Promise.resolve("second");
+      }
+
+      const result = await toArrayFromAsync(generatePromises());
+      // for await automatically awaits promises, so we get resolved values
+      expect(result).toEqual(["first", "second"]);
+    });
+
+    it("should handle async generator that yields already resolved values", async () => {
+      async function* generateResolvedValues() {
+        yield await Promise.resolve("first");
+        yield await Promise.resolve("second");
+      }
+
+      const result = await toArrayFromAsync(generateResolvedValues());
+      // The resolved values are yielded directly
+      expect(result).toEqual(["first", "second"]);
+    });
+
+    it("should maintain order of async generator items", async () => {
+      async function* generateInOrder() {
+        for (let i = 1; i <= 5; i++) {
+          // Simulate varying delays
+          await new Promise((resolve) =>
+            setTimeout(resolve, Math.random() * 10),
+          );
+          yield `item-${i}`;
+        }
+      }
+
+      const result = await toArrayFromAsync(generateInOrder());
+      expect(result).toEqual([
+        "item-1",
+        "item-2",
+        "item-3",
+        "item-4",
+        "item-5",
+      ]);
+    });
+  });
+});

package/src/utils/array-utils.ts

@@ -0,0 +1,41 @@
+/**
+ * Array utility functions for working with async iterators and arrays
+ */
+
+/**
+ * Creates an array from an async iterable, similar to Array.from() but for async iterables
+ *
+ * @param asyncIterable - An async iterable to convert to an array
+ * @returns Promise that resolves to an array containing all items from the async iterable
+ *
+ * @example
+ * async function* generateNumbers() {
+ *   yield 1;
+ *   yield 2;
+ *   yield 3;
+ * }
+ *
+ * const numbers = await fromAsync(generateNumbers()); // [1, 2, 3]
+ *
+ * @example
+ * // With async generator that fetches data
+ * async function* fetchUsers() {
+ *   for (let page = 1; page <= 3; page++) {
+ *     const users = await fetchUsersPage(page);
+ *     yield* users;
+ *   }
+ * }
+ *
+ * const allUsers = await fromAsync(fetchUsers());
+ */
+export async function toArrayFromAsync<T>(
+  asyncIterable: AsyncIterable<T>,
+): Promise<T[]> {
+  const result: T[] = [];
+
+  for await (const item of asyncIterable) {
+    result.push(item);
+  }
+
+  return result;
+}

package/src/utils/domain-utils.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from "vitest";
+import {
+  groupVersionedAppKeysByType,
+  groupAppKeysByType,
+} from "./domain-utils";
+
+describe("domain-utils", () => {
+  describe("groupVersionedAppKeysByType", () => {
+    it("should reject UUID app keys", () => {
+      expect(() => {
+        groupVersionedAppKeysByType(["61e47557-af91-4b0c-a3e0-c28606357664"]);
+      }).toThrow(
+        "UUID app keys are not supported. Use app slug or implementation ID instead of: 61e47557-af91-4b0c-a3e0-c28606357664",
+      );
+    });
+
+    it("should categorize *API as selectedApi", () => {
+      const result = groupVersionedAppKeysByType(["FormatterCLIAPI"]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI"],
+        slug: [],
+      });
+    });
+
+    it("should categorize various API types as selectedApi", () => {
+      const result = groupVersionedAppKeysByType([
+        "FormatterCLIAPI",
+        "SlackAPI",
+        "GmailRESTAPI",
+        "WebhookAPI",
+        "AnythingWithUppercase",
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: [
+          "FormatterCLIAPI",
+          "SlackAPI",
+          "GmailRESTAPI",
+          "WebhookAPI",
+          "AnythingWithUppercase",
+        ],
+        slug: [],
+      });
+    });
+
+    it("should categorize lower-case strings as slugs, converting underscores to dashes", () => {
+      const result = groupVersionedAppKeysByType([
+        "slack",
+        "google-sheets",
+        "_100hires_ats",
+        "amazon_redshift",
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: [],
+        slug: ["slack", "google-sheets", "100hires-ats", "amazon-redshift"],
+      });
+    });
+
+    it("should preserve version from API implementations", () => {
+      const result = groupVersionedAppKeysByType(["FormatterCLIAPI@1.0.0"]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI@1.0.0"],
+        slug: [],
+      });
+    });
+
+    it("should preserve version from slugs", () => {
+      const result = groupVersionedAppKeysByType(["slack@2.1.0"]);
+
+      expect(result).toEqual({
+        selectedApi: [],
+        slug: ["slack@2.1.0"],
+      });
+    });
+
+    it("should handle mixed types correctly", () => {
+      const result = groupVersionedAppKeysByType([
+        "FormatterCLIAPI@1.0.0",
+        "slack",
+        "AnotherAPI",
+        "gmail@3.0.1",
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI@1.0.0", "AnotherAPI"],
+        slug: ["slack", "gmail@3.0.1"],
+      });
+    });
+
+    it("should handle empty array", () => {
+      const result = groupVersionedAppKeysByType([]);
+
+      expect(result).toEqual({
+        selectedApi: [],
+        slug: [],
+      });
+    });
+
+    it("should reject uppercase and lowercase UUIDs", () => {
+      expect(() => {
+        groupVersionedAppKeysByType(["61E47557-AF91-4B0C-A3E0-C28606357664"]);
+      }).toThrow(
+        "UUID app keys are not supported. Use app slug or implementation ID instead of: 61E47557-AF91-4B0C-A3E0-C28606357664",
+      );
+
+      expect(() => {
+        groupVersionedAppKeysByType(["f47ac10b-58cc-4372-a567-0e02b2c3d479"]);
+      }).toThrow(
+        "UUID app keys are not supported. Use app slug or implementation ID instead of: f47ac10b-58cc-4372-a567-0e02b2c3d479",
+      );
+    });
+
+    it("should categorize partial UUIDs as slugs", () => {
+      const result = groupVersionedAppKeysByType([
+        "61e47557-af91-4b0c-a3e0", // too short
+        "61e47557-af91-4b0c-a3e0-c28606357664-extra", // too long
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: [],
+        slug: [
+          "61e47557-af91-4b0c-a3e0",
+          "61e47557-af91-4b0c-a3e0-c28606357664-extra",
+        ],
+      });
+    });
+
+    it("should dedupe exact duplicate versioned keys", () => {
+      const result = groupVersionedAppKeysByType([
+        "slack@2.1.0",
+        "FormatterCLIAPI@1.0.0",
+        "slack@2.1.0", // exact duplicate
+        "FormatterCLIAPI@1.0.0", // exact duplicate
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI@1.0.0"],
+        slug: ["slack@2.1.0"],
+      });
+    });
+  });
+
+  describe("groupAppKeysByType", () => {
+    it("should strip versions from API implementations", () => {
+      const result = groupAppKeysByType(["FormatterCLIAPI@1.0.0"]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI"],
+        slug: [],
+      });
+    });
+
+    it("should strip versions from slugs", () => {
+      const result = groupAppKeysByType(["slack@2.1.0"]);
+
+      expect(result).toEqual({
+        selectedApi: [],
+        slug: ["slack"],
+      });
+    });
+
+    it("should handle mixed types and strip versions", () => {
+      const result = groupAppKeysByType([
+        "FormatterCLIAPI@1.0.0",
+        "slack",
+        "AnotherAPI@2.3.4",
+        "gmail@3.0.1",
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI", "AnotherAPI"],
+        slug: ["slack", "gmail"],
+      });
+    });
+
+    it("should handle keys without versions", () => {
+      const result = groupAppKeysByType([
+        "FormatterCLIAPI",
+        "slack",
+        "AnotherAPI",
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI", "AnotherAPI"],
+        slug: ["slack"],
+      });
+    });
+
+    it("should reject UUID app keys (delegated to versioned function)", () => {
+      expect(() => {
+        groupAppKeysByType(["61e47557-af91-4b0c-a3e0-c28606357664"]);
+      }).toThrow(
+        "UUID app keys are not supported. Use app slug or implementation ID instead of: 61e47557-af91-4b0c-a3e0-c28606357664",
+      );
+    });
+
+    it("should handle empty array", () => {
+      const result = groupAppKeysByType([]);
+
+      expect(result).toEqual({
+        selectedApi: [],
+        slug: [],
+      });
+    });
+
+    it("should dedupe multiple versions of same base key", () => {
+      const result = groupAppKeysByType([
+        "slack@1.0.0",
+        "FormatterCLIAPI@2.1.0",
+        "slack@1.2.3", // different version of slack
+        "FormatterCLIAPI@1.0.0", // different version of FormatterCLIAPI
+        "gmail",
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI"], // only one instance despite multiple versions
+        slug: ["slack", "gmail"], // only one slack despite multiple versions
+      });
+    });
+
+    it("should dedupe exact duplicates after version stripping", () => {
+      const result = groupAppKeysByType([
+        "slack@1.0.0",
+        "slack", // no version
+        "slack@2.0.0", // different version
+        "FormatterCLIAPI",
+        "FormatterCLIAPI@1.5.0",
+      ]);
+
+      expect(result).toEqual({
+        selectedApi: ["FormatterCLIAPI"],
+        slug: ["slack"],
+      });
+    });
+  });
+});

package/src/utils/domain-utils.ts

@@ -0,0 +1,283 @@
+/**
+ * Domain utility functions for working with app identifiers and data normalization
+ */
+
+import type {
+  Action,
+  App,
+  Authentication,
+  Implementation,
+  ImplementationMeta,
+  Service,
+} from "../api/types";
+import type { ActionItem, AppItem, AuthenticationItem } from "../types/domain";
+
+/**
+ * Splits a versioned key to extract the base key and version
+ *
+ * @param versionedKey - Versioned key in format "KeyName@version" (e.g., "SlackCLIAPI@1.21.1")
+ * @returns Tuple of [baseKey, version] or [versionedKey, undefined] if no @ symbol
+ *
+ * @example
+ * splitVersionedKey("SlackCLIAPI@1.21.1") // ["SlackCLIAPI", "1.21.1"]
+ * splitVersionedKey("SomeAPI") // ["SomeAPI", undefined]
+ */
+export function splitVersionedKey(
+  versionedKey: string,
+): [string, string | undefined] {
+  const parts = versionedKey.split("@");
+  if (parts.length >= 2) {
+    const baseKey = parts[0];
+    const version = parts.slice(1).join("@"); // Handle edge case of multiple @ symbols
+    return [baseKey, version];
+  }
+  return [versionedKey, undefined];
+}
+
+/**
+ * Converts an API App to an AppItem with normalized field names
+ *
+ * @param app - Raw App from API
+ * @returns Normalized AppItem
+ */
+export function normalizeAppItem(app: App): AppItem {
+  // Extract API name and version from current_implementation_id
+  const [apiName, appVersion] = app.current_implementation_id
+    ? splitVersionedKey(app.current_implementation_id)
+    : [app.current_implementation_id || "", undefined];
+
+  return {
+    title: app.name,
+    key: app.slug || apiName,
+    current_implementation_id: app.current_implementation_id || "",
+    version: appVersion, // Extract version separately
+  };
+}
+
+/**
+ * Converts an Implementation to an AppItem with normalized field names
+ *
+ * @param implementation - Raw Implementation from API
+ * @returns Normalized AppItem
+ */
+export function normalizeImplementationToAppItem(
+  implementation: Implementation,
+): AppItem {
+  // Extract API name and version from selected_api
+  const [selectedApi, appVersion] = implementation.selected_api
+    ? splitVersionedKey(implementation.selected_api)
+    : [implementation.selected_api || "", undefined];
+
+  return {
+    title: implementation.name || selectedApi,
+    key: selectedApi,
+    current_implementation_id: implementation.selected_api || "",
+    version: appVersion, // Extract version separately
+  };
+}
+
+/**
+ * Converts a lightweight ImplementationMeta to a slimmed AppItem
+ *
+ * @param implementationMeta - Raw ImplementationMeta from API
+ * @returns Normalized AppItem with essential fields only
+ */
+export function normalizeImplementationMetaToAppItem(
+  implementationMeta: ImplementationMeta,
+): AppItem {
+  // Extract API name and version from the implementation ID
+  const [selectedApi, appVersion] = splitVersionedKey(implementationMeta.id);
+
+  return {
+    title: implementationMeta.name,
+    key: selectedApi,
+    current_implementation_id: implementationMeta.id, // Keep the full versioned ID
+    version: appVersion, // Extract version separately
+    slug: implementationMeta.slug,
+  };
+}
+
+export function normalizeServiceToAppItem(service: Service): AppItem {
+  const [selectedApi, appVersion] = service.current_implementation_id
+    ? splitVersionedKey(service.current_implementation_id)
+    : ["", undefined];
+
+  return {
+    title: service.name,
+    key: selectedApi,
+    current_implementation_id: service.current_implementation_id,
+    version: appVersion,
+    description: service.description,
+  };
+}
+
+/**
+ * Converts an API Authentication to an AuthenticationItem with normalized field names
+ *
+ * @param auth - Raw Authentication from API
+ * @param options - Additional fields to include
+ * @param options.app_key - selected_api from implementations endpoint
+ * @param options.version - Version extracted from selected_api
+ * @returns Normalized AuthenticationItem
+ */
+export function normalizeAuthenticationItem(
+  auth: Authentication,
+  options: { app_key?: string; version?: string } = {},
+): AuthenticationItem {
+  // Extract app key and version from selected_api if not provided
+  let appKey = options.app_key;
+  let version = options.version;
+
+  if (auth.selected_api) {
+    const [extractedAppKey, extractedVersion] = splitVersionedKey(
+      auth.selected_api,
+    );
+
+    // Use extracted app key if not provided in options
+    if (!appKey) {
+      appKey = extractedAppKey;
+    }
+
+    // Use extracted version if not provided in options
+    if (!version) {
+      version = extractedVersion;
+    }
+  }
+
+  const {
+    selected_api: selectedApi,
+    customuser_id: userId,
+    ...restOfAuth
+  } = auth;
+
+  return {
+    ...restOfAuth, // Pass through all other API response fields except selected_api
+    implementation_id: selectedApi, // Rename selected_api to implementation_id
+    title: auth.title || (auth as any).label || undefined, // Coerce title from label if missing
+    is_expired: auth.is_stale, // Map is_stale to is_expired
+    expired_at: auth.marked_stale_at, // Map marked_stale_at to expired_at
+    app_key: appKey, // App key from implementations endpoint or parsed from selected_api
+    version, // Version from selected_api or provided
+    user_id: userId, // Map customuser_id to user_id
+  };
+}
+
+export function normalizeActionItem(action: Action): ActionItem {
+  const { name, type, selected_api: appKey, ...restOfAction } = action;
+  return {
+    ...restOfAction,
+    app_key: appKey || "",
+    action_type: type,
+    title: name, // Map name to title
+    type: "action",
+  };
+}
+
+/**
+ * Groups app keys by their type based on format patterns
+ *
+ * @param appKeys Array of app key strings to categorize
+ * @returns Object with arrays of keys grouped by type: selectedApi (CLI APIs), slug (everything else)
+ *
+ * @example
+ * groupVersionedAppKeysByType([
+ *   'FormatterCLIAPI@1.0.0',
+ *   'slack',
+ *   'AnotherAPI'
+ * ])
+ * // Returns: {
+ * //   selectedApi: ['FormatterCLIAPI@1.0.0', 'AnotherAPI'],
+ * //   slug: ['slack']
+ * // }
+ */
+export function groupVersionedAppKeysByType(appKeys: string[]): {
+  selectedApi: string[];
+  slug: string[];
+} {
+  const result = {
+    selectedApi: [] as string[],
+    slug: [] as string[],
+  };
+
+  // Use Sets to track seen keys for deduplication
+  const seenSelectedApi = new Set<string>();
+  const seenSlugs = new Set<string>();
+
+  for (const key of appKeys) {
+    // Split by @ to get base name for classification (but preserve full key in results)
+    const [keyWithoutVersion, version] = splitVersionedKey(key);
+
+    // Check if it's a UUID (canonical ID) - not supported
+    const uuidRegex =
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    if (uuidRegex.test(keyWithoutVersion)) {
+      throw new Error(
+        `UUID app keys are not supported. Use app slug or implementation ID instead of: ${key}`,
+      );
+    }
+
+    // Check if it's a snake_case string
+    if (isSnakeCasedSlug(keyWithoutVersion)) {
+      const dashified = dashifySnakeCasedSlug(keyWithoutVersion);
+      const slugWithVersion = version ? `${dashified}@${version}` : dashified;
+      if (!seenSlugs.has(slugWithVersion)) {
+        seenSlugs.add(slugWithVersion);
+        result.slug.push(slugWithVersion); // Preserve full key including version
+      }
+      continue;
+    }
+
+    // Check if it's a slug (lowercase and dashes)
+    if (keyWithoutVersion.match(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)) {
+      seenSlugs.add(key);
+      result.slug.push(key);
+      continue;
+    }
+
+    // Everything else is a selected_api
+    if (!seenSelectedApi.has(key)) {
+      seenSelectedApi.add(key);
+      result.selectedApi.push(key); // Preserve full key including version
+    }
+  }
+
+  return result;
+}
+
+export function groupAppKeysByType(appKeys: string[]): {
+  selectedApi: string[];
+  slug: string[];
+} {
+  const grouped = groupVersionedAppKeysByType(appKeys);
+
+  // Extract base keys and dedupe by using Set
+  return {
+    selectedApi: [
+      ...new Set(grouped.selectedApi.map((key) => key.split("@")[0])),
+    ],
+    slug: [...new Set(grouped.slug.map((key) => key.split("@")[0]))],
+  };
+}
+
+function isSnakeCasedSlug(slug: string): boolean {
+  // Allow leading underscore for slugs starting with a number.
+  if (slug.match(/^_[0-9]/)) {
+    slug = slug.slice(1);
+  }
+
+  return !!slug.match(/^[a-z0-9]+(?:_[a-z0-9]+)*$/);
+}
+
+function dashifySnakeCasedSlug(slug: string): string {
+  // Only dashify if it's a valid snake_cased slug.
+  if (!isSnakeCasedSlug(slug)) {
+    return slug;
+  }
+
+  // Allow one leading underscore for slugs starting with a number.
+  if (slug.startsWith("_")) {
+    slug = slug.slice(1);
+  }
+
+  return slug.replace(/_/g, "-");
+}