@zapier/zapier-sdk 0.45.2 → 0.46.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @zapier/zapier-sdk
 
+## 0.46.1
+
+### Patch Changes
+
+- 591ddb5: Removed custom error handlers and added definePlugin, createPluginMethod, and createPaginatedPluginMethod to reduce plugin boilerplate.
+
+## 0.46.0
+
+### Minor Changes
+
+- bd887ab: Rename the client credentials persistence seam from storage to cache and expose the CLI filesystem/keychain adapter as a best-effort cache.
+
 ## 0.45.2
 
 ### Patch 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;AAihCjB,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;AAqiCjB,eAAO,MAAM,eAAe,GAAI,SAAS,gBAAgB,KAAG,SAW3D,CAAC"}

package/dist/api/client.js

@@ -11,7 +11,7 @@ import { resolveAuthToken, invalidateCredentialsToken, isCliLoginAvailable, } fr
 import { getZapierBaseUrl } from "../utils/url-utils";
 import { sleep, calculateExponentialBackoffMs } from "../utils/retry-utils";
 import { isPlainObject } from "../utils/type-guard-utils";
-import { ZapierApiError, ZapierApprovalError, ZapierAuthenticationError, ZapierTimeoutError, ZapierValidationError, ZapierNotFoundError, ZapierRateLimitError, } from "../types/errors";
+import { ZapierApiError, ZapierApprovalError, ZapierAuthenticationError, ZapierTimeoutError, ZapierValidationError, ZapierResourceNotFoundError, ZapierRateLimitError, } from "../types/errors";
 import { ZAPIER_MAX_NETWORK_RETRIES, ZAPIER_MAX_NETWORK_RETRY_DELAY_MS, getZapierIsInteractive, getZapierApprovalMode, getZapierSdkService, DEFAULT_APPROVAL_TIMEOUT_MS, DEFAULT_MAX_APPROVAL_RETRIES, } from "../constants";
 import { SDK_VERSION } from "../sdk-version";
 import { openApproval } from "../utils/open-approval";
