@zapier/zapier-sdk 0.4.1 → 0.5.1

package/dist/utils/function-utils.test.js

@@ -0,0 +1,110 @@
+import { describe, it, expect } from "vitest";
+import { createFunction, createPaginatedFunction } from "./function-utils";
+import { ZapierValidationError, ZapierUnknownError } from "../types/errors";
+import { ALL_ITEMS, listTestItems } from "./pagination-utils.test";
+describe("createFunction", () => {
+    it("should return result from core function", async () => {
+        const mockCoreFn = async (options) => {
+            return `Hello, ${options.name}!`;
+        };
+        const wrappedFn = createFunction(mockCoreFn);
+        const result = await wrappedFn({ name: "World" });
+        expect(result).toBe("Hello, World!");
+    });
+});
+describe.each([
+    { name: "createFunction", createFn: createFunction },
+    { name: "createPaginatedFunction", createFn: createPaginatedFunction },
+])("$name", ({ createFn }) => {
+    it("should preserve function name", async () => {
+        async function testCoreFn(options) {
+            return options.value * 2;
+        }
+        const wrappedFn = createFn(testCoreFn);
+        expect(wrappedFn.name).toBe("testCoreFn");
+    });
+    it("should normalize and rethrow ZapierError instances", async () => {
+        const mockError = new ZapierValidationError("Validation failed", {
+            details: { field: "name" },
+        });
+        const mockCoreFn = async () => {
+            throw mockError;
+        };
+        const wrappedFn = createFn(mockCoreFn);
+        await expect(wrappedFn({})).rejects.toBe(mockError);
+    });
+    it("should normalize generic Error to ZapierUnknownError", async () => {
+        const mockCoreFn = async () => {
+            throw new Error("Something went wrong");
+        };
+        const wrappedFn = createFn(mockCoreFn);
+        await expect(wrappedFn({})).rejects.toThrow(ZapierUnknownError);
+    });
+    it("should normalize non-Error values to ZapierUnknownError", async () => {
+        const mockCoreFn = async () => {
+            throw "String error";
+        };
+        const wrappedFn = createFn(mockCoreFn);
+        await expect(wrappedFn({})).rejects.toThrow(ZapierUnknownError);
+    });
+});
+describe("createPaginatedFunction", () => {
+    it("should wrap non-array result in {data: [result]}", async () => {
+        const mockCoreFn = async (options) => {
+            return `Hello, ${options.name}!`;
+        };
+        const wrappedFn = createPaginatedFunction(mockCoreFn);
+        const result = await wrappedFn({ name: "World" });
+        expect(result).toEqual({ data: ["Hello, World!"] });
+    });
+    it("should wrap array result in {data: result}", async () => {
+        const mockCoreFn = async (options) => {
+            return Array.from({ length: options.count }, (_, i) => `Item ${i + 1}`);
+        };
+        const wrappedFn = createPaginatedFunction(mockCoreFn);
+        const result = await wrappedFn({ count: 3 });
+        expect(result).toEqual({ data: ["Item 1", "Item 2", "Item 3"] });
+    });
+    it("should return {data} object unchanged", async () => {
+        const mockCoreFn = async (options) => {
+            return { data: options.items };
+        };
+        const wrappedFn = createPaginatedFunction(mockCoreFn);
+        const result = await wrappedFn({ items: ["A", "B", "C"] });
+        expect(result).toEqual({ data: ["A", "B", "C"] });
+    });
+    it("should allow for await iteration over pages", async () => {
+        const listItems = createPaginatedFunction(listTestItems);
+        const pages = [];
+        for await (const page of listItems({ pageSize: 3 })) {
+            pages.push(page);
+            if (pages.length >= 3)
+                break;
+        }
+        // Should have collected 3 pages
+        expect(pages).toHaveLength(3);
+        // Check first page structure
+        expect(pages[0]).toEqual({
+            data: ALL_ITEMS.slice(0, 3),
+            nextCursor: "cursor-3",
+        });
+        // Check second page
+        expect(pages[1]).toEqual({
+            data: ALL_ITEMS.slice(3, 6),
+            nextCursor: "cursor-6",
+        });
+    });
+    it("should allow for await iteration over individual items", async () => {
+        const listItems = createPaginatedFunction(listTestItems);
+        const items = [];
+        for await (const item of listItems({ pageSize: 3 }).items()) {
+            items.push(item);
+            if (items.length >= 7)
+                break; // Get first 7 items across pages
+        }
+        // Should have collected 7 individual items
+        expect(items).toHaveLength(7);
+        // Should be the first 7 items from ALL_ITEMS (flattened from pages)
+        expect(items).toEqual(ALL_ITEMS.slice(0, 7));
+    });
+});

package/dist/utils/pagination-utils.d.ts

