@logto/api 1.43.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,
+        };
     }
 }

package/lib/management.d.ts

@@ -19,6 +19,7 @@ export type CreateManagementApiOptions = {
     /**
      * Override the base URL generated from the tenant ID.
      * Useful for testing or custom deployments.
+     * Trailing slashes are ignored.
      */
     baseUrl?: string;
     /**
@@ -26,6 +27,25 @@ export type CreateManagementApiOptions = {
      * Useful for testing or custom deployments.
      */
     apiIndicator?: string;
+    /**
+     * 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?: number;
+    /**
+     * 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;
+    /**
+     * The maximum time in seconds allowed for the Management API network request after token
+     * retrieval. It is composed with per-request signals, and a timeout rejects the API call.
+     * Non-positive and infinite values disable the timeout. `NaN` uses the default value.
+     * @default 10
+     */
+    requestTimeout?: number;
 };
 /**
  * Options for creating an API client with custom token authentication.
@@ -33,6 +53,7 @@ export type CreateManagementApiOptions = {
 export type CreateApiClientOptions = {
     /**
      * The base URL for the Management API.
+     * Trailing slashes are ignored.
      */
     baseUrl: string;
     /**
@@ -40,6 +61,13 @@ export type CreateApiClientOptions = {
      * This function will be called for each request that requires authentication.
      */
     getToken: () => Promise<string>;
+    /**
+     * The maximum time in seconds allowed for the API network request after `getToken()` resolves.
+     * It is composed with per-request signals, and a timeout rejects the API call.
+     * Non-positive and infinite values disable the timeout. `NaN` uses the default value.
+     * @default 10
+     */
+    requestTimeout?: number;
 };
 /**
  * Returns the base URL for the Management API based on the tenant ID.
@@ -59,6 +87,18 @@ export declare const getManagementApiIndicator: (tenantId: string) => string;
  * This is used when requesting an access token for the Management API.
  */
 export declare const allScope = "all";
+type LowercaseHttpMethods = {
+    get: Client<paths>['GET'];
+    put: Client<paths>['PUT'];
+    post: Client<paths>['POST'];
+    delete: Client<paths>['DELETE'];
+    options: Client<paths>['OPTIONS'];
+    head: Client<paths>['HEAD'];
+    patch: Client<paths>['PATCH'];
+    trace: Client<paths>['TRACE'];
+};
+/** A typed Management API client with lowercase HTTP methods. */
+export type ManagementApiClient = Client<paths> & LowercaseHttpMethods;
 /**
  * Creates an API client with custom token authentication.
  *
@@ -78,12 +118,12 @@ export declare const allScope = "all";
  *   getToken: async () => getYourToken(),
  * });
  *
- * const response = await client.GET('/api/applications/{id}', {
+ * const response = await client.get('/api/applications/{id}', {
  *   params: { path: { id: 'app-id' } },
  * });
  * ```
  */
-export declare function createApiClient(options: CreateApiClientOptions): Client<paths>;
+export declare function createApiClient(options: CreateApiClientOptions): ManagementApiClient;
 type ManagementApiReturnType = {
     /**
      * The API client for the Management API.
@@ -91,7 +131,7 @@ type ManagementApiReturnType = {
      * This client is configured to use the provided client credentials
      * and will automatically include the access token in requests.
      */
-    apiClient: Client<paths>;
+    apiClient: ManagementApiClient;
     /**
      * The client credentials instance used for authentication.
      */
@@ -123,7 +163,7 @@ type ManagementApiReturnType = {
  * });
  *
  * // Use apiClient to make requests to the Management API
- * const response = await apiClient.GET('/api/users');
+ * const response = await apiClient.get('/api/users');
  * console.log(response.data);
  * ```
  *

package/lib/management.js

@@ -1,5 +1,6 @@
 import createClient from 'openapi-fetch';
 import { ClientCredentials } from './client-credentials.js';
+import { normalizeTimeout, toTimeoutMilliseconds } from './timeout.js';
 /**
  * Returns the base URL for the Management API based on the tenant ID.
  * @param tenantId The tenant ID to construct the base URL.
@@ -18,6 +19,28 @@ export const getManagementApiIndicator = (tenantId) => `${getBaseUrl(tenantId)}/
  * This is used when requesting an access token for the Management API.
  */
 export const allScope = 'all';
+const bearerTokenPrefix = 'Bearer ';
+const normalizeBaseUrl = (baseUrl) => baseUrl.replace(/\/+$/u, '');
+const isWellKnownPath = (schemaPath) => schemaPath.includes('/.well-known/');
+const createRequestTimeoutFetch = (requestTimeout) => async (request, requestInit) => {
+    const signal = AbortSignal.any([
+        request.signal,
+        AbortSignal.timeout(toTimeoutMilliseconds(requestTimeout)),
+    ]);
+    return fetch(request, { ...requestInit, signal });
+};
+const addLowercaseHttpMethods = (client) => 
+// eslint-disable-next-line @silverhand/fp/no-mutating-assign -- Keep the original client identity while adding lowercase aliases.
+Object.assign(client, {
+    get: client.GET,
+    put: client.PUT,
+    post: client.POST,
+    delete: client.DELETE,
+    options: client.OPTIONS,
+    head: client.HEAD,
+    patch: client.PATCH,
+    trace: client.TRACE,
+});
 /**
  * Creates an API client with custom token authentication.
  *
@@ -37,25 +60,29 @@ export const allScope = 'all';
  *   getToken: async () => getYourToken(),
  * });
  *
- * const response = await client.GET('/api/applications/{id}', {
+ * const response = await client.get('/api/applications/{id}', {
  *   params: { path: { id: 'app-id' } },
  * });
  * ```
  */
 export function createApiClient(options) {
     const { baseUrl, getToken } = options;
-    const client = createClient({ baseUrl });
+    const requestTimeout = normalizeTimeout(options.requestTimeout);
+    const client = createClient({
+        baseUrl: normalizeBaseUrl(baseUrl),
+        ...(requestTimeout > 0 && { fetch: createRequestTimeoutFetch(requestTimeout) }),
+    });
     client.use({
         async onRequest({ schemaPath, request }) {
-            if (schemaPath.includes('/.well-known/')) {
+            if (isWellKnownPath(schemaPath)) {
                 return;
             }
             const token = await getToken();
-            request.headers.set('Authorization', `Bearer ${token}`);
+            request.headers.set('Authorization', `${bearerTokenPrefix}${token}`);
             return request;
         },
     });
-    return client;
+    return addLowercaseHttpMethods(client);
 }
 /**
  * Creates a Management API client with the specified tenant ID and options.
@@ -83,7 +110,7 @@ export function createApiClient(options) {
  * });
  *
  * // Use apiClient to make requests to the Management API
- * const response = await apiClient.GET('/api/users');
+ * const response = await apiClient.get('/api/users');
  * console.log(response.data);
  * ```
  *
@@ -99,8 +126,8 @@ export function createApiClient(options) {
  * ```
  */
 export function createManagementApi(tenantId, options) {
-    const { clientId, clientSecret } = options;
-    const baseUrl = options.baseUrl ?? getBaseUrl(tenantId);
+    const { clientId, clientSecret, tokenRequestTimeout, getTokenRequestSignal, requestTimeout } = options;
+    const baseUrl = normalizeBaseUrl(options.baseUrl ?? getBaseUrl(tenantId));
     const apiIndicator = options.apiIndicator ?? getManagementApiIndicator(tenantId);
     const clientCredentials = new ClientCredentials({
         clientId,
@@ -110,17 +137,41 @@ export function createManagementApi(tenantId, options) {
             resource: apiIndicator,
             scope: allScope,
         },
+        tokenRequestTimeout,
+        getTokenRequestSignal,
     });
+    const warnedScopes = new Set();
     const apiClient = createApiClient({
         baseUrl,
+        requestTimeout,
         getToken: async () => {
             const { value, scope } = await clientCredentials.getAccessToken();
-            if (scope !== allScope) {
+            if (scope !== allScope && !warnedScopes.has(scope)) {
+                warnedScopes.add(scope);
                 console.warn(`The scope "${scope}" is not equal to the expected value "${allScope}". This may cause issues with API access. See https://a.logto.io/m2m-mapi to learn more about configuring machine-to-machine access to the Management API.`);
             }
             return value;
         },
     });
+    apiClient.use({
+        onResponse({ schemaPath, request, response }) {
+            if (isWellKnownPath(schemaPath)) {
+                return;
+            }
+            const authorization = request.headers.get('Authorization');
+            if (!authorization?.startsWith(bearerTokenPrefix)) {
+                return;
+            }
+            const accessToken = authorization.slice(bearerTokenPrefix.length);
+            if (response.status === 401) {
+                // Do not retry here because the request body may have been consumed.
+                clientCredentials.invalidateAccessToken(accessToken);
+            }
+            else if (response.ok) {
+                clientCredentials.markAccessTokenAsValid(accessToken);
+            }
+        },
+    });
     return {
         apiClient,
         clientCredentials,

package/lib/timeout.d.ts

@@ -0,0 +1,7 @@
+export declare const normalizeTimeout: (timeout?: number) => number;
+export declare const getAbortReason: (signal: AbortSignal, fallbackMessage: string) => Error;
+export declare const toTimeoutMilliseconds: (timeout: number) => number;
+export declare const createTimeoutSignal: (timeout: number, message: string) => {
+    signal: AbortSignal;
+    clear: () => void;
+};

package/lib/timeout.js

@@ -0,0 +1,29 @@
+const defaultTimeout = 10;
+// Browsers and Node.js reliably support timer delays up to a signed 32-bit integer.
+const maximumTimeoutMilliseconds = 2_147_483_647;
+export const normalizeTimeout = (timeout) => {
+    if (timeout === undefined || Number.isNaN(timeout)) {
+        return defaultTimeout;
+    }
+    return Number.isFinite(timeout) && timeout > 0 ? timeout : 0;
+};
+export const getAbortReason = (signal, fallbackMessage) => {
+    // eslint-disable-next-line prefer-destructuring -- Keep the DOM's any-typed reason narrowed to unknown.
+    const reason = signal.reason;
+    return reason instanceof Error ? reason : new Error(fallbackMessage, { cause: reason });
+};
+export const toTimeoutMilliseconds = (timeout) => Math.min(Math.max(Math.ceil(timeout * 1000), 1), maximumTimeoutMilliseconds);
+export const createTimeoutSignal = (timeout, message) => {
+    const controller = new AbortController();
+    const timer = timeout > 0
+        ? setTimeout(() => {
+            controller.abort(new DOMException(message, 'TimeoutError'));
+        }, toTimeoutMilliseconds(timeout))
+        : undefined;
+    return {
+        signal: controller.signal,
+        clear: () => {
+            clearTimeout(timer);
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/api",
-  "version": "1.43.0",
+  "version": "1.44.0-beta.0",
   "description": "Logto API types and clients.",
   "author": "Silverhand Inc. <contact@silverhand.io>",
   "homepage": "https://github.com/logto-io/logto#readme",