@zapier/zapier-sdk 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/zapier-sdk
 
+## 0.23.0
+
+### Minor Changes
+
+- 7cf2b12: Add debug logging to zapier-sdk-cli-login. Only allow one token refresh at a time.
+
+## 0.22.1
+
+### Patch Changes
+
+- 8ebde4b: Add required scopes for credentials methods.
+
 ## 0.22.0
 
 ### Minor Changes

package/dist/api/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AA0fjB,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,SAW3D,CAAC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/api/client.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAGjB,MAAM,SAAS,CAAC;AA2gBjB,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,SAW3D,CAAC"}

package/dist/api/client.js

@@ -69,18 +69,20 @@ class ZapierApiClient {
         }
     }
     // Helper to get a token from the different places it could be gotten
-    async getAuthToken() {
+    async getAuthToken(options) {
         return resolveAuthToken({
             credentials: this.options.credentials,
             token: this.options.token,
             onEvent: this.options.onEvent,
             fetch: this.options.fetch,
             baseUrl: this.options.baseUrl,
+            requiredScopes: options?.requiredScopes,
+            debug: this.options.debug,
         });
     }
     // Helper to handle responses
     async handleResponse(params) {
-        const { response, customErrorHandler, wasMissingAuthToken } = params;
+        const { response, customErrorHandler, wasMissingAuthToken, requiredScopes, } = params;
         const { data: responseData } = await this.parseResult(response);
         if (response.ok) {
             return responseData;
@@ -123,6 +125,7 @@ class ZapierApiClient {
                 await invalidateCredentialsToken({
                     credentials: this.options.credentials,
                     token: this.options.token,
+                    requiredScopes,
                 });
             }
             throw new ZapierAuthenticationError(message, errorOptions);
@@ -237,6 +240,16 @@ class ZapierApiClient {
         // Find matching path configuration.
         const matchingPathKey = Object.keys(pathConfig).find((configPath) => path === configPath || path.startsWith(configPath + "/"));
         const config = matchingPathKey ? pathConfig[matchingPathKey] : undefined;
+        // Apply pathPrefix if there's a matching config with pathPrefix.
+        let finalPath = path;
+        if (config &&
+            "pathPrefix" in config &&
+            config.pathPrefix &&
+            matchingPathKey) {
+            // Strip the matching path key, and use the pathPrefix instead.
+            const pathWithoutPrefix = path.slice(matchingPathKey.length) || "/";
+            finalPath = `${config.pathPrefix}${pathWithoutPrefix}`;
+        }
         // Check if baseUrl is a Zapier-inferred base URL.
         const zapierBaseUrl = getZapierBaseUrl(this.options.baseUrl);
         // Let's remain compatible with a base URL that is set to a Zapier-inferred
@@ -246,26 +259,17 @@ class ZapierApiClient {
             // If baseUrl is already the Zapier base URL, use sdkapi subdomain.
             const originalBaseUrl = new URL(this.options.baseUrl);
             const finalBaseUrl = `https://sdkapi.${originalBaseUrl.hostname}`;
-            // Only prepend pathPrefix if there's a matching config with pathPrefix.
-            let finalPath = path;
-            if (config &&
-                "pathPrefix" in config &&
-                config.pathPrefix &&
-                matchingPathKey) {
-                // Strip the matching path key, and use the pathPrefix instead.
-                const pathWithoutPrefix = path.slice(matchingPathKey.length) || "/";
-                finalPath = `${config.pathPrefix}${pathWithoutPrefix}`;
-            }
             return {
                 url: new URL(finalPath, finalBaseUrl),
                 pathConfig: config,
             };
         }
-        // For a base URL that isn't a Zapier-inferred domain, use the whole base URL.
+        // For a base URL that isn't a Zapier-inferred domain (e.g., localhost),
+        // preserve any path from the base URL and append the final path.
         const baseUrl = new URL(this.options.baseUrl);
-        const fullPath = baseUrl.pathname.replace(/\/$/, "") + path;
+        const basePath = baseUrl.pathname.replace(/\/$/, "");
         return {
-            url: new URL(fullPath, baseUrl.origin),
+            url: new URL(basePath + finalPath, baseUrl.origin),
             pathConfig: config,
         };
     }
@@ -286,7 +290,9 @@ class ZapierApiClient {
         // useful context to the API. The session is a good example of this. Auth
         // is not required, but if we don't add auth, then we won't get the user's
         // session!
-        const authToken = await this.getAuthToken();
+        const authToken = await this.getAuthToken({
+            requiredScopes: options.requiredScopes,
+        });
         if (authToken) {
             const authHeaderName = pathConfig && pathConfig.authHeader
                 ? pathConfig.authHeader
@@ -310,7 +316,9 @@ class ZapierApiClient {
             headers["Content-Type"] = "application/json";
         }
         // Check if we have an auth token available
-        const wasMissingAuthToken = options.authRequired && (await this.getAuthToken()) == null;
+        const wasMissingAuthToken = options.authRequired &&
+            (await this.getAuthToken({ requiredScopes: options.requiredScopes })) ==
+                null;
         const response = await this.plainFetch(path, {
             ...options,
             method,
@@ -322,6 +330,7 @@ class ZapierApiClient {
             response,
             customErrorHandler: options.customErrorHandler,
             wasMissingAuthToken,
+            requiredScopes: options.requiredScopes,
         });
         // Allow empty responses for DELETE or 204 No Content
         if (typeof result === "string") {

package/dist/api/client.test.js

@@ -5,14 +5,16 @@ vi.mock("../auth");
 describe("ApiClient", () => {
     const mockResolveAuthToken = vi.mocked(auth.resolveAuthToken);
     const mockInvalidateCredentialsToken = vi.mocked(auth.invalidateCredentialsToken);
+    let mockFetch;
     beforeEach(() => {
         vi.clearAllMocks();
         // Prevent any actual HTTP calls
-        global.fetch = vi.fn().mockResolvedValue({
+        mockFetch = vi.fn().mockResolvedValue({
             ok: true,
             status: 200,
             text: () => Promise.resolve(JSON.stringify({ data: "test" })),
         });
+        global.fetch = mockFetch;
     });
     describe("authentication token resolution", () => {
         it("should pass credentials to resolveAuthToken when provided", async () => {
@@ -35,6 +37,8 @@ describe("ApiClient", () => {
                 onEvent: undefined,
                 fetch: expect.any(Function),
                 baseUrl: "https://api.custom.zapier.dev",
+                requiredScopes: undefined,
+                debug: false,
             });
         });
         it("should pass undefined credentials when not provided", async () => {
@@ -51,6 +55,8 @@ describe("ApiClient", () => {
                 onEvent: undefined,
                 fetch: expect.any(Function),
                 baseUrl: "https://api.custom.zapier.dev",
+                requiredScopes: undefined,
+                debug: false,
             });
         });
         it("should pass deprecated token option to resolveAuthToken", async () => {
@@ -69,6 +75,8 @@ describe("ApiClient", () => {
                 onEvent: undefined,
                 fetch: expect.any(Function),
                 baseUrl: "https://api.custom.zapier.dev",
+                requiredScopes: undefined,
+                debug: false,
             });
         });
         it("should pass string credentials to resolveAuthToken", async () => {
@@ -85,6 +93,8 @@ describe("ApiClient", () => {
                 onEvent: undefined,
                 fetch: expect.any(Function),
                 baseUrl: "https://api.custom.zapier.dev",
+                requiredScopes: undefined,
+                debug: false,
             });
         });
         it("should pass credentials function to resolveAuthToken", async () => {
@@ -102,6 +112,8 @@ describe("ApiClient", () => {
                 onEvent: undefined,
                 fetch: expect.any(Function),
                 baseUrl: "https://api.custom.zapier.dev",
+                requiredScopes: undefined,
+                debug: false,
             });
         });
     });
@@ -148,4 +160,72 @@ describe("ApiClient", () => {
             expect(mockInvalidateCredentialsToken).not.toHaveBeenCalled();
         });
     });
+    describe("URL path configuration", () => {
+        beforeEach(() => {
+            mockResolveAuthToken.mockResolvedValue("test-token");
+        });
+        it("should apply pathPrefix for /relay path with Zapier base URL", async () => {
+            const client = createZapierApi({
+                baseUrl: "https://zapier.com",
+                credentials: "test-token",
+                debug: false,
+            });
+            await client.get("/relay/some/path");
+            expect(mockFetch).toHaveBeenCalledWith("https://sdkapi.zapier.com/api/v0/sdk/relay/some/path", expect.any(Object));
+        });
+        it("should apply pathPrefix for /zapier path with Zapier base URL", async () => {
+            const client = createZapierApi({
+                baseUrl: "https://zapier.com",
+                credentials: "test-token",
+                debug: false,
+            });
+            await client.get("/zapier/apps");
+            expect(mockFetch).toHaveBeenCalledWith("https://sdkapi.zapier.com/api/v0/sdk/zapier/apps", expect.any(Object));
+        });
+        it("should apply pathPrefix for /relay path with localhost base URL", async () => {
+            const client = createZapierApi({
+                baseUrl: "http://localhost:3000",
+                credentials: "test-token",
+                debug: false,
+            });
+            await client.get("/relay/some/path");
+            expect(mockFetch).toHaveBeenCalledWith("http://localhost:3000/api/v0/sdk/relay/some/path", expect.any(Object));
+        });
+        it("should apply pathPrefix for /zapier path with localhost base URL", async () => {
+            const client = createZapierApi({
+                baseUrl: "http://localhost:3000",
+                credentials: "test-token",
+                debug: false,
+            });
+            await client.get("/zapier/apps");
+            expect(mockFetch).toHaveBeenCalledWith("http://localhost:3000/api/v0/sdk/zapier/apps", expect.any(Object));
+        });
+        it("should not apply pathPrefix for non-configured paths", async () => {
+            const client = createZapierApi({
+                baseUrl: "http://localhost:3000",
+                credentials: "test-token",
+                debug: false,
+            });
+            await client.get("/other/path");
+            expect(mockFetch).toHaveBeenCalledWith("http://localhost:3000/other/path", expect.any(Object));
+        });
+        it("should handle exact path match for pathPrefix", async () => {
+            const client = createZapierApi({
+                baseUrl: "http://localhost:3000",
+                credentials: "test-token",
+                debug: false,
+            });
+            await client.get("/relay");
+            expect(mockFetch).toHaveBeenCalledWith("http://localhost:3000/api/v0/sdk/relay/", expect.any(Object));
+        });
+        it("should preserve base URL path for localhost with path component", async () => {
+            const client = createZapierApi({
+                baseUrl: "http://localhost:3000/a/b/c",
+                credentials: "test-token",
+                debug: false,
+            });
+            await client.get("/relay/some/path");
+            expect(mockFetch).toHaveBeenCalledWith("http://localhost:3000/a/b/c/api/v0/sdk/relay/some/path", expect.any(Object));
+        });
+    });
 });

package/dist/api/types.d.ts

@@ -43,6 +43,12 @@ export interface RequestOptions {
     headers?: Record<string, string>;
     searchParams?: Record<string, string>;
     authRequired?: boolean;
+    /**
+     * OAuth scopes required for this request. When using client credentials,
+     * these scopes will be requested during token exchange (merged with any
+     * scopes specified in the credentials object).
+     */
+    requiredScopes?: string[];
     customErrorHandler?: (errorInfo: {
         status: number;
         statusText: string;

package/dist/api/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/api/types.ts"],"names":[],"mappings":"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"}

package/dist/auth.d.ts

@@ -23,15 +23,24 @@ export interface ResolveAuthTokenOptions {
     onEvent?: EventCallback;
     fetch?: typeof globalThis.fetch;
     baseUrl?: string;
+    /**
+     * Additional OAuth scopes required for this request. When using client
+     * credentials, these scopes will be merged with any scopes specified in
+     * the credentials object during token exchange.
+     */
+    requiredScopes?: string[];
+    /** Enable debug logging for auth operations. */
+    debug?: boolean;
 }
 /**
  * Clear the token cache. Useful for testing or forcing re-authentication.
  */
 export declare function clearTokenCache(): void;
 /**
- * Invalidate a cached token. Called when we get a 401 response.
+ * Invalidate a cached token for a specific clientId and scope combination.
+ * Called when we get a 401 response.
  */
-export declare function invalidateCachedToken(clientId: string): void;
+export declare function invalidateCachedToken(clientId: string, scopes: string[]): void;
 /**
  * Options for getTokenFromCliLogin.
  */
@@ -44,6 +53,7 @@ interface CliLoginOptions {
         baseUrl?: string;
         scope?: string;
     };
+    debug?: boolean;
 }
 /**
  * Attempts to get a token by optionally importing from CLI login package.
@@ -77,5 +87,6 @@ export declare function resolveAuthToken(options?: ResolveAuthTokenOptions): Pro
 export declare function invalidateCredentialsToken(options: {
     credentials?: Credentials;
     token?: string;
+    requiredScopes?: string[];
 }): Promise<void>;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,qBAAqB,CAAC;AAM5E,YAAY,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,aAAa,GACd,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAsBD;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAoCD;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE5D;AAsFD;;GAEG;AACH,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,WAAW,CAAC,EAAE;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgB7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAiB7B;AAuED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE;IACxD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,qBAAqB,CAAC;AAM5E,YAAY,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,aAAa,GACd,MAAM,gBAAgB,CAAC;AAGxB,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,EACvB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA+BD;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AA0CD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EAAE,GACf,IAAI,CAIN;AA6HD;;GAEG;AACH,UAAU,eAAe;IACvB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,WAAW,CAAC,EAAE;QACZ,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgB7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAkB7B;AA6ED;;;;GAIG;AACH,wBAAsB,0BAA0B,CAAC,OAAO,EAAE;IACxD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAQhB"}

package/dist/auth.js

@@ -14,14 +14,22 @@ import { ZAPIER_BASE_URL } from "./constants";
 export { isClientCredentials, isPkceCredentials, isCredentialsObject, isCredentialsFunction, } from "./types/credentials";
 /**
  * In-memory cache for tokens obtained via client credentials flow.
- * Keyed by clientId.
+ * Keyed by clientId + sorted scopes.
  */
 const tokenCache = new Map();
 /**
  * In-flight token exchange promises to prevent duplicate exchanges.
  * When an exchange is in progress, subsequent calls await the same promise.
+ * Keyed by clientId + sorted scopes.
  */
 const pendingExchanges = new Map();
+/**
+ * Build a cache key from clientId and scopes.
+ */
+function buildCacheKey(clientId, scopes) {
+    const sortedScopes = [...scopes].sort().join(",");
+    return `${clientId}:${sortedScopes}`;
+}
 /**
  * Clear the token cache. Useful for testing or forcing re-authentication.
  */
@@ -34,8 +42,9 @@ const TOKEN_EXPIRATION_BUFFER = 5 * 60 * 1000; // 5 minutes
  * Get a cached token if it exists and is not expired.
  * Returns undefined if no valid cached token exists.
  */
-function getCachedToken(clientId) {
-    const cached = tokenCache.get(clientId);
+function getCachedToken(clientId, scopes) {
+    const cacheKey = buildCacheKey(clientId, scopes);
+    const cached = tokenCache.get(cacheKey);
     if (!cached)
         return undefined;
     // Check if token is still valid (with expiration buffer)
@@ -43,23 +52,27 @@ function getCachedToken(clientId) {
         return cached.accessToken;
     }
     // Token expired, remove from cache
-    tokenCache.delete(clientId);
+    tokenCache.delete(cacheKey);
     return undefined;
 }
 /**
  * Cache a token obtained from client credentials flow.
  */
-function cacheToken(clientId, accessToken, expiresIn) {
-    tokenCache.set(clientId, {
+function cacheToken(clientId, scopes, accessToken, expiresIn) {
+    const cacheKey = buildCacheKey(clientId, scopes);
+    tokenCache.set(cacheKey, {
         accessToken,
         expiresAt: Date.now() + expiresIn * 1000,
     });
 }
 /**
- * Invalidate a cached token. Called when we get a 401 response.
+ * Invalidate a cached token for a specific clientId and scope combination.
+ * Called when we get a 401 response.
  */
-export function invalidateCachedToken(clientId) {
-    tokenCache.delete(clientId);
+export function invalidateCachedToken(clientId, scopes) {
+    const cacheKey = buildCacheKey(clientId, scopes);
+    tokenCache.delete(cacheKey);
+    pendingExchanges.delete(cacheKey);
 }
 /**
  * Get the token endpoint URL for client credentials exchange.
@@ -68,13 +81,43 @@ function getTokenEndpointUrl(baseUrl) {
     const base = baseUrl || ZAPIER_BASE_URL;
     return `${base}/oauth/token/`;
 }
+/**
+ * Merge and deduplicate scopes from credentials and required scopes.
+ * If no credentials scope is specified, defaults to "external".
+ * Returns a sorted array of unique scopes.
+ */
+function mergeScopes(credentialsScope, requiredScopes) {
+    const scopeSet = new Set();
+    // Add scopes from credentials (space-separated string)
+    // If no credentials scope specified, default to "external"
+    if (credentialsScope) {
+        for (const s of credentialsScope.split(" ")) {
+            if (s.trim()) {
+                scopeSet.add(s.trim());
+            }
+        }
+    }
+    else {
+        scopeSet.add("external");
+    }
+    // Add required scopes
+    if (requiredScopes) {
+        for (const s of requiredScopes) {
+            scopeSet.add(s);
+        }
+    }
+    return [...scopeSet].sort();
+}
 /**
  * Exchange client credentials for an access token.
  */
 async function exchangeClientCredentials(options) {
-    const { clientId, clientSecret, baseUrl, scope, onEvent } = options;
+    const { clientId, clientSecret, baseUrl, scope, requiredScopes, onEvent } = options;
     const fetchFn = options.fetch || globalThis.fetch;
     const tokenUrl = getTokenEndpointUrl(baseUrl);
+    // Merge credentials scope with required scopes
+    const mergedScopes = mergeScopes(scope, requiredScopes);
+    const scopeString = mergedScopes.join(" ");
     onEvent?.({
         type: "auth_exchanging",
         payload: {
@@ -92,7 +135,7 @@ async function exchangeClientCredentials(options) {
             grant_type: "client_credentials",
             client_id: clientId,
             client_secret: clientSecret,
-            scope: scope || "external",
+            scope: scopeString,
             audience: "zapier.com",
         }),
     });
@@ -113,9 +156,9 @@ async function exchangeClientCredentials(options) {
     if (!data.access_token) {
         throw new Error("Client credentials response missing access_token");
     }
-    // Cache the token
+    // Cache the token with the scopes used
     const expiresIn = data.expires_in || 3600; // Default to 1 hour
-    cacheToken(clientId, data.access_token, expiresIn);
+    cacheToken(clientId, mergedScopes, data.access_token, expiresIn);
     onEvent?.({
         type: "auth_success",
         payload: {
@@ -177,6 +220,7 @@ export async function resolveAuthToken(options = {}) {
     return getTokenFromCliLogin({
         onEvent: options.onEvent,
         fetch: options.fetch,
+        debug: options.debug,
     });
 }
 /**
@@ -190,13 +234,16 @@ async function resolveAuthTokenFromCredentials(credentials, options) {
     // Client credentials: exchange for token
     if (isClientCredentials(credentials)) {
         const { clientId } = credentials;
+        // Compute merged scopes for cache lookup
+        const mergedScopes = mergeScopes(credentials.scope, options.requiredScopes);
+        const cacheKey = buildCacheKey(clientId, mergedScopes);
         // Check cache first
-        const cached = getCachedToken(clientId);
+        const cached = getCachedToken(clientId, mergedScopes);
         if (cached) {
             return cached;
         }
-        // Check if there's already an exchange in progress for this clientId
-        const pending = pendingExchanges.get(clientId);
+        // Check if there's already an exchange in progress for this clientId + scopes
+        const pending = pendingExchanges.get(cacheKey);
         if (pending) {
             return pending;
         }
@@ -206,13 +253,14 @@ async function resolveAuthTokenFromCredentials(credentials, options) {
             clientSecret: credentials.clientSecret,
             baseUrl: credentials.baseUrl || options.baseUrl,
             scope: credentials.scope,
+            requiredScopes: options.requiredScopes,
             fetch: options.fetch,
             onEvent: options.onEvent,
         }).finally(() => {
             // Remove from pending when done (success or failure)
-            pendingExchanges.delete(clientId);
+            pendingExchanges.delete(cacheKey);
         });
-        pendingExchanges.set(clientId, exchangePromise);
+        pendingExchanges.set(cacheKey, exchangePromise);
         return exchangePromise;
     }
     // PKCE credentials: delegate to CLI login
@@ -222,6 +270,7 @@ async function resolveAuthTokenFromCredentials(credentials, options) {
             onEvent: options.onEvent,
             fetch: options.fetch,
             credentials,
+            debug: options.debug,
         });
         if (storedToken) {
             return storedToken;
@@ -240,8 +289,11 @@ async function resolveAuthTokenFromCredentials(credentials, options) {
  */
 export async function invalidateCredentialsToken(options) {
     const resolved = await resolveCredentials(options);
+    if (!resolved)
+        return;
     const clientId = getClientIdFromCredentials(resolved);
-    if (clientId) {
-        invalidateCachedToken(clientId);
+    if (clientId && isClientCredentials(resolved)) {
+        const scopes = mergeScopes(resolved.scope, options.requiredScopes);
+        invalidateCachedToken(clientId, scopes);
     }
 }

package/dist/auth.test.js

@@ -218,6 +218,102 @@ describe("auth", () => {
                 fetch: mockFetch,
             })).rejects.toThrow("Client credentials exchange failed");
         });
+        it("should merge requiredScopes with credentials scope", async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({
+                    access_token: "merged-scope-token",
+                    expires_in: 3600,
+                }),
+            });
+            await auth.resolveAuthToken({
+                credentials: {
+                    type: "client_credentials",
+                    clientId: "scope-test-client",
+                    clientSecret: "secret",
+                    scope: "external",
+                },
+                requiredScopes: ["credentials"],
+                fetch: mockFetch,
+            });
+            const callArgs = mockFetch.mock.calls[0];
+            const body = callArgs[1].body;
+            // Scopes should be merged and sorted alphabetically
+            expect(body.get("scope")).toBe("credentials external");
+        });
+        it("should always include external scope with requiredScopes", async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({
+                    access_token: "required-scope-token",
+                    expires_in: 3600,
+                }),
+            });
+            await auth.resolveAuthToken({
+                credentials: {
+                    type: "client_credentials",
+                    clientId: "required-scope-client",
+                    clientSecret: "secret",
+                },
+                requiredScopes: ["credentials"],
+                fetch: mockFetch,
+            });
+            const callArgs = mockFetch.mock.calls[0];
+            const body = callArgs[1].body;
+            // Should include both external (always present) and credentials (required)
+            expect(body.get("scope")).toBe("credentials external");
+        });
+        it("should cache tokens separately for different scope combinations", async () => {
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({
+                    access_token: "first-scope-token",
+                    expires_in: 3600,
+                }),
+            });
+            // First call with no requiredScopes
+            const result1 = await auth.resolveAuthToken({
+                credentials: {
+                    type: "client_credentials",
+                    clientId: "scope-cache-client",
+                    clientSecret: "secret",
+                },
+                fetch: mockFetch,
+            });
+            expect(result1).toBe("first-scope-token");
+            expect(mockFetch).toHaveBeenCalledTimes(1);
+            // Second call with different requiredScopes - should NOT use cache
+            mockFetch.mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({
+                    access_token: "second-scope-token",
+                    expires_in: 3600,
+                }),
+            });
+            const result2 = await auth.resolveAuthToken({
+                credentials: {
+                    type: "client_credentials",
+                    clientId: "scope-cache-client",
+                    clientSecret: "secret",
+                },
+                requiredScopes: ["credentials"],
+                fetch: mockFetch,
+            });
+            expect(result2).toBe("second-scope-token");
+            expect(mockFetch).toHaveBeenCalledTimes(2); // Should have made a new request
+            // Third call with same requiredScopes as second - should use cache
+            const result3 = await auth.resolveAuthToken({
+                credentials: {
+                    type: "client_credentials",
+                    clientId: "scope-cache-client",
+                    clientSecret: "secret",
+                },
+                requiredScopes: ["credentials"],
+                fetch: mockFetch,
+            });
+            expect(result3).toBe("second-scope-token");
+            expect(mockFetch).toHaveBeenCalledTimes(2); // No new request
+        });
     });
     describe("PKCE credentials", () => {
         it("should delegate PKCE credentials to CLI login", async () => {
@@ -260,8 +356,8 @@ describe("auth", () => {
                 fetch: mockFetch,
             });
             expect(mockFetch).toHaveBeenCalledTimes(1);
-            // Invalidate the cache
-            auth.invalidateCachedToken("invalidate-test");
+            // Invalidate the cache (default scope is "external")
+            auth.invalidateCachedToken("invalidate-test", ["external"]);
             // Next call should fetch again
             mockFetch.mockResolvedValue({
                 ok: true,