@logto/api 1.42.0 → 1.44.0-beta.0

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.42.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",