@zapier/zapier-sdk 0.18.3 → 1.0.0

package/dist/auth.d.ts

@@ -2,51 +2,79 @@
  * SDK Authentication Utilities
  *
  * This module provides SDK-level authentication utilities focused
- * solely on token acquisition. CLI-specific functionality like login/logout
- * is handled by the @zapier/zapier-sdk-cli-login package.
+ * on token acquisition. It uses the credentials system for resolution
+ * and handles different credential types appropriately.
+ *
+ * CLI-specific functionality like login/logout is handled by the
+ * @zapier/zapier-sdk-cli-login package.
  */
 import type { EventCallback } from "./types/events";
+import type { Credentials } from "./types/credentials";
 export type { SdkEvent, AuthEvent, ApiEvent, LoadingEvent, EventCallback, } from "./types/events";
-export interface AuthOptions {
+export type { Credentials, ResolvedCredentials, CredentialsObject, ClientCredentialsObject, PkceCredentialsObject, } from "./types/credentials";
+export { isClientCredentials, isPkceCredentials, isCredentialsObject, isCredentialsFunction, } from "./types/credentials";
+/**
+ * Options for resolving auth tokens.
+ */
+export interface ResolveAuthTokenOptions {
+    credentials?: Credentials;
+    /** @deprecated Use `credentials` instead */
+    token?: string;
     onEvent?: EventCallback;
     fetch?: typeof globalThis.fetch;
     baseUrl?: string;
-    authBaseUrl?: string;
-    authClientId?: string;
-}
-export interface ResolveAuthTokenOptions extends AuthOptions {
-    token?: string;
-    getToken?: () => Promise<string | undefined> | string | undefined;
 }
 /**
- * Gets the ZAPIER_TOKEN from environment variables.
- * Returns undefined if not set.
+ * 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.
+ */
+export declare function invalidateCachedToken(clientId: string): void;
+/**
+ * Options for getTokenFromCliLogin.
  */
-export declare function getTokenFromEnv(): string | undefined;
+interface CliLoginOptions {
+    onEvent?: EventCallback;
+    fetch?: typeof globalThis.fetch;
+    credentials?: {
+        type?: "pkce";
+        clientId: string;
+        baseUrl?: string;
+        scope?: string;
+    };
+}
 /**
  * Attempts to get a token by optionally importing from CLI login package.
  * This provides a graceful fallback when the CLI login package is not available.
  *
  * Returns undefined if no valid token is found or CLI package is not available.
  */
-export declare function getTokenFromCliLogin(options?: AuthOptions): Promise<string | undefined>;
+export declare function getTokenFromCliLogin(options: CliLoginOptions): Promise<string | undefined>;
 /**
- * Attempts to get a token with the following precedence:
- * 1. ZAPIER_TOKEN environment variable
- * 2. CLI login package (if available) with auto-refresh
+ * Resolves an auth token from wherever it can be found.
  *
- * Returns undefined if no valid token is found.
- */
-export declare function getTokenFromEnvOrConfig(options?: AuthOptions): Promise<string | undefined>;
-/**
- * Resolves an auth token from all possible sources with the following precedence:
- * 1. Explicitly provided token in options
- * 2. Token from getToken callback in options
- * 3. ZAPIER_TOKEN environment variable
- * 4. CLI login package (if available)
+ * Resolution order:
+ * 1. Explicit credentials option (or deprecated token option)
+ * 2. Environment variables
+ * 3. CLI login package (if available)
+ *
+ * For different credential types:
+ * - String: Used directly as the token
+ * - Client credentials: Exchanged for an access token (with caching)
+ * - PKCE: Delegates to CLI login (throws if not available)
  *
- * This is the canonical token resolution logic used throughout the SDK.
  * Returns undefined if no valid token is found.
  */
 export declare function resolveAuthToken(options?: ResolveAuthTokenOptions): Promise<string | undefined>;
+/**
+ * Invalidate the cached token for the given credentials, if applicable.
+ * This is called when we receive a 401 response, indicating the token
+ * is no longer valid. Only affects client_credentials flow tokens.
+ */
+export declare function invalidateCredentialsToken(options: {
+    credentials?: Credentials;
+    token?: 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;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGpD,YAAY,EACV,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,aAAa,GACd,MAAM,gBAAgB,CAAC;AAGxB,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAwB,SAAQ,WAAW;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC;CACnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAEpD;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B;AAED;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAS7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAgB7B"}
+{"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;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAa7B;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"}

package/dist/auth.js

@@ -2,15 +2,129 @@
  * SDK Authentication Utilities
  *
  * This module provides SDK-level authentication utilities focused
- * solely on token acquisition. CLI-specific functionality like login/logout
- * is handled by the @zapier/zapier-sdk-cli-login package.
+ * on token acquisition. It uses the credentials system for resolution
+ * and handles different credential types appropriately.
+ *
+ * CLI-specific functionality like login/logout is handled by the
+ * @zapier/zapier-sdk-cli-login package.
+ */
+import { isClientCredentials, isPkceCredentials } from "./types/credentials";
+import { resolveCredentials, getClientIdFromCredentials } from "./credentials";
+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.
+ */
+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.
+ */
+const pendingExchanges = new Map();
+/**
+ * Clear the token cache. Useful for testing or forcing re-authentication.
+ */
+export function clearTokenCache() {
+    tokenCache.clear();
+    pendingExchanges.clear();
+}
+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);
+    if (!cached)
+        return undefined;
+    // Check if token is still valid (with expiration buffer)
+    if (cached.expiresAt > Date.now() + TOKEN_EXPIRATION_BUFFER) {
+        return cached.accessToken;
+    }
+    // Token expired, remove from cache
+    tokenCache.delete(clientId);
+    return undefined;
+}
+/**
+ * Cache a token obtained from client credentials flow.
+ */
+function cacheToken(clientId, accessToken, expiresIn) {
+    tokenCache.set(clientId, {
+        accessToken,
+        expiresAt: Date.now() + expiresIn * 1000,
+    });
+}
+/**
+ * Invalidate a cached token. Called when we get a 401 response.
+ */
+export function invalidateCachedToken(clientId) {
+    tokenCache.delete(clientId);
+}
 /**
- * Gets the ZAPIER_TOKEN from environment variables.
- * Returns undefined if not set.
+ * Get the token endpoint URL for client credentials exchange.
  */
-export function getTokenFromEnv() {
-    return process.env.ZAPIER_TOKEN;
+function getTokenEndpointUrl(baseUrl) {
+    const base = baseUrl || ZAPIER_BASE_URL;
+    return `${base}/oauth/token/`;
+}
+/**
+ * Exchange client credentials for an access token.
+ */
+async function exchangeClientCredentials(options) {
+    const { clientId, clientSecret, baseUrl, scope, onEvent } = options;
+    const fetchFn = options.fetch || globalThis.fetch;
+    const tokenUrl = getTokenEndpointUrl(baseUrl);
+    onEvent?.({
+        type: "auth_exchanging",
+        payload: {
+            message: "Exchanging client credentials for token...",
+            operation: "client_credentials",
+        },
+        timestamp: Date.now(),
+    });
+    const response = await fetchFn(tokenUrl, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: clientId,
+            client_secret: clientSecret,
+            scope: scope || "external",
+            audience: "zapier.com",
+        }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        onEvent?.({
+            type: "auth_error",
+            payload: {
+                message: `Client credentials exchange failed: ${response.status}`,
+                error: errorText,
+                operation: "client_credentials",
+            },
+            timestamp: Date.now(),
+        });
+        throw new Error(`Client credentials exchange failed: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (!data.access_token) {
+        throw new Error("Client credentials response missing access_token");
+    }
+    // Cache the token
+    const expiresIn = data.expires_in || 3600; // Default to 1 hour
+    cacheToken(clientId, data.access_token, expiresIn);
+    onEvent?.({
+        type: "auth_success",
+        payload: {
+            message: "Client credentials exchange successful",
+            operation: "client_credentials",
+        },
+        timestamp: Date.now(),
+    });
+    return data.access_token;
 }
 /**
  * Attempts to get a token by optionally importing from CLI login package.
@@ -18,11 +132,13 @@ export function getTokenFromEnv() {
  *
  * Returns undefined if no valid token is found or CLI package is not available.
  */
-export async function getTokenFromCliLogin(options = {}) {
+export async function getTokenFromCliLogin(options) {
     try {
-        // Dynamically import the CLI login package if available
-        const { getToken } = await import("@zapier/zapier-sdk-cli-login");
-        return await getToken(options);
+        // Dynamically import the CLI login package if available.
+        // This is intentionally an async import because this module is a dependency
+        // of the CLI and is only available when the CLI is installed!
+        const cliLogin = await import("@zapier/zapier-sdk-cli-login");
+        return await cliLogin.getToken(options);
     }
     catch {
         // CLI login package is not available, return undefined
@@ -30,43 +146,99 @@ export async function getTokenFromCliLogin(options = {}) {
     }
 }
 /**
- * Attempts to get a token with the following precedence:
- * 1. ZAPIER_TOKEN environment variable
- * 2. CLI login package (if available) with auto-refresh
+ * Resolves an auth token from wherever it can be found.
+ *
+ * Resolution order:
+ * 1. Explicit credentials option (or deprecated token option)
+ * 2. Environment variables
+ * 3. CLI login package (if available)
+ *
+ * For different credential types:
+ * - String: Used directly as the token
+ * - Client credentials: Exchanged for an access token (with caching)
+ * - PKCE: Delegates to CLI login (throws if not available)
  *
  * Returns undefined if no valid token is found.
  */
-export async function getTokenFromEnvOrConfig(options = {}) {
-    // First priority: environment variable
-    const envToken = getTokenFromEnv();
-    if (envToken) {
-        return envToken;
+export async function resolveAuthToken(options = {}) {
+    // Resolve credentials from options and env vars
+    const credentials = await resolveCredentials({
+        credentials: options.credentials,
+        token: options.token,
+    });
+    // If we got credentials, process them based on type
+    if (credentials !== undefined) {
+        return resolveAuthTokenFromCredentials(credentials, options);
     }
-    // Second priority: CLI login package (if available)
-    return getTokenFromCliLogin(options);
+    // No credentials from options or env, try CLI login for stored token
+    return getTokenFromCliLogin({
+        onEvent: options.onEvent,
+        fetch: options.fetch,
+    });
 }
 /**
- * Resolves an auth token from all possible sources with the following precedence:
- * 1. Explicitly provided token in options
- * 2. Token from getToken callback in options
- * 3. ZAPIER_TOKEN environment variable
- * 4. CLI login package (if available)
- *
- * This is the canonical token resolution logic used throughout the SDK.
- * Returns undefined if no valid token is found.
+ * Resolve an auth token from resolved credentials.
  */
-export async function resolveAuthToken(options = {}) {
-    // First priority: explicitly provided token
-    if (options.token) {
-        return options.token;
+async function resolveAuthTokenFromCredentials(credentials, options) {
+    // String credentials are used directly as tokens
+    if (typeof credentials === "string") {
+        return credentials;
+    }
+    // Client credentials: exchange for token
+    if (isClientCredentials(credentials)) {
+        const { clientId } = credentials;
+        // Check cache first
+        const cached = getCachedToken(clientId);
+        if (cached) {
+            return cached;
+        }
+        // Check if there's already an exchange in progress for this clientId
+        const pending = pendingExchanges.get(clientId);
+        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,
+            fetch: options.fetch,
+            onEvent: options.onEvent,
+        }).finally(() => {
+            // Remove from pending when done (success or failure)
+            pendingExchanges.delete(clientId);
+        });
+        pendingExchanges.set(clientId, exchangePromise);
+        return exchangePromise;
     }
-    // Second priority: getToken callback
-    if (options.getToken) {
-        const token = await options.getToken();
-        if (token) {
-            return token;
+    // PKCE credentials: delegate to CLI login
+    if (isPkceCredentials(credentials)) {
+        // Try to get stored token from CLI login
+        const storedToken = await getTokenFromCliLogin({
+            onEvent: options.onEvent,
+            fetch: options.fetch,
+            credentials,
+        });
+        if (storedToken) {
+            return storedToken;
         }
+        // No stored token - user needs to run login
+        throw new Error("PKCE credentials require interactive login. " +
+            "Please run the 'login' command with the CLI first, or use client_credentials flow.");
+    }
+    // Should not reach here, but handle gracefully
+    throw new Error("Unknown credentials type");
+}
+/**
+ * Invalidate the cached token for the given credentials, if applicable.
+ * This is called when we receive a 401 response, indicating the token
+ * is no longer valid. Only affects client_credentials flow tokens.
+ */
+export async function invalidateCredentialsToken(options) {
+    const resolved = await resolveCredentials(options);
+    const clientId = getClientIdFromCredentials(resolved);
+    if (clientId) {
+        invalidateCachedToken(clientId);
     }
-    // Third and fourth priorities: environment variable or CLI login
-    return getTokenFromEnvOrConfig(options);
 }