@@ -331,11 +331,12 @@ class ZapierApiClient {
             baseUrl: this.options.baseUrl,
             requiredScopes: options?.requiredScopes,
             debug: this.options.debug,
+            cache: this.options.cache,
         });
     }
     // Helper to handle responses
     async handleResponse(params) {
-        const { response, customErrorHandler, wasMissingAuthToken, requiredScopes, } = params;
+        const { response, customErrorHandler, resource, wasMissingAuthToken, requiredScopes, } = params;
         const { data: responseData } = await this.parseResult(response);
         if (response.ok) {
             return responseData;
@@ -345,7 +346,9 @@ class ZapierApiClient {
             statusText: response.statusText,
             data: responseData,
         };
-        // Check for custom error handling first
+        // Precedence: customErrorHandler runs first; if it returns an Error,
+        // throw it. If it returns undefined (or wasn't provided), fall through
+        // to the resource-enriched / bare defaults below.
         if (customErrorHandler) {
             const customError = customErrorHandler(errorInfo);
             if (customError) {
@@ -364,21 +367,35 @@ class ZapierApiClient {
             statusCode: response.status,
             errors,
         };
-        // Use appropriate error type based on status code
+        // 404: always throw ZapierResourceNotFoundError (subclass of
+        // ZapierNotFoundError, so existing instanceof checks still pass).
+        // resourceType/resourceId are populated when the caller passed a
+        // `resource` hint, otherwise left undefined. The message is the
+        // server's detail verbatim; formatErrorMessage surfaces the resource
+        // hint separately (Type: ..., ID: ...) so we don't duplicate it here.
         if (response.status === 404) {
-            throw new ZapierNotFoundError(message, errorOptions);
+            throw new ZapierResourceNotFoundError(message, {
+                ...errorOptions,
+                resourceType: resource?.type,
+                resourceId: resource?.id !== undefined ? String(resource.id) : undefined,
+            });
         }
         if (response.status === 401 || response.status === 403) {
             // If we get a 401/403 error and no auth token was provided, give helpful message
             if (wasMissingAuthToken) {
                 throw new ZapierAuthenticationError(`Authentication required (HTTP ${response.status}). Please provide credentials in options or set ZAPIER_CREDENTIALS environment variable.`, errorOptions);
             }
-            // On 401, invalidate cached token so next request gets a fresh one
+            // On 401, invalidate the cached token so the next request fires
+            // a fresh exchange. Passing baseUrl + cache explicitly so the
+            // invalidation targets the same cache key the token was stored
+            // under (both are part of the key identity).
             if (response.status === 401) {
                 await invalidateCredentialsToken({
                     credentials: this.options.credentials,
                     token: this.options.token,
+                    baseUrl: this.options.baseUrl,
                     requiredScopes,
+                    cache: this.options.cache,
                 });
             }
             throw new ZapierAuthenticationError(message, errorOptions);
@@ -400,7 +417,6 @@ class ZapierApiClient {
         const data = dataArray[0];
         return (typeof data === "object" &&
             data !== null &&
-            "message" in data &&
             "code" in data &&
             "title" in data &&
             "detail" in data);
@@ -611,6 +627,7 @@ class ZapierApiClient {
         const result = await this.handleResponse({
             response,
             customErrorHandler: options.customErrorHandler,
+            resource: options.resource,
             wasMissingAuthToken,
             requiredScopes: options.requiredScopes,
         });

package/dist/api/schemas.d.ts

@@ -43,8 +43,8 @@ export declare const NeedSchema: z.ZodObject<{
         string: "string";
         boolean: "boolean";
         file: "file";
-        integer: "integer";
         filter: "filter";
+        integer: "integer";
         text: "text";
         datetime: "datetime";
         decimal: "decimal";
@@ -65,11 +65,11 @@ export declare const ActionPermissionsSchema: z.ZodObject<{
 export declare const ActionSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     type: z.ZodEnum<{
-        search: "search";
         filter: "filter";
         read: "read";
         read_bulk: "read_bulk";
         run: "run";
+        search: "search";
         search_and_write: "search_and_write";
         search_or_write: "search_or_write";
         write: "write";
@@ -288,8 +288,8 @@ export declare const NeedsResponseSchema: z.ZodObject<{
             string: "string";
             boolean: "boolean";
             file: "file";
-            integer: "integer";
             filter: "filter";
+            integer: "integer";
             text: "text";
             datetime: "datetime";
             decimal: "decimal";
@@ -313,11 +313,11 @@ export declare const ImplementationSchema: z.ZodObject<{
     actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;
         type: z.ZodEnum<{
-            search: "search";
             filter: "filter";
             read: "read";
             read_bulk: "read_bulk";
             run: "run";
+            search: "search";
             search_and_write: "search_and_write";
             search_or_write: "search_or_write";
             write: "write";
@@ -355,11 +355,11 @@ export declare const ImplementationsResponseSchema: z.ZodObject<{
         actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodOptional<z.ZodString>;
             type: z.ZodEnum<{
-                search: "search";
                 filter: "filter";
                 read: "read";
                 read_bulk: "read_bulk";
                 run: "run";
+                search: "search";
                 search_and_write: "search_and_write";
                 search_or_write: "search_or_write";
                 write: "write";

package/dist/api/types.d.ts

@@ -13,6 +13,7 @@ import type { ImplementationMetaSchema, ImplementationsMetaResponseSchema } from
 import type { SdkEvent } from "../types/events";
 import type { Credentials } from "../types/credentials";
 import type { RequestContext } from "@zapier/policy-context";
+import type { ZapierCache } from "../cache";
 import type { z } from "zod";
 import type { NeedChoicesSchema, NeedSchema, ActionLinksSchema, ActionPermissionsSchema, ActionSchema, ChoiceSchema, FieldSchema, ActionExecutionResultSchema, ActionFieldChoiceSchema, ActionFieldSchema, UserProfileSchema, AppSchema, NeedsRequestSchema, NeedsResponseSchema, ImplementationSchema, ImplementationsResponseSchema, ServiceSchema, ServicesResponseSchema, NeedChoicesRequestSchema, NeedChoicesResponseSchema, NeedChoicesResponseMetaSchema, NeedChoicesResponseLinksSchema } from "./schemas";
 export interface ApiClientOptions {
@@ -71,6 +72,11 @@ export interface ApiClientOptions {
         name: string;
         version: string;
     };
+    /**
+     * Pluggable key-value cache used to cache access tokens across
+     * invocations. See ZapierCache in ../cache.ts.
+     */
+    cache?: ZapierCache;
 }
 export interface ApiClient {
     get: <T = unknown>(path: string, options?: RequestOptions) => Promise<T>;
@@ -100,6 +106,17 @@ export interface RequestOptions {
         statusText: string;
         data: unknown;
     }) => Error | undefined;
+    /**
+     * Optional metadata about what this request is fetching/affecting. When
+     * set, 404 responses throw `ZapierResourceNotFoundError` with
+     * `resourceType` / `resourceId` populated. The `type` is free-form;
+     * conventionally it matches how the resource appears in API URL segments
+     * (`"table"`, `"record"`, `"connection"`, etc.).
+     */
+    resource?: {
+        type: string;
+        id?: string | number;
+    };
     /**
      * Builds the policy context for this request if it triggers the approval
      * flow. Callers that may receive a 403 `approval_required` response MUST

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

@@ -6,10 +6,13 @@
  * and handles different credential types appropriately.
  *
  * CLI-specific functionality like login/logout is handled by the
- * @zapier/zapier-sdk-cli-login package.
+ * @zapier/zapier-sdk-cli package (imported via its `./login` subpath).
  */
 import type { EventCallback } from "./types/events";
 import type { Credentials } from "./types/credentials";
+import { type ZapierCache } from "./cache";
+export type { ZapierCache, ZapierCacheEntry, ZapierCacheSetOptions, } from "./cache";
+export { createMemoryCache } from "./cache";
 export type { SdkEvent, AuthEvent, ApiEvent, LoadingEvent, EventCallback, } from "./types/events";
 export type { Credentials, ResolvedCredentials, CredentialsObject, ClientCredentialsObject, PkceCredentialsObject, } from "./types/credentials";
 export { isClientCredentials, isPkceCredentials, isCredentialsObject, isCredentialsFunction, } from "./types/credentials";
@@ -31,16 +34,32 @@ export interface ResolveAuthTokenOptions {
     requiredScopes?: string[];
     /** Enable debug logging for auth operations. */
     debug?: boolean;
+    /**
+     * Pluggable key-value cache used to cache access tokens across
+     * process boundaries. When omitted, the SDK tries to load a default
+     * adapter from the cli-login package (file system + keychain) and
+     * falls back to in-memory cache if none is available.
+     */
+    cache?: ZapierCache;
 }
 /**
- * Clear the token cache. Useful for testing or forcing re-authentication.
+ * Clear in-process caches. Useful for testing or to force the next
+ * resolve to re-import the default cache adapter. Does not touch
+ * persistent cache — use `invalidateCachedToken` for that.
  */
 export declare function clearTokenCache(): void;
 /**
- * Invalidate a cached token for a specific clientId and scope combination.
- * Called when we get a 401 response.
+ * Invalidate the cached token for a given client_credentials identity.
+ * Called on 401 so the next request re-exchanges. Clears both the
+ * in-process pending-exchange map and the persistent layer via the
+ * resolved cache adapter.
  */
-export declare function invalidateCachedToken(clientId: string, scopes: string[]): void;
+export declare function invalidateCachedToken(options: {
+    clientId: string;
+    scopes: string[];
+    baseUrl: string;
+    cache?: ZapierCache;
+}): Promise<void>;
 /**
  * Options for getTokenFromCliLogin.
  */
@@ -55,7 +74,7 @@ interface CliLoginOptions {
     };
     debug?: boolean;
 }
-type CliLoginModule = typeof import("@zapier/zapier-sdk-cli-login");
+type CliLoginModule = typeof import("@zapier/zapier-sdk-cli/login");
 /**
  * Inject an already-loaded CLI login module so the SDK skips its dynamic import.
  * This guarantees CLI and SDK share the same module instance in the same process.
@@ -97,6 +116,8 @@ export declare function resolveAuthToken(options?: ResolveAuthTokenOptions): Pro
 export declare function invalidateCredentialsToken(options: {
     credentials?: Credentials;
     token?: string;
+    baseUrl?: string;
     requiredScopes?: string[];
+    cache?: ZapierCache;
 }): 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;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,CAItC;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;AAGD,KAAK,cAAc,GAAG,cAAc,8BAA8B,CAAC,CAAC;AA2CpE;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAE3D;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,GAAG,SAAS,CAGzD;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAK7B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB7B;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"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/auth.js

@@ -6,80 +6,100 @@
  * and handles different credential types appropriately.
  *
  * CLI-specific functionality like login/logout is handled by the
- * @zapier/zapier-sdk-cli-login package.
+ * @zapier/zapier-sdk-cli package (imported via its `./login` subpath).
  */
 import { isClientCredentials, isPkceCredentials } from "./types/credentials";
 import { resolveCredentials, getClientIdFromCredentials } from "./credentials";
-import { ZAPIER_BASE_URL } from "./constants";
+import { createMemoryCache } from "./cache";
+const DEFAULT_AUTH_BASE_URL = "https://zapier.com";
+export { createMemoryCache } from "./cache";
 export { isClientCredentials, isPkceCredentials, isCredentialsObject, isCredentialsFunction, } from "./types/credentials";
 /**
- * In-memory cache for tokens obtained via client credentials flow.
- * Keyed by clientId + sorted scopes.
+ * In-flight token exchange promises to prevent duplicate exchanges
+ * inside the same process. When an exchange is in progress, subsequent
+ * calls await the same promise. Cache backends are responsible for
+ * cross-process dedup via their optional `withLock` method.
  */
-const tokenCache = new Map();
+const pendingExchanges = 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.
+ * The resolved default cache adapter. Cached at module scope so
+ * repeated calls to `resolveAuthToken` reuse the same provider.
  */
-const pendingExchanges = new Map();
+let cachedDefaultCache;
 /**
- * Build a cache key from clientId and scopes.
+ * Build the cache key for a client_credentials identity. baseUrl is
+ * part of the key so the same clientId+scopes against different auth
+ * hosts (prod vs staging) never alias.
  */
-function buildCacheKey(clientId, scopes) {
-    const sortedScopes = [...scopes].sort().join(",");
-    return `${clientId}:${sortedScopes}`;
+function buildCacheKey(options) {
+    const sortedScopes = [...options.scopes].sort().join(",");
+    return `zapier-sdk/client-credentials/${options.clientId}:${sortedScopes}:${options.baseUrl}`;
 }
 /**
- * Clear the token cache. Useful for testing or forcing re-authentication.
+ * Clear in-process caches. Useful for testing or to force the next
+ * resolve to re-import the default cache adapter. Does not touch
+ * persistent cache — use `invalidateCachedToken` for that.
  */
 export function clearTokenCache() {
-    tokenCache.clear();
     pendingExchanges.clear();
     cachedCliLogin = undefined;
+    cachedDefaultCache = undefined;
 }
-const TOKEN_EXPIRATION_BUFFER = 5 * 60 * 1000; // 5 minutes
+const TOKEN_EXPIRATION_BUFFER_MS = 5 * 60 * 1000;
 /**
- * Get a cached token if it exists and is not expired.
- * Returns undefined if no valid cached token exists.
+ * Decide which cache adapter to use for this call. Priority:
+ *   1. explicit `options.cache`
+ *   2. CLI's default cache provider (if installed)
+ *   3. in-memory fallback
  */
-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)
-    if (cached.expiresAt > Date.now() + TOKEN_EXPIRATION_BUFFER) {
-        return cached.accessToken;
+async function resolveCache(options) {
+    if (options.cache)
+        return options.cache;
+    if (cachedDefaultCache !== undefined)
+        return cachedDefaultCache;
+    const cliLogin = await getCliLogin();
+    if (cliLogin?.createCache) {
+        try {
+            const cache = cliLogin.createCache();
+            cachedDefaultCache = cache;
+            return cache;
+        }
+        catch {
+            // Fall through to in-memory if the CLI provider can't be constructed.
+        }
     }
-    // Token expired, remove from cache
-    tokenCache.delete(cacheKey);
-    return undefined;
+    const fallback = createMemoryCache();
+    cachedDefaultCache = fallback;
+    return fallback;
 }
-/**
- * Cache a token obtained from client credentials flow.
- */
-function cacheToken(clientId, scopes, accessToken, expiresIn) {
-    const cacheKey = buildCacheKey(clientId, scopes);
-    tokenCache.set(cacheKey, {
-        accessToken,
-        expiresAt: Date.now() + expiresIn * 1000,
-    });
+function entryIsValid(entry) {
+    if (entry.expiresAt === undefined)
+        return true;
+    return entry.expiresAt > Date.now() + TOKEN_EXPIRATION_BUFFER_MS;
 }
 /**
- * Invalidate a cached token for a specific clientId and scope combination.
- * Called when we get a 401 response.
+ * Invalidate the cached token for a given client_credentials identity.
+ * Called on 401 so the next request re-exchanges. Clears both the
+ * in-process pending-exchange map and the persistent layer via the
+ * resolved cache adapter.
  */
-export function invalidateCachedToken(clientId, scopes) {
-    const cacheKey = buildCacheKey(clientId, scopes);
-    tokenCache.delete(cacheKey);
+export async function invalidateCachedToken(options) {
+    const cacheKey = buildCacheKey(options);
     pendingExchanges.delete(cacheKey);
+    const cache = await resolveCache({ cache: options.cache });
+    try {
+        await cache.delete(cacheKey);
+    }
+    catch {
+        // Best-effort: the caller is about to surface a 401 to its own
+        // caller; a failed invalidation shouldn't add noise on top of that.
+    }
 }
 /**
  * Get the token endpoint URL for client credentials exchange.
  */
 function getTokenEndpointUrl(baseUrl) {
-    const base = baseUrl || ZAPIER_BASE_URL;
+    const base = baseUrl || DEFAULT_AUTH_BASE_URL;
     return `${base}/oauth/token/`;
 }
 /**
@@ -109,9 +129,6 @@ function mergeScopes(credentialsScope, requiredScopes) {
     }
     return [...scopeSet].sort();
 }
-/**
- * Exchange client credentials for an access token.
- */
 async function exchangeClientCredentials(options) {
     const { clientId, clientSecret, baseUrl, scope, requiredScopes, onEvent } = options;
     const fetchFn = options.fetch || globalThis.fetch;
@@ -157,9 +174,6 @@ async function exchangeClientCredentials(options) {
     if (!data.access_token) {
         throw new Error("Client credentials response missing access_token");
     }
-    // Cache the token with the scopes used
-    const expiresIn = data.expires_in || 3600; // Default to 1 hour
-    cacheToken(clientId, mergedScopes, data.access_token, expiresIn);
     onEvent?.({
         type: "auth_success",
         payload: {
@@ -168,18 +182,17 @@ async function exchangeClientCredentials(options) {
         },
         timestamp: Date.now(),
     });
-    return data.access_token;
+    return {
+        accessToken: data.access_token,
+        expiresIn: data.expires_in || 3600,
+    };
 }
 let cachedCliLogin;
 /**
- * Dynamically imports a CLI login package with caching.
- *
- * Tries `@zapier/zapier-sdk-cli/login` first (available when the CLI is a
- * direct dependency), then falls back to `@zapier/zapier-sdk-cli-login` (for
- * users who install the lightweight login package directly).
- *
- * Returns the module if found, or `undefined` if neither package is available.
- * The result is cached after the first attempt.
+ * Dynamically imports the CLI's login/cache entrypoint with caching.
+ * Returns the module if the CLI package is installed in the consumer's
+ * environment, or `undefined` if not (e.g. in a browser or minimal
+ * server deployment). The result is cached after the first attempt.
  */
 async function getCliLogin() {
     if (cachedCliLogin !== undefined) {
@@ -193,17 +206,7 @@ async function getCliLogin() {
         }
     }
     catch {
-        // Not available, try fallback
-    }
-    try {
-        const mod = await import("@zapier/zapier-sdk-cli-login");
-        if (typeof mod.getToken === "function") {
-            cachedCliLogin = mod;
-            return cachedCliLogin;
-        }
-    }
-    catch {
-        // Not available
+        // Not available (no CLI installed in this environment).
     }
     cachedCliLogin = false;
     return undefined;
@@ -277,33 +280,62 @@ async function resolveAuthTokenFromCredentials(credentials, options) {
     if (typeof credentials === "string") {
         return credentials;
     }
-    // Client credentials: exchange for token
+    // Client credentials: exchange + cache through a pluggable cache
+    // adapter. Resolution order:
+    //   1. in-process pending exchange (dedup concurrent same-process calls)
+    //   2. cache.get (hits keychain + config under the filesystem adapter,
+    //      RAM under the in-memory adapter, whatever the user adapter does)
+    //   3. cache.withLock (if available) -> re-read, exchange, persist
+    //      (so N parallel processes collapse to 1 network exchange)
+    //   4. plain exchange + persist when no lock is available
     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, mergedScopes);
-        if (cached) {
-            return cached;
+        const resolvedBaseUrl = credentials.baseUrl || options.baseUrl || DEFAULT_AUTH_BASE_URL;
+        const cacheKey = buildCacheKey({
+            clientId,
+            scopes: mergedScopes,
+            baseUrl: resolvedBaseUrl,
+        });
+        const cache = await resolveCache(options);
+        // Fast-path read
+        const cached = await cache.get(cacheKey);
+        if (cached && entryIsValid(cached)) {
+            return cached.value;
         }
-        // Check if there's already an exchange in progress for this clientId + scopes
+        // In-process dedup
         const pending = pendingExchanges.get(cacheKey);
-        if (pending) {
+        if (pending)
             return pending;
-        }
-        // Start new exchange and cache the promise to prevent duplicate exchanges
-        const exchangePromise = exchangeClientCredentials({
-            clientId: credentials.clientId,
-            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)
+        // Serialize exchange + persist inside the lock (when the adapter
+        // supports cross-process locking). The second acquirer re-reads the
+        // cache under the lock and uses the first's token instead of firing
+        // another exchange.
+        const runLocked = async () => {
+            const recheck = await cache.get(cacheKey);
+            if (recheck && entryIsValid(recheck))
+                return recheck.value;
+            const { accessToken, expiresIn } = await exchangeClientCredentials({
+                clientId: credentials.clientId,
+                clientSecret: credentials.clientSecret,
+                baseUrl: credentials.baseUrl || options.baseUrl,
+                scope: credentials.scope,
+                requiredScopes: options.requiredScopes,
+                fetch: options.fetch,
+                onEvent: options.onEvent,
+            });
+            try {
+                await cache.set(cacheKey, accessToken, {
+                    secret: true,
+                    ttl: expiresIn,
+                });
+            }
+            catch {
+                // Best-effort persistence: next process will re-exchange.
+            }
+            return accessToken;
+        };
+        const exchangePromise = (cache.withLock ? cache.withLock(cacheKey, runLocked) : runLocked()).finally(() => {
             pendingExchanges.delete(cacheKey);
         });
         pendingExchanges.set(cacheKey, exchangePromise);
@@ -340,6 +372,12 @@ export async function invalidateCredentialsToken(options) {
     const clientId = getClientIdFromCredentials(resolved);
     if (clientId && isClientCredentials(resolved)) {
         const scopes = mergeScopes(resolved.scope, options.requiredScopes);
-        invalidateCachedToken(clientId, scopes);
+        const baseUrl = resolved.baseUrl || options.baseUrl || DEFAULT_AUTH_BASE_URL;
+        await invalidateCachedToken({
+            clientId,
+            scopes,
+            baseUrl,
+            cache: options.cache,
+        });
     }
 }