@zapier/zapier-sdk 0.29.0 → 0.31.0

package/dist/utils/function-utils.js

@@ -1,21 +1,10 @@
 /**
  * Generic utility functions for creating paginated SDK functions
  */
-import { z } from "zod";
 import { ZapierError, ZapierUnknownError, ZapierAuthenticationError, } from "../types/errors";
 import { paginate } from "./pagination-utils";
 import { createValidator, validateOptions } from "./validation";
-/**
- * Zod schema for telemetry marker to prevent nested telemetry emissions.
- * Used to extend options schemas with proper typing.
- */
-export const TelemetryMarkerSchema = z.object({
-    _telemetry: z
-        .object({
-        isNested: z.boolean().optional(),
-    })
-        .optional(),
-});
+import { isTelemetryNested, runWithTelemetryContext, } from "./telemetry-context";
 /**
  * Helper function to extract cursor from pagination data
  * Supports JSON:API style `links.next` URLs by extracting the `offset` parameter.
@@ -65,19 +54,32 @@ export function createFunction(coreFn, schema, telemetry) {
     // Create a named function using dynamic property access
     const namedFunctions = {
         [functionName]: async function (options) {
-            const startTime = Date.now();
-            const normalizedOptions = (options ?? {});
-            const isNested = normalizedOptions?._telemetry?.isNested === true;
-            try {
-                if (schema) {
-                    const validatedOptions = validateOptions(schema, normalizedOptions);
-                    const result = await coreFn({
-                        ...normalizedOptions,
-                        ...validatedOptions,
-                    });
-                    // Emit telemetry only for top-level calls
+            return runWithTelemetryContext(async () => {
+                const startTime = Date.now();
+                const normalizedOptions = (options ?? {});
+                const isNested = isTelemetryNested();
+                try {
+                    if (schema) {
+                        const validatedOptions = validateOptions(schema, normalizedOptions);
+                        const result = await coreFn({
+                            ...normalizedOptions,
+                            ...validatedOptions,
+                        });
+                        if (!isNested && telemetry?.onMethodCalled) {
+                            const argumentCount = Object.keys(normalizedOptions).length;
+                            telemetry.onMethodCalled({
+                                methodName: functionName,
+                                durationMs: Date.now() - startTime,
+                                success: true,
+                                argumentCount,
+                                isPaginated: false,
+                            });
+                        }
+                        return result;
+                    }
+                    const result = await coreFn(normalizedOptions);
                     if (!isNested && telemetry?.onMethodCalled) {
-                        const argumentCount = Object.keys(normalizedOptions).filter((k) => k !== "_telemetry").length;
+                        const argumentCount = Object.keys(normalizedOptions).length;
                         telemetry.onMethodCalled({
                             methodName: functionName,
                             durationMs: Date.now() - startTime,
@@ -88,34 +90,22 @@ export function createFunction(coreFn, schema, telemetry) {
                     }
                     return result;
                 }
-                const result = await coreFn(normalizedOptions);
-                if (!isNested && telemetry?.onMethodCalled) {
-                    const argumentCount = Object.keys(normalizedOptions).filter((k) => k !== "_telemetry").length;
-                    telemetry.onMethodCalled({
-                        methodName: functionName,
-                        durationMs: Date.now() - startTime,
-                        success: true,
-                        argumentCount,
-                        isPaginated: false,
-                    });
-                }
-                return result;
-            }
-            catch (error) {
-                const normalizedError = normalizeError(error);
-                if (!isNested && telemetry?.onMethodCalled) {
-                    const argumentCount = Object.keys(normalizedOptions).filter((k) => k !== "_telemetry").length;
-                    telemetry.onMethodCalled({
-                        methodName: functionName,
-                        durationMs: Date.now() - startTime,
-                        success: false,
-                        error: normalizedError,
-                        argumentCount,
-                        isPaginated: false,
-                    });
+                catch (error) {
+                    const normalizedError = normalizeError(error);
+                    if (!isNested && telemetry?.onMethodCalled) {
+                        const argumentCount = Object.keys(normalizedOptions).length;
+                        telemetry.onMethodCalled({
+                            methodName: functionName,
+                            durationMs: Date.now() - startTime,
+                            success: false,
+                            error: normalizedError,
+                            argumentCount,
+                            isPaginated: false,
+                        });
+                    }
+                    throw normalizedError;
                 }
-                throw normalizedError;
-            }
+            });
         },
     };
     return namedFunctions[functionName];
@@ -172,81 +162,83 @@ export function createPaginatedFunction(coreFn, schema, telemetry, explicitFunct
     // Create the main paginated function
     const namedFunctions = {
         [functionName]: function (options) {
-            const startTime = Date.now();
-            // Convert undefined options to empty object
-            const normalizedOptions = (options ?? {});
-            const isNested = normalizedOptions?._telemetry?.isNested === true;
-            // Validate options if schema provided (validated fields take precedence)
-            const validatedOptions = {
-                ...normalizedOptions,
-                ...(validator ? validator(normalizedOptions) : normalizedOptions),
-            };
-            // Set default pageSize if not provided
-            const pageSize = validatedOptions.pageSize || 100;
-            const optimizedOptions = {
-                ...validatedOptions,
-                pageSize,
-            };
-            const iterator = paginate(pageFunction, optimizedOptions);
-            // Get a promise for the first iteration
-            const firstPagePromise = iterator.next().then((result) => {
-                if (result.done) {
-                    throw new Error("Paginate should always iterate at least once");
-                }
-                return result.value;
-            });
-            // Emit telemetry after first page completes
-            if (!isNested && telemetry?.onMethodCalled) {
-                firstPagePromise
-                    .then(() => {
-                    const argumentCount = Object.keys(normalizedOptions).filter((k) => k !== "_telemetry").length;
-                    telemetry.onMethodCalled({
-                        methodName: functionName,
-                        durationMs: Date.now() - startTime,
-                        success: true,
-                        argumentCount,
-                        isPaginated: true,
-                    });
-                })
-                    .catch((error) => {
-                    const argumentCount = Object.keys(normalizedOptions).filter((k) => k !== "_telemetry").length;
-                    telemetry.onMethodCalled({
-                        methodName: functionName,
-                        durationMs: Date.now() - startTime,
-                        success: false,
-                        error: error instanceof Error ? error : new Error(String(error)),
-                        argumentCount,
-                        isPaginated: true,
-                    });
-                });
-            }
-            // Add Symbol.asyncIterator to make the promise iterable
-            return Object.assign(firstPagePromise, {
-                [Symbol.asyncIterator]: async function* () {
-                    // Yield the first page (await the promise)
-                    yield await firstPagePromise;
-                    // Yield the rest of the pages
-                    for await (const page of iterator) {
-                        yield page;
+            return runWithTelemetryContext(() => {
+                const startTime = Date.now();
+                // Convert undefined options to empty object
+                const normalizedOptions = (options ?? {});
+                const isNested = isTelemetryNested();
+                // Validate options if schema provided (validated fields take precedence)
+                const validatedOptions = {
+                    ...normalizedOptions,
+                    ...(validator ? validator(normalizedOptions) : normalizedOptions),
+                };
+                // Set default pageSize if not provided
+                const pageSize = validatedOptions.pageSize || 100;
+                const optimizedOptions = {
+                    ...validatedOptions,
+                    pageSize,
+                };
+                const iterator = paginate(pageFunction, optimizedOptions);
+                // Get a promise for the first iteration
+                const firstPagePromise = iterator.next().then((result) => {
+                    if (result.done) {
+                        throw new Error("Paginate should always iterate at least once");
                     }
-                },
-                items: function () {
-                    return {
-                        [Symbol.asyncIterator]: async function* () {
-                            // Yield the first page items
-                            const firstPage = await firstPagePromise;
-                            for (const item of firstPage.data) {
-                                yield item;
-                            }
-                            // Yield items from the rest of the pages
-                            for await (const page of iterator) {
-                                for (const item of page.data) {
+                    return result.value;
+                });
+                // Emit telemetry after first page completes
+                if (!isNested && telemetry?.onMethodCalled) {
+                    firstPagePromise
+                        .then(() => {
+                        const argumentCount = Object.keys(normalizedOptions).length;
+                        telemetry.onMethodCalled({
+                            methodName: functionName,
+                            durationMs: Date.now() - startTime,
+                            success: true,
+                            argumentCount,
+                            isPaginated: true,
+                        });
+                    })
+                        .catch((error) => {
+                        const argumentCount = Object.keys(normalizedOptions).length;
+                        telemetry.onMethodCalled({
+                            methodName: functionName,
+                            durationMs: Date.now() - startTime,
+                            success: false,
+                            error: error instanceof Error ? error : new Error(String(error)),
+                            argumentCount,
+                            isPaginated: true,
+                        });
+                    });
+                }
+                // Add Symbol.asyncIterator to make the promise iterable
+                return Object.assign(firstPagePromise, {
+                    [Symbol.asyncIterator]: async function* () {
+                        // Yield the first page (await the promise)
+                        yield await firstPagePromise;
+                        // Yield the rest of the pages
+                        for await (const page of iterator) {
+                            yield page;
+                        }
+                    },
+                    items: function () {
+                        return {
+                            [Symbol.asyncIterator]: async function* () {
+                                // Yield the first page items
+                                const firstPage = await firstPagePromise;
+                                for (const item of firstPage.data) {
                                     yield item;
                                 }
-                            }
-                        },
-                    };
-                },
+                                // Yield items from the rest of the pages
+                                for await (const page of iterator) {
+                                    for (const item of page.data) {
+                                        yield item;
+                                    }
+                                }
+                            },
+                        };
+                    },
+                });
             });
         },
     };

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

@@ -1,7 +1,8 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import { createFunction, createPaginatedFunction } from "./function-utils";
 import { ZapierValidationError, ZapierUnknownError } from "../types/errors";
 import { ALL_ITEMS, listTestItems } from "./pagination-utils.test";
+import { isTelemetryNested } from "./telemetry-context";
 describe("createFunction", () => {
     it("should return result from core function", async () => {
         const mockCoreFn = async (options) => {
@@ -108,3 +109,80 @@ describe("createPaginatedFunction", () => {
         expect(items).toEqual(ALL_ITEMS.slice(0, 7));
     });
 });
+describe("telemetry nesting via AsyncLocalStorage", () => {
+    it("emits telemetry for a top-level createFunction call", async () => {
+        const onMethodCalled = vi.fn();
+        const telemetry = { onMethodCalled };
+        async function myMethod(options) {
+            return options.value * 2;
+        }
+        const wrapped = createFunction(myMethod, undefined, telemetry);
+        await wrapped({ value: 5 });
+        expect(onMethodCalled).toHaveBeenCalledOnce();
+        expect(onMethodCalled).toHaveBeenCalledWith(expect.objectContaining({
+            methodName: "myMethod",
+            success: true,
+            isPaginated: false,
+        }));
+    });
+    it("emits telemetry for a top-level createPaginatedFunction call", async () => {
+        const onMethodCalled = vi.fn();
+        const wrapped = createPaginatedFunction(listTestItems, undefined, { onMethodCalled }, "topLevelList");
+        await wrapped({ pageSize: 3 });
+        expect(onMethodCalled).toHaveBeenCalledOnce();
+        expect(onMethodCalled).toHaveBeenCalledWith(expect.objectContaining({
+            methodName: "topLevelList",
+            success: true,
+            isPaginated: true,
+        }));
+    });
+    it("suppresses telemetry when createFunction calls another createFunction", async () => {
+        const outerTelemetry = vi.fn();
+        const innerTelemetry = vi.fn();
+        async function innerMethod(_options) {
+            return "inner";
+        }
+        const wrappedInner = createFunction(innerMethod, undefined, {
+            onMethodCalled: innerTelemetry,
+        });
+        async function outerMethod(_options) {
+            return wrappedInner({});
+        }
+        const wrappedOuter = createFunction(outerMethod, undefined, {
+            onMethodCalled: outerTelemetry,
+        });
+        await wrappedOuter({});
+        expect(outerTelemetry).toHaveBeenCalledOnce();
+        expect(innerTelemetry).not.toHaveBeenCalled();
+    });
+    it("suppresses telemetry for nested createPaginatedFunction calls", async () => {
+        const outerTelemetry = vi.fn();
+        const innerTelemetry = vi.fn();
+        const wrappedInner = createPaginatedFunction(listTestItems, undefined, { onMethodCalled: innerTelemetry }, "innerList");
+        async function outerMethod(_options) {
+            const result = await wrappedInner({ pageSize: 3 });
+            return result.data;
+        }
+        const wrappedOuter = createFunction(outerMethod, undefined, {
+            onMethodCalled: outerTelemetry,
+        });
+        await wrappedOuter({});
+        expect(outerTelemetry).toHaveBeenCalledOnce();
+        expect(innerTelemetry).not.toHaveBeenCalled();
+    });
+    it("context is restored after nested call completes", async () => {
+        expect(isTelemetryNested()).toBe(false);
+        async function inner(_options) {
+            return "inner";
+        }
+        const wrappedInner = createFunction(inner);
+        async function outer(_options) {
+            await wrappedInner({});
+            expect(isTelemetryNested()).toBe(false);
+            return "outer";
+        }
+        const wrappedOuter = createFunction(outer);
+        await wrappedOuter({});
+        expect(isTelemetryNested()).toBe(false);
+    });
+});

package/dist/utils/telemetry-context.d.ts

@@ -0,0 +1,3 @@
+export declare function isTelemetryNested(): boolean;
+export declare function runWithTelemetryContext<T>(fn: () => T): T;
+//# sourceMappingURL=telemetry-context.d.ts.map

package/dist/utils/telemetry-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry-context.d.ts","sourceRoot":"","sources":["../../src/utils/telemetry-context.ts"],"names":[],"mappings":"AAmBA,wBAAgB,iBAAiB,IAAI,OAAO,CAI3C;AAED,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAIzD"}

package/dist/utils/telemetry-context.js

@@ -0,0 +1,23 @@
+// Intentional dynamic require — one-time environment detection for AsyncLocalStorage
+// availability (e.g., unavailable in browsers). This is NOT lazy loading.
+let telemetryStore = null;
+try {
+    const mod = require("node:async_hooks");
+    telemetryStore = new mod.AsyncLocalStorage();
+}
+catch {
+    // In non-Node environments, telemetry is disabled entirely (isTelemetryNested
+    // always returns true) since we can't reliably deduplicate nested calls.
+}
+export function isTelemetryNested() {
+    if (!telemetryStore)
+        return true;
+    const store = telemetryStore.getStore();
+    return store !== undefined && store.depth > 0;
+}
+export function runWithTelemetryContext(fn) {
+    if (!telemetryStore)
+        return fn();
+    const currentDepth = telemetryStore.getStore()?.depth ?? -1;
+    return telemetryStore.run({ depth: currentDepth + 1 }, fn);
+}

package/dist/utils/telemetry-context.test.d.ts

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

package/dist/utils/telemetry-context.test.d.ts.map

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

package/dist/utils/telemetry-context.test.js

@@ -0,0 +1,92 @@
+import { describe, it, expect } from "vitest";
+import { isTelemetryNested, runWithTelemetryContext, } from "./telemetry-context";
+describe("telemetry-context", () => {
+    describe("isTelemetryNested", () => {
+        it("returns false outside any context", () => {
+            expect(isTelemetryNested()).toBe(false);
+        });
+        it("returns false inside top-level runWithTelemetryContext (depth 0)", () => {
+            runWithTelemetryContext(() => {
+                expect(isTelemetryNested()).toBe(false);
+            });
+        });
+        it("returns true inside nested runWithTelemetryContext (depth 1)", () => {
+            runWithTelemetryContext(() => {
+                runWithTelemetryContext(() => {
+                    expect(isTelemetryNested()).toBe(true);
+                });
+            });
+        });
+        it("returns true at deeper nesting levels", () => {
+            runWithTelemetryContext(() => {
+                runWithTelemetryContext(() => {
+                    runWithTelemetryContext(() => {
+                        expect(isTelemetryNested()).toBe(true);
+                    });
+                });
+            });
+        });
+        it("restores context after exiting nested scope", () => {
+            runWithTelemetryContext(() => {
+                expect(isTelemetryNested()).toBe(false);
+                runWithTelemetryContext(() => {
+                    expect(isTelemetryNested()).toBe(true);
+                });
+                expect(isTelemetryNested()).toBe(false);
+            });
+            expect(isTelemetryNested()).toBe(false);
+        });
+    });
+    describe("async boundaries", () => {
+        it("works correctly across async/await boundaries", async () => {
+            await runWithTelemetryContext(async () => {
+                expect(isTelemetryNested()).toBe(false);
+                await new Promise((resolve) => setTimeout(resolve, 1));
+                expect(isTelemetryNested()).toBe(false);
+                await runWithTelemetryContext(async () => {
+                    expect(isTelemetryNested()).toBe(true);
+                    await new Promise((resolve) => setTimeout(resolve, 1));
+                    expect(isTelemetryNested()).toBe(true);
+                });
+            });
+        });
+        it("isolates parallel async calls from each other", async () => {
+            const results = [];
+            await runWithTelemetryContext(async () => {
+                const task1 = runWithTelemetryContext(async () => {
+                    await new Promise((resolve) => setTimeout(resolve, 5));
+                    results.push({ id: "task1-inner", nested: isTelemetryNested() });
+                });
+                const task2 = (async () => {
+                    await new Promise((resolve) => setTimeout(resolve, 1));
+                    results.push({ id: "task2-top", nested: isTelemetryNested() });
+                })();
+                await Promise.all([task1, task2]);
+            });
+            const task1Result = results.find((r) => r.id === "task1-inner");
+            const task2Result = results.find((r) => r.id === "task2-top");
+            expect(task1Result?.nested).toBe(true);
+            expect(task2Result?.nested).toBe(false);
+        });
+    });
+    describe("runWithTelemetryContext", () => {
+        it("returns the value from the wrapped function", () => {
+            const result = runWithTelemetryContext(() => 42);
+            expect(result).toBe(42);
+        });
+        it("returns async values from the wrapped function", async () => {
+            const result = await runWithTelemetryContext(async () => "hello");
+            expect(result).toBe("hello");
+        });
+        it("propagates errors from the wrapped function", () => {
+            expect(() => runWithTelemetryContext(() => {
+                throw new Error("test error");
+            })).toThrow("test error");
+        });
+        it("propagates async errors from the wrapped function", async () => {
+            await expect(runWithTelemetryContext(async () => {
+                throw new Error("async test error");
+            })).rejects.toThrow("async test error");
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zapier/zapier-sdk",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "description": "Complete Zapier SDK - combines all Zapier SDK packages",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",