@zapier/zapier-sdk 0.4.1 → 0.5.1

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

@@ -0,0 +1,461 @@
+import { describe, it, expect } from "vitest";
+import { paginate, paginateMaxItems } from "./pagination-utils";
+// Test data set - simulating a large dataset with cursor-based pagination
+export const ALL_ITEMS = Array.from({ length: 25 }, (_, i) => ({
+    id: i + 1,
+    name: `Item ${i + 1}`,
+}));
+// Test page function that implements cursor-based pagination logic
+export async function listTestItems(options) {
+    const { pageSize = 5, cursor, filter, maxItems } = options;
+    // Cap pageSize at 10 to simulate real API limits
+    let actualPageSize = Math.min(pageSize, 10);
+    // If maxItems hint is provided, further limit the page size for optimization
+    if (maxItems !== undefined && maxItems > 0) {
+        actualPageSize = Math.min(actualPageSize, maxItems);
+    }
+    // Filter items if filter is provided
+    let items = ALL_ITEMS;
+    if (filter) {
+        items = items.filter((item) => item.name.toLowerCase().includes(filter.toLowerCase()));
+    }
+    // Find starting position based on cursor
+    let startIndex = 0;
+    if (cursor) {
+        // Cursor format: "cursor-{itemId}"
+        const cursorId = parseInt(cursor.replace("cursor-", ""));
+        startIndex = items.findIndex((item) => item.id > cursorId);
+        if (startIndex === -1) {
+            // No more items after cursor
+            return { data: [], nextCursor: undefined };
+        }
+    }
+    // Get page of items
+    const pageItems = items.slice(startIndex, startIndex + actualPageSize);
+    // Determine next cursor
+    let nextCursor;
+    if (startIndex + actualPageSize < items.length && pageItems.length > 0) {
+        const lastItem = pageItems[pageItems.length - 1];
+        nextCursor = `cursor-${lastItem.id}`;
+    }
+    return {
+        data: pageItems,
+        nextCursor,
+    };
+}
+describe("paginate", () => {
+    it("should paginate through multiple pages", async () => {
+        const pageIterator = paginate(listTestItems, { pageSize: 3 });
+        const pages = [];
+        for await (const page of pageIterator) {
+            pages.push(page);
+        }
+        // With 25 items and pageSize 3, should have 9 pages (8 full + 1 partial)
+        expect(pages).toHaveLength(9);
+        // Check first page
+        expect(pages[0]).toEqual({
+            data: ALL_ITEMS.slice(0, 3),
+            nextCursor: "cursor-3",
+        });
+        // Check second page (cursor should be passed correctly)
+        expect(pages[1]).toEqual({
+            data: ALL_ITEMS.slice(3, 6),
+            nextCursor: "cursor-6",
+        });
+        // Check last page (should have no nextCursor)
+        expect(pages[8]).toEqual({
+            data: ALL_ITEMS.slice(24, 25),
+            nextCursor: undefined,
+        });
+        // Verify we got all 25 items across all pages
+        const allItems = pages.flatMap((page) => page.data);
+        expect(allItems).toHaveLength(25);
+    });
+    it("should cap pageSize at 10 when unbuffered", async () => {
+        // Use a page size larger than 10, should get capped
+        const pageIterator = paginateMaxItems(listTestItems, { pageSize: 50 });
+        const pages = [];
+        for await (const page of pageIterator) {
+            pages.push(page);
+        }
+        // Should get 3 pages: 10+10+5=25 (pageSize capped at 10)
+        expect(pages).toHaveLength(3);
+        expect(pages[0].data).toHaveLength(10); // First page capped at 10
+        expect(pages[1].data).toHaveLength(10); // Second page capped at 10
+        expect(pages[2].data).toHaveLength(5); // Last page has remaining 5
+        expect(pages[2].nextCursor).toBeUndefined(); // Last page has no nextCursor
+    });
+    it("should not cap pageSize when buffered", async () => {
+        const pageIterator = paginate(listTestItems, { pageSize: 50 });
+        for await (const page of pageIterator) {
+            expect(page.data).toHaveLength(25);
+            break;
+        }
+    });
+    it("should not cap pageSize when buffered", async () => {
+        const pageIterator = paginate(listTestItems, { pageSize: 15 });
+        const pages = [];
+        for await (const page of pageIterator) {
+            pages.push(page);
+        }
+        expect(pages).toHaveLength(2);
+        expect(pages[0].data).toHaveLength(15);
+        expect(pages[1].data).toHaveLength(10);
+    });
+    it("should continue from pseudo cursor", async () => {
+        const pageIterator = paginate(listTestItems, { pageSize: 15 });
+        const pages = [];
+        for await (const page of pageIterator) {
+            pages.push(page);
+            break;
+        }
+        const nextPageIterator = paginate(listTestItems, {
+            pageSize: 15,
+            cursor: pages[0].nextCursor,
+        });
+        for await (const page of nextPageIterator) {
+            pages.push(page);
+        }
+        expect(pages).toHaveLength(2);
+        expect(pages[0].data).toHaveLength(15);
+        expect(pages[1].data).toHaveLength(10);
+    });
+    it("should handle filtered results", async () => {
+        // Filter for items containing "1" (should match Item 1, Item 10-19, Item 21)
+        const pageIterator = paginate(listTestItems, {
+            pageSize: 4,
+            filter: "1",
+        });
+        const pages = [];
+        for await (const page of pageIterator) {
+            pages.push(page);
+        }
+        // Should have multiple pages due to pageSize: 4
+        expect(pages.length).toBeGreaterThan(1);
+        // All items should contain "1"
+        const allItems = pages.flatMap((page) => page.data);
+        expect(allItems.every((item) => item.name.includes("1"))).toBe(true);
+        // Should include items like Item 1, Item 10, Item 11, etc.
+        expect(allItems).toContainEqual(ALL_ITEMS[0]); // Item 1
+        expect(allItems).toContainEqual(ALL_ITEMS[9]); // Item 10
+        expect(allItems).toContainEqual(ALL_ITEMS[20]); // Item 21
+    });
+    it("should handle empty results", async () => {
+        // Filter that matches no items
+        const pageIterator = paginate(listTestItems, {
+            pageSize: 10,
+            filter: "nonexistent",
+        });
+        const pages = [];
+        for await (const page of pageIterator) {
+            pages.push(page);
+        }
+        expect(pages).toHaveLength(1);
+        expect(pages[0]).toEqual({
+            data: [],
+            nextCursor: undefined,
+        });
+    });
+    it("should pass through errors from the page function", async () => {
+        // Create a page function that throws an error
+        const errorPageFunction = async () => {
+            throw new Error("Page function failed");
+        };
+        const pageIterator = paginate(errorPageFunction, {});
+        let reachedUnreachableCode = undefined;
+        await expect(async () => {
+            for await (const page of pageIterator) {
+                // Should never reach here due to error
+                reachedUnreachableCode = page;
+            }
+        }).rejects.toThrow("Page function failed");
+        // Verify we never reached the unreachable code
+        expect(reachedUnreachableCode).toBeUndefined();
+    });
+    it("should start pagination from provided cursor", async () => {
+        // Test that pagination can start from a specific cursor position
+        const pageIterator = paginate(listTestItems, {
+            pageSize: 3,
+            cursor: "cursor-5", // Start after item 5
+        });
+        const pages = [];
+        for await (const page of pageIterator) {
+            pages.push(page);
+            if (pages.length >= 2)
+                break; // Just test first 2 pages
+        }
+        expect(pages).toHaveLength(2);
+        // First page should start after cursor-5 (from item 6)
+        expect(pages[0].data[0]).toEqual(ALL_ITEMS[5]); // Item 6
+        // Second page should continue properly
+        expect(pages[1].data[0]).toEqual(ALL_ITEMS[8]); // Item 9
+    });
+    it("should allow breaking out of pagination early", async () => {
+        // Test that users can break out of the iterator manually
+        const pageIterator = paginate(listTestItems, { pageSize: 3 });
+        const pages = [];
+        for await (const page of pageIterator) {
+            pages.push(page);
+            // Break after getting 3 pages
+            if (pages.length >= 3) {
+                break;
+            }
+        }
+        // Should have stopped at exactly 3 pages with 9 items (3+3+3=9)
+        const allItems = pages.flatMap((page) => page.data);
+        expect(allItems).toHaveLength(9);
+        expect(pages).toHaveLength(3);
+        // Should be first 9 items
+        expect(allItems).toEqual(ALL_ITEMS.slice(0, 9));
+    });
+    describe("conditional types for optional options", () => {
+        it("should work with function that takes no options", async () => {
+            async function fetchWithNoOptions(_options) {
+                return { data: [1, 2, 3] };
+            }
+            const pages = [];
+            for await (const page of paginate(fetchWithNoOptions)) {
+                pages.push(...page.data);
+            }
+            expect(pages).toEqual([1, 2, 3]);
+        });
+        it("should work with function that takes optional options", async () => {
+            async function fetchWithOptionalOptions(options) {
+                return { data: [`page-${options?.cursor || "1"}`] };
+            }
+            const pages = [];
+            for await (const page of paginate(fetchWithOptionalOptions, {
+                limit: 5,
+            })) {
+                pages.push(...page.data);
+            }
+            expect(pages).toEqual(["page-1"]);
+        });
+        it("should work with function that takes only cursor", async () => {
+            async function fetchWithOnlyCursor(_options) {
+                return { data: [true] };
+            }
+            const pages = [];
+            for await (const page of paginate(fetchWithOnlyCursor, {
+                cursor: "start",
+            })) {
+                pages.push(...page.data);
+            }
+            expect(pages).toEqual([true]);
+        });
+        it("should work when baseOptions is omitted entirely", async () => {
+            async function fetchSimple(_options) {
+                return { data: ["simple"] };
+            }
+            const pages = [];
+            for await (const page of paginate(fetchSimple)) {
+                pages.push(...page.data);
+            }
+            expect(pages).toEqual(["simple"]);
+        });
+    });
+    describe("maxItems functionality", () => {
+        it("should limit total items across pages", async () => {
+            const items = [];
+            for await (const page of paginate(listTestItems, {
+                pageSize: 3,
+                maxItems: 7,
+            })) {
+                items.push(...page.data);
+            }
+            expect(items).toHaveLength(7);
+            expect(items).toEqual(ALL_ITEMS.slice(0, 7));
+        });
+        it("should truncate the final page when maxItems is exceeded", async () => {
+            // Create a function that ignores maxItems hint to force truncation
+            async function fetchIgnoringMaxItems(options) {
+                return listTestItems({
+                    pageSize: options.pageSize,
+                    cursor: options.cursor,
+                });
+            }
+            const pageData = [];
+            for await (const page of paginate(fetchIgnoringMaxItems, {
+                pageSize: 3,
+                maxItems: 7,
+            })) {
+                pageData.push(page);
+            }
+            // Should have 3 pages: [3 items], [3 items], [1 item (truncated)]
+            expect(pageData).toHaveLength(3);
+            expect(pageData[0].data).toHaveLength(3);
+            expect(pageData[1].data).toHaveLength(3);
+            expect(pageData[2].data).toHaveLength(1); // Truncated page
+            expect(pageData[2].nextCursor).toBeUndefined(); // Should clear cursor
+        });
+        it("should stop early when maxItems is exactly a page boundary", async () => {
+            const items = [];
+            for await (const page of paginate(listTestItems, {
+                pageSize: 3,
+                maxItems: 6,
+            })) {
+                items.push(...page.data);
+            }
+            expect(items).toHaveLength(6);
+            expect(items).toEqual(ALL_ITEMS.slice(0, 6));
+        });
+        it("should handle maxItems of 0", async () => {
+            const items = [];
+            for await (const page of paginate(listTestItems, {
+                pageSize: 3,
+                maxItems: 0,
+            })) {
+                items.push(...page.data);
+            }
+            expect(items).toHaveLength(0);
+        });
+        it("should work normally when maxItems is larger than total items", async () => {
+            const items = [];
+            for await (const page of paginate(listTestItems, {
+                pageSize: 3,
+                maxItems: 100,
+            })) {
+                items.push(...page.data);
+            }
+            // Should get all items since limit is higher than total
+            expect(items).toEqual(ALL_ITEMS);
+        });
+        it("should work with maxItems and other options combined", async () => {
+            async function fetchWithLimit(options) {
+                const start = parseInt(options.cursor || "0");
+                let limit = options.limit;
+                // Apply maxItems hint for optimization
+                if (options.maxItems !== undefined && options.maxItems > 0) {
+                    limit = Math.min(limit, options.maxItems);
+                }
+                const items = ALL_ITEMS.slice(start, start + limit);
+                const nextCursor = start + limit < ALL_ITEMS.length
+                    ? (start + limit).toString()
+                    : undefined;
+                return { data: items, nextCursor };
+            }
+            const items = [];
+            for await (const page of paginate(fetchWithLimit, {
+                limit: 2,
+                maxItems: 5,
+            })) {
+                items.push(...page.data);
+            }
+            expect(items).toHaveLength(5);
+            expect(items).toEqual(ALL_ITEMS.slice(0, 5));
+        });
+        it("should preserve original page structure except for truncation", async () => {
+            // Create a function that ignores maxItems hint to force truncation
+            async function fetchIgnoringMaxItems(options) {
+                const pageSize = options.pageSize || 3;
+                const start = options.cursor
+                    ? parseInt(options.cursor.replace("cursor-", "")) + 1
+                    : 0;
+                const items = ALL_ITEMS.slice(start, start + pageSize);
+                const nextCursor = start + pageSize <= ALL_ITEMS.length
+                    ? `cursor-${ALL_ITEMS[start + pageSize - 1].id}`
+                    : undefined;
+                return { data: items, nextCursor };
+            }
+            let pageCount = 0;
+            for await (const page of paginate(fetchIgnoringMaxItems, {
+                pageSize: 3,
+                maxItems: 7,
+            })) {
+                pageCount++;
+                // All pages should have the expected structure
+                expect(page).toHaveProperty("data");
+                expect(Array.isArray(page.data)).toBe(true);
+                if (pageCount === 3) {
+                    // Final truncated page
+                    expect(page.data).toHaveLength(1);
+                    expect(page.nextCursor).toBeUndefined();
+                }
+                else {
+                    // Regular pages
+                    expect(page.data).toHaveLength(3);
+                    expect(typeof page.nextCursor).toBe("string");
+                }
+            }
+            expect(pageCount).toBe(3);
+        });
+        it("should handle API that ignores pageSize and returns more items on first page", async () => {
+            // Simulate an API that ignores pageSize and always returns 10 items per page
+            async function apiIgnoresPageSize(options) {
+                return listTestItems({
+                    cursor: options.cursor,
+                    pageSize: 10,
+                });
+            }
+            const pages = [];
+            // User requests pageSize: 3, but API returns 10 per page
+            for await (const page of paginate(apiIgnoresPageSize, {
+                pageSize: 3,
+            })) {
+                pages.push(page);
+                // Only get first page to test the behavior
+                break;
+            }
+            // Should get 1 page with only 3 items (paginate enforces pageSize limit)
+            expect(pages).toHaveLength(1);
+            expect(pages[0].data).toHaveLength(3);
+            expect(pages[0].data).toEqual(ALL_ITEMS.slice(0, 3));
+            // Cursor should still be present since there are more items available
+            expect(pages[0].nextCursor).toBeDefined();
+        });
+        it("should truncate oversized API response to pageSize", async () => {
+            // API always returns 10 items, but user wants pageSize: 3
+            async function apiReturns10Items(options) {
+                return listTestItems({
+                    cursor: options.cursor,
+                    pageSize: 10,
+                });
+            }
+            const pages = [];
+            for await (const page of paginate(apiReturns10Items, {
+                pageSize: 3,
+            })) {
+                pages.push(page);
+            }
+            // Should truncate each 10-item API response to 3 items per page
+            expect(pages).toHaveLength(9);
+            expect(pages[0].data).toHaveLength(3);
+            expect(pages[1].data).toHaveLength(3);
+            expect(pages[8].data).toHaveLength(1);
+            // Verify items are from different API calls
+            expect(pages[0].data).toEqual(ALL_ITEMS.slice(0, 3)); // Items 1-3 from first API call
+            expect(pages[1].data).toEqual(ALL_ITEMS.slice(3, 6)); // Items 11-13 from second API call
+            expect(pages[8].data).toEqual(ALL_ITEMS.slice(24, 25)); // Items 21-23 from third API call
+            // All pages should have nextCursor since API has more data
+            expect(pages[0].nextCursor).toBe('["$$offset$$",3,null]');
+            expect(pages[8].nextCursor).toBeUndefined();
+        });
+        it("should handle pageSize enforcement with maxItems limit", async () => {
+            // API returns 10 items, user wants pageSize: 3, maxItems: 7
+            async function apiReturns10Items(options) {
+                return listTestItems({
+                    cursor: options.cursor,
+                    pageSize: 10,
+                });
+            }
+            const pages = [];
+            for await (const page of paginate(apiReturns10Items, {
+                pageSize: 3,
+                maxItems: 7,
+            })) {
+                pages.push(page);
+            }
+            // Should get: [3, 3, 1] items (total 7, respecting maxItems)
+            expect(pages).toHaveLength(3);
+            expect(pages[0].data).toHaveLength(3);
+            expect(pages[1].data).toHaveLength(3);
+            expect(pages[2].data).toHaveLength(1); // Truncated to respect maxItems
+            // Last page should have no nextCursor (maxItems reached)
+            expect(pages[2].nextCursor).toBeUndefined();
+            // Verify total items
+            const allItems = pages.flatMap((p) => p.data);
+            expect(allItems).toHaveLength(7);
+            expect(allItems).toEqual(ALL_ITEMS.slice(0, 7));
+        });
+    });
+});

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

@@ -0,0 +1,45 @@
+import { z } from "zod";
+export interface FormattedItem {
+    title: string;
+    subtitle?: string;
+    details: Array<{
+        text: string;
+        style: "normal" | "dim" | "accent" | "warning" | "success";
+    }>;
+}
+export interface FormatMetadata {
+    format: (item: any) => FormattedItem;
+}
+export declare function withFormatter<T extends z.ZodType>(schema: T, formatMeta: FormatMetadata): T;
+export declare function getFormatMetadata(schema: z.ZodType): FormatMetadata | undefined;
+export declare function withOutputSchema<T extends z.ZodType>(inputSchema: T, outputSchema: z.ZodType): T;
+export declare function getOutputSchema(inputSchema: z.ZodType): z.ZodType | undefined;
+export interface StaticResolver {
+    type: "static";
+    inputType?: "text" | "password" | "email";
+    placeholder?: string;
+}
+export interface DynamicResolver {
+    type: "dynamic";
+    fetch: (sdk: any, resolvedParams: any) => Promise<any[]>;
+    prompt: (items: any[], params: any) => any;
+    depends?: string[];
+}
+export interface FieldsResolver {
+    type: "fields";
+    fetch: (sdk: any, resolvedParams: any) => Promise<any[]>;
+    depends?: string[];
+}
+export type ResolverMetadata = StaticResolver | DynamicResolver | FieldsResolver;
+export interface ResolverConfig {
+    resolver: ResolverMetadata;
+}
+export declare function withResolver<T extends z.ZodType>(schema: T, config: ResolverConfig): T;
+export declare function getSchemaDescription(schema: z.ZodSchema): string | undefined;
+export declare function getFieldDescriptions(schema: z.ZodObject<any>): Record<string, string>;
+export interface PositionalMetadata {
+    positional: true;
+}
+export declare function withPositional<T extends z.ZodType>(schema: T): T;
+export declare function isPositional(schema: z.ZodType): boolean;
+//# sourceMappingURL=schema-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema-utils.d.ts","sourceRoot":"","sources":["../../src/utils/schema-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;KAC5D,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,aAAa,CAAC;CACtC;AAGD,wBAAgB,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC/C,MAAM,EAAE,CAAC,EACT,UAAU,EAAE,cAAc,GACzB,CAAC,CAIH;AAGD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,CAAC,CAAC,OAAO,GAChB,cAAc,GAAG,SAAS,CAE5B;AAGD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAClD,WAAW,EAAE,CAAC,EACd,YAAY,EAAE,CAAC,CAAC,OAAO,GACtB,CAAC,CAIH;AAGD,wBAAgB,eAAe,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,GAAG,SAAS,CAE7E;AAMD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACzD,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,KAAK,GAAG,CAAC;IAC3C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACzD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,eAAe,GACf,cAAc,CAAC;AAGnB,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;CAI5B;AAGD,wBAAgB,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC9C,MAAM,EAAE,CAAC,EACT,MAAM,EAAE,cAAc,GACrB,CAAC,CAIH;AAMD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,MAAM,GAAG,SAAS,CAE5E;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,GACvB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB;AAMD,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,IAAI,CAAC;CAClB;AAGD,wBAAgB,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAIhE;AAGD,wBAAgB,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,OAAO,CAiBvD"}

package/dist/utils/schema-utils.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+// Helper function to add format metadata to schemas
+export function withFormatter(schema, formatMeta) {
+    // Store format metadata on the schema definition
+    schema._def.formatMeta = formatMeta;
+    return schema;
+}
+// Helper function to get format metadata from a schema
+export function getFormatMetadata(schema) {
+    return schema._def.formatMeta;
+}
+// Helper function to link input schemas to output schemas
+export function withOutputSchema(inputSchema, outputSchema) {
+    // Store output schema reference on the input schema
+    inputSchema._def.outputSchema = outputSchema;
+    return inputSchema;
+}
+// Helper function to get output schema from an input schema
+export function getOutputSchema(inputSchema) {
+    return inputSchema._def.outputSchema;
+}
+// Helper function to add resolver metadata to schemas
+export function withResolver(schema, config) {
+    // Store resolver metadata on the schema definition
+    schema._def.resolverMeta = config;
+    return schema;
+}
+// ============================================================================
+// Schema Description Utilities
+// ============================================================================
+export function getSchemaDescription(schema) {
+    return schema.description;
+}
+export function getFieldDescriptions(schema) {
+    const descriptions = {};
+    const shape = schema.shape;
+    for (const [key, fieldSchema] of Object.entries(shape)) {
+        if (fieldSchema instanceof z.ZodType && fieldSchema.description) {
+            descriptions[key] = fieldSchema.description;
+        }
+    }
+    return descriptions;
+}
+// Helper function to mark a parameter as positional for CLI
+export function withPositional(schema) {
+    // Store positional metadata on the schema definition
+    schema._def.positionalMeta = { positional: true };
+    return schema;
+}
+// Helper function to check if a parameter should be positional
+export function isPositional(schema) {
+    // Check the current schema first
+    if (schema._def.positionalMeta?.positional) {
+        return true;
+    }
+    // If this is a ZodOptional, check the inner type
+    if (schema instanceof z.ZodOptional) {
+        return isPositional(schema._def.innerType);
+    }
+    // If this is a ZodDefault, check the inner type
+    if (schema instanceof z.ZodDefault) {
+        return isPositional(schema._def.innerType);
+    }
+    return false;
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare function createValidator<TSchema extends z.ZodSchema>(schema: TSchema): (input: unknown) => z.infer<TSchema>;
+export declare const validateOptions: <TOptions, TSchemaOptions extends TOptions>(schema: z.ZodSchema<TSchemaOptions>, options: TOptions) => any;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgCxB,wBAAgB,eAAe,CAAC,OAAO,SAAS,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,IAC/C,OAAO,OAAO,KAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAG7D;AAED,eAAO,MAAM,eAAe,GAAI,QAAQ,EAAE,cAAc,SAAS,QAAQ,EACvE,QAAQ,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,EACnC,SAAS,QAAQ,QAGlB,CAAC"}

package/dist/utils/validation.js

@@ -0,0 +1,30 @@
+import { ZapierValidationError } from "../types/errors";
+/**
+ * Throws clean ZapierValidationError on validation failures
+ */
+const validate = (schema, input) => {
+    const result = schema.safeParse(input);
+    if (!result.success) {
+        // Format Zod errors into a clean, user-friendly message
+        const errorMessages = result.error.errors.map((error) => {
+            const path = error.path.length > 0 ? error.path.join(".") : "input";
+            return `${path}: ${error.message}`;
+        });
+        const message = `Validation failed:\n  ${errorMessages.join("\n  ")}`;
+        throw new ZapierValidationError(message, {
+            details: {
+                zodErrors: result.error.errors,
+                input,
+            },
+        });
+    }
+    return result.data;
+};
+export function createValidator(schema) {
+    return function validateFn(input) {
+        return validate(schema, input);
+    };
+}
+export const validateOptions = (schema, options) => {
+    return validate(schema, options);
+};

package/dist/utils/validation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validation.test.d.ts.map

package/dist/utils/validation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.test.d.ts","sourceRoot":"","sources":["../../src/utils/validation.test.ts"],"names":[],"mappings":""}

package/dist/utils/validation.test.js

@@ -0,0 +1,43 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { createValidator } from "./validation";
+import { ZapierValidationError } from "../types/errors";
+describe("validation utilities", () => {
+    describe("createValidator", () => {
+        it("should validate valid input", () => {
+            const schema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            const validator = createValidator(schema);
+            const result = validator({ name: "John", age: 30 });
+            expect(result).toEqual({ name: "John", age: 30 });
+        });
+        it("should throw ZapierValidationError for invalid input", () => {
+            const schema = z.object({
+                name: z.string(),
+                age: z.number(),
+            });
+            const validator = createValidator(schema);
+            expect(() => {
+                validator({ name: "John", age: "not-a-number" });
+            }).toThrow(ZapierValidationError);
+        });
+        it("should include helpful error messages", () => {
+            const schema = z.object({
+                name: z.string(),
+                age: z.number().min(0),
+            });
+            const validator = createValidator(schema);
+            try {
+                validator({ name: 123, age: -5 });
+            }
+            catch (error) {
+                expect(error).toBeInstanceOf(ZapierValidationError);
+                expect(error.message).toContain("name:");
+                expect(error.message).toContain("age:");
+                expect(error.details.zodErrors).toBeDefined();
+            }
+        });
+    });
+});