@@ -0,0 +1,37 @@
+type TPageOptions<TOptions> = TOptions extends undefined ? {
+    cursor?: string;
+    maxItems?: number;
+    pageSize?: number;
+} : TOptions & {
+    cursor?: string;
+    maxItems?: number;
+    pageSize?: number;
+};
+export declare function createPrefixedCursor(prefix: string, cursor: string | undefined): string;
+export declare function splitPrefixedCursor(cursor: string | undefined, prefixes?: string[]): [string | undefined, string | undefined];
+/**
+ * Utility for paginating through API endpoints that return cursor-based pages
+ *
+ * @param pageFunction - Function that fetches a single page with {data, nextCursor} structure
+ * @param pageOptions - Options to pass to the page function (cursor will be managed automatically)
+ * @returns Async iterator that yields pages
+ */
+export declare function paginateMaxItems<TOptions, TPage extends {
+    data: any[];
+    nextCursor?: string;
+}>(pageFunction: (options: TOptions & {
+    cursor?: string;
+    maxItems?: number;
+    pageSize?: number;
+}) => Promise<TPage>, pageOptions?: TPageOptions<TOptions>): AsyncIterableIterator<TPage>;
+export declare function paginateBuffered<TOptions, TPage extends {
+    data: any[];
+    nextCursor?: string;
+}>(pageFunction: (options: TOptions & {
+    cursor?: string;
+    maxItems?: number;
+    pageSize?: number;
+}) => Promise<TPage>, pageOptions?: TPageOptions<TOptions>): AsyncIterableIterator<TPage>;
+export declare const paginate: typeof paginateBuffered;
+export {};
+//# sourceMappingURL=pagination-utils.d.ts.map

package/dist/utils/pagination-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination-utils.d.ts","sourceRoot":"","sources":["../../src/utils/pagination-utils.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,CAAC,QAAQ,IAAI,QAAQ,SAAS,SAAS,GACpD;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD,QAAQ,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAoCzE,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,MAAM,CAKR;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,CAAC,EAAE,MAAM,EAAE,GAClB,CAAC,MAAM,GAAG,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,CAkB1C;AAED;;;;;;GAMG;AACH,wBAAuB,gBAAgB,CACrC,QAAQ,EACR,KAAK,SAAS;IAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAElD,YAAY,EAAE,CACZ,OAAO,EAAE,QAAQ,GAAG;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,KACE,OAAO,CAAC,KAAK,CAAC,EACnB,WAAW,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,GACnC,qBAAqB,CAAC,KAAK,CAAC,CAoC9B;AAED,wBAAuB,gBAAgB,CACrC,QAAQ,EACR,KAAK,SAAS;IAAE,IAAI,EAAE,GAAG,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAElD,YAAY,EAAE,CACZ,OAAO,EAAE,QAAQ,GAAG;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,KACE,OAAO,CAAC,KAAK,CAAC,EACnB,WAAW,CAAC,EAAE,YAAY,CAAC,QAAQ,CAAC,GACnC,qBAAqB,CAAC,KAAK,CAAC,CAiG9B;AAED,eAAO,MAAM,QAAQ,yBAAmB,CAAC"}

package/dist/utils/pagination-utils.js

@@ -0,0 +1,165 @@
+const offsetCursorMarker = "$$offset$$";
+function splitOffsetCursor(cursor) {
+    if (!cursor) {
+        return [0, cursor];
+    }
+    try {
+        const parsedCursor = JSON.parse(cursor);
+        if (!Array.isArray(parsedCursor)) {
+            return [0, cursor];
+        }
+        const [marker, offset, currentCursor] = parsedCursor;
+        if (marker !== offsetCursorMarker) {
+            return [0, cursor];
+        }
+        if (typeof offset !== "number") {
+            return [0, cursor];
+        }
+        return [offset, currentCursor];
+    }
+    catch {
+        return [0, cursor];
+    }
+}
+function createOffsetCursor(offset, currentCursor) {
+    return JSON.stringify([offsetCursorMarker, offset, currentCursor]);
+}
+export function createPrefixedCursor(prefix, cursor) {
+    if (!cursor) {
+        return `${prefix}::`;
+    }
+    return `${prefix}::${cursor}`;
+}
+export function splitPrefixedCursor(cursor, prefixes) {
+    if (!cursor) {
+        return [undefined, undefined];
+    }
+    const [prefix, ...rest] = cursor.split("::");
+    if (prefixes && !prefixes.includes(prefix)) {
+        return [undefined, cursor];
+    }
+    cursor = rest.join("::");
+    if (!cursor) {
+        return [prefix, undefined];
+    }
+    return [prefix, cursor];
+}
+/**
+ * Utility for paginating through API endpoints that return cursor-based pages
+ *
+ * @param pageFunction - Function that fetches a single page with {data, nextCursor} structure
+ * @param pageOptions - Options to pass to the page function (cursor will be managed automatically)
+ * @returns Async iterator that yields pages
+ */
+export async function* paginateMaxItems(pageFunction, pageOptions) {
+    let cursor = pageOptions?.cursor;
+    let totalItemsYielded = 0;
+    const maxItems = pageOptions?.maxItems;
+    const pageSize = pageOptions?.pageSize;
+    do {
+        const options = {
+            ...(pageOptions || {}),
+            cursor,
+            pageSize: maxItems !== undefined && pageSize !== undefined
+                ? Math.min(pageSize, maxItems)
+                : pageSize,
+        };
+        const page = await pageFunction(options);
+        if (maxItems !== undefined) {
+            const remainingItems = maxItems - totalItemsYielded;
+            if (page.data.length >= remainingItems) {
+                const yieldedPage = {
+                    ...page,
+                    data: page.data.slice(0, remainingItems),
+                    nextCursor: undefined,
+                };
+                yield yieldedPage;
+                break;
+            }
+        }
+        yield page;
+        totalItemsYielded += page.data.length;
+        cursor = page.nextCursor;
+    } while (cursor);
+}
+export async function* paginateBuffered(pageFunction, pageOptions) {
+    const pageSize = pageOptions?.pageSize;
+    const [cursorOffset, currentCursor] = splitOffsetCursor(pageOptions?.cursor);
+    const options = {
+        ...(pageOptions || {}),
+        cursor: currentCursor,
+    };
+    const iterator = paginateMaxItems(pageFunction, options);
+    let bufferedPages = [];
+    let isFirstPage = true;
+    let cursor;
+    for await (let page of iterator) {
+        if (isFirstPage) {
+            isFirstPage = false;
+            if (cursorOffset) {
+                page = {
+                    ...page,
+                    data: page.data.slice(cursorOffset),
+                };
+            }
+        }
+        if (!pageSize) {
+            yield page;
+            cursor = page.nextCursor;
+            continue;
+        }
+        const bufferedLength = bufferedPages.reduce((acc, page) => acc + page.data.length, 0);
+        // If we don't have enough to fill a page, buffer this page.
+        if (bufferedLength + page.data.length < pageSize) {
+            bufferedPages.push(page);
+            cursor = page.nextCursor;
+            continue;
+        }
+        // Let's yield a page from our buffered pages.
+        const bufferedItems = bufferedPages.map((p) => p.data).flat();
+        const allItems = [...bufferedItems, ...page.data];
+        const pageItems = allItems.slice(0, pageSize);
+        const remainingItems = allItems.slice(pageItems.length);
+        // No extra items to buffer, so we can just yield a normal page with a cursor to the next one.
+        if (remainingItems.length === 0) {
+            yield {
+                ...page,
+                data: pageItems,
+                nextCursor: page.nextCursor,
+            };
+            bufferedPages = [];
+            cursor = page.nextCursor;
+            continue;
+        }
+        // Yield our items with a cursor to offset into this page.
+        yield {
+            ...page,
+            data: pageItems,
+            nextCursor: createOffsetCursor(page.data.length - remainingItems.length, cursor),
+        };
+        while (remainingItems.length > pageSize) {
+            const pageItems = remainingItems.splice(0, pageSize);
+            yield {
+                ...page,
+                data: pageItems,
+                nextCursor: createOffsetCursor(page.data.length - remainingItems.length, cursor),
+            };
+        }
+        bufferedPages = [
+            {
+                ...page,
+                data: remainingItems,
+            },
+        ];
+        cursor = page.nextCursor;
+    }
+    if (bufferedPages.length > 0) {
+        const lastBufferedPage = bufferedPages.slice(-1)[0];
+        const bufferedItems = bufferedPages.map((p) => p.data).flat();
+        yield {
+            ...lastBufferedPage,
+            data: bufferedItems,
+        };
+    }
+}
+export const paginate = paginateBuffered;

package/dist/utils/pagination-utils.test.d.ts

@@ -0,0 +1,17 @@
+export declare const ALL_ITEMS: {
+    id: number;
+    name: string;
+}[];
+export declare function listTestItems(options: {
+    pageSize?: number;
+    cursor?: string;
+    filter?: string;
+    maxItems?: number;
+}): Promise<{
+    data: {
+        id: number;
+        name: string;
+    }[];
+    nextCursor: string | undefined;
+}>;
+//# sourceMappingURL=pagination-utils.test.d.ts.map

package/dist/utils/pagination-utils.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination-utils.test.d.ts","sourceRoot":"","sources":["../../src/utils/pagination-utils.test.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,SAAS;;;GAGnB,CAAC;AAGJ,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;;;;;;GA6CA"}