@logto/api 1.42.0 → 1.44.0-beta.0

package/README.md

@@ -33,8 +33,9 @@ const { apiClient } = createManagementApi('your-tenant-id', {
   clientSecret: 'your-client-secret',
 });
 
-// Make API calls
-const response = await apiClient.GET('/api/users');
+// Make API calls with lowercase or uppercase methods
+const response = await apiClient.get('/api/users');
+// const response = await apiClient.GET('/api/users');
 console.log(response.data);
 ```
 
@@ -51,6 +52,24 @@ const { apiClient } = createManagementApi('default', {
 });
 ```
 
+#### Timeouts
+
+Token fetches and Management API network requests have separate 10-second timeouts. The API request
+timeout starts after token retrieval, so a request that needs a new token can use both timeout
+periods. Use `tokenRequestTimeout` and `requestTimeout` to configure them in seconds. Set either option
+to `0` or a negative value to disable its timeout.
+
+Use `getTokenRequestSignal` to return a custom signal for each token request. The signal is composed
+with `tokenRequestTimeout`, and the first one to abort cancels the token request. A per-request
+`signal` is similarly composed with `requestTimeout` for the Management API request. Timeouts and
+custom cancellation reject the API call instead of returning a response object.
+
+#### Token refresh
+
+After a Management API request returns `401`, the next request fetches a new token. If the replacement
+token also receives a `401`, it remains cached until a request succeeds or the token expires. The SDK
+does not automatically retry the failed API request.
+
 #### Custom authentication
 
 For advanced use cases where you need full control over the authentication logic, use `createApiClient`:
@@ -67,7 +86,7 @@ const client = createApiClient({
 });
 
 // Type-safe API calls
-const response = await client.GET('/api/applications/{id}', {
+const response = await client.get('/api/applications/{id}', {
   params: { path: { id: 'your-app-id' } },
 });
 ```

package/lib/client-credentials.d.ts

@@ -6,7 +6,7 @@ export type AccessToken = {
     scope?: string;
 };
 export declare class ClientCredentialsError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 export type ClientCredentialsOptions = {
     clientId: string;
@@ -15,9 +15,23 @@ export type ClientCredentialsOptions = {
     tokenParams?: Record<string, string>;
     /**
      * The time in seconds before the access token expires to consider it valid.
+     * A value greater than or equal to the token lifetime causes every call to fetch a new token,
+     * so cached-token invalidation protection cannot persist across calls.
      * @default 60
      */
     accessTokenExpiryLeeway?: Seconds;
+    /**
+     * The maximum time in seconds allowed for fetching an access token.
+     * Non-positive and infinite values disable the timeout. `NaN` uses the default value.
+     * @default 10
+     */
+    tokenRequestTimeout?: Seconds;
+    /**
+     * Returns an optional signal for each token request. The factory is called once per actual token
+     * fetch, so concurrent callers sharing a fetch also share its signal. The signal is composed with
+     * `tokenRequestTimeout`, and the first signal to abort cancels the request.
+     */
+    getTokenRequestSignal?: () => AbortSignal | undefined;
 };
 /**
  * A class handles client credentials for API authentication. It caches the access token
@@ -26,12 +40,25 @@ export type ClientCredentialsOptions = {
 export declare class ClientCredentials {
     protected options: ClientCredentialsOptions;
     protected accessToken?: AccessToken;
+    private accessTokenPromise?;
+    private awaitingValidationAfterRefresh;
     get accessTokenExpiryLeeway(): Seconds;
+    get tokenRequestTimeout(): Seconds;
     constructor(options: ClientCredentialsOptions);
     /**
      * Retrieves the access token, refreshing it if necessary.
-     * @returns The access token as a string.
+     * Concurrent calls share the same token request.
+     * @returns The access token and its metadata.
      */
     getAccessToken(): Promise<AccessToken>;
+    /**
+     * Invalidates the cached token if it matches the token rejected by the API.
+     * A delayed response for an older token must not invalidate a newer cached token.
+     */
+    invalidateAccessToken(token: string): void;
+    /** Allows a future 401 to invalidate the token after it receives a successful API response. */
+    markAccessTokenAsValid(token: string): void;
+    private fetchAccessToken;
+    private requestAccessToken;
 }
 export {};

package/lib/client-credentials.js

@@ -1,9 +1,29 @@
+import { createTimeoutSignal, getAbortReason, normalizeTimeout } from './timeout.js';
 export class ClientCredentialsError extends Error {
-    constructor(message) {
-        super(message);
+    constructor(message, options) {
+        super(message, options);
         this.name = 'ClientCredentialsError';
     }
 }
+const createAbortPromise = (signal) => {
+    // eslint-disable-next-line no-use-extend-native/no-use-extend-native -- `Promise.withResolvers` is standard since ES2024; the rule's built-in method list predates it.
+    const { promise, reject } = Promise.withResolvers();
+    const handleAbort = () => {
+        reject(getAbortReason(signal, 'Token request aborted'));
+    };
+    if (signal.aborted) {
+        handleAbort();
+    }
+    else {
+        signal.addEventListener('abort', handleAbort, { once: true });
+    }
+    return {
+        promise,
+        clear: () => {
+            signal.removeEventListener('abort', handleAbort);
+        },
+    };
+};
 /**
  * A class handles client credentials for API authentication. It caches the access token
  * and provides methods to retrieve it, ensuring the token is valid and refreshing it when necessary.
@@ -12,46 +32,113 @@ export class ClientCredentials {
     get accessTokenExpiryLeeway() {
         return this.options.accessTokenExpiryLeeway ?? 60;
     }
+    get tokenRequestTimeout() {
+        return normalizeTimeout(this.options.tokenRequestTimeout);
+    }
     constructor(options) {
         this.options = options;
+        this.awaitingValidationAfterRefresh = false;
     }
     /**
      * Retrieves the access token, refreshing it if necessary.
-     * @returns The access token as a string.
+     * Concurrent calls share the same token request.
+     * @returns The access token and its metadata.
      */
     async getAccessToken() {
         const now = new Date();
-        // If the access token is not set or has expired, refresh it
-        if (!this.accessToken?.expiresAt ||
-            this.accessToken.expiresAt <= Math.floor(now.getTime() / 1000) + this.accessTokenExpiryLeeway) {
-            const response = await fetch(this.options.tokenEndpoint, {
-                method: 'POST',
-                headers: {
-                    'Content-Type': 'application/x-www-form-urlencoded',
-                },
-                body: new URLSearchParams({
-                    grant_type: 'client_credentials',
-                    client_id: this.options.clientId,
-                    client_secret: this.options.clientSecret,
-                    ...this.options.tokenParams,
-                }).toString(),
-            });
-            if (!response.ok) {
-                throw new ClientCredentialsError(`Failed to fetch access token: ${response.status} ${response.statusText}`);
+        // Return the cached token if it is still valid.
+        if (this.accessToken?.expiresAt &&
+            this.accessToken.expiresAt > Math.floor(now.getTime() / 1000) + this.accessTokenExpiryLeeway) {
+            return this.accessToken;
+        }
+        if (this.accessToken) {
+            // A natural expiry starts a new invalidation cycle.
+            this.awaitingValidationAfterRefresh = false;
+        }
+        if (this.accessTokenPromise) {
+            return this.accessTokenPromise;
+        }
+        try {
+            this.accessTokenPromise = this.fetchAccessToken();
+            this.accessToken = await this.accessTokenPromise;
+            return this.accessToken;
+        }
+        finally {
+            this.accessTokenPromise = undefined;
+        }
+    }
+    /**
+     * Invalidates the cached token if it matches the token rejected by the API.
+     * A delayed response for an older token must not invalidate a newer cached token.
+     */
+    invalidateAccessToken(token) {
+        if (this.accessToken?.value === token && !this.awaitingValidationAfterRefresh) {
+            this.accessToken = undefined;
+            this.awaitingValidationAfterRefresh = true;
+        }
+    }
+    /** Allows a future 401 to invalidate the token after it receives a successful API response. */
+    markAccessTokenAsValid(token) {
+        if (this.accessToken?.value === token) {
+            this.awaitingValidationAfterRefresh = false;
+        }
+    }
+    async fetchAccessToken() {
+        const timeout = createTimeoutSignal(this.tokenRequestTimeout, 'Token request timed out');
+        try {
+            const customSignal = this.options.getTokenRequestSignal?.();
+            const signal = customSignal
+                ? AbortSignal.any([timeout.signal, customSignal])
+                : timeout.signal;
+            const abort = createAbortPromise(signal);
+            try {
+                // Guard against Response implementations that do not propagate request aborts to json().
+                return await Promise.race([this.requestAccessToken(signal), abort.promise]);
             }
-            const data = await response.json();
-            if (typeof data !== 'object' || data === null || !('access_token' in data)) {
-                throw new ClientCredentialsError('Invalid response from token endpoint');
+            finally {
+                abort.clear();
             }
-            if (!('expires_in' in data) || typeof data.expires_in !== 'number') {
-                throw new ClientCredentialsError('Invalid or missing expires_in in token response');
+        }
+        catch (error) {
+            if (error instanceof ClientCredentialsError) {
+                throw error;
             }
-            this.accessToken = {
-                value: String(data.access_token),
-                expiresAt: Math.floor(now.getTime() / 1000) + data.expires_in,
-                scope: 'scope' in data && typeof data.scope === 'string' ? data.scope : undefined,
-            };
+            throw new ClientCredentialsError(`Failed to fetch access token: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        finally {
+            timeout.clear();
+        }
+    }
+    async requestAccessToken(signal) {
+        const now = new Date();
+        const response = await fetch(this.options.tokenEndpoint, {
+            method: 'POST',
+            redirect: 'error',
+            signal,
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+                grant_type: 'client_credentials',
+                client_id: this.options.clientId,
+                client_secret: this.options.clientSecret,
+                ...this.options.tokenParams,
+            }).toString(),
+        });
+        if (!response.ok) {
+            throw new ClientCredentialsError(`Failed to fetch access token: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        if (typeof data !== 'object' || data === null || !('access_token' in data)) {
+            throw new ClientCredentialsError('Invalid response from token endpoint');
+        }
+        if (!('expires_in' in data) || typeof data.expires_in !== 'number') {
+            throw new ClientCredentialsError('Invalid or missing expires_in in token response');
         }
-        return this.accessToken;
+        return {
+            value: String(data.access_token),
+            expiresAt: Math.floor(now.getTime() / 1000) + data.expires_in,
+            scope: 'scope' in data && typeof data.scope === 'string' ? data.scope : undefined,
+        };
     }
 }