@logto/api 1.44.0-beta.0 → 1.44.0

package/README.md

@@ -27,8 +27,8 @@ For detailed setup instructions, visit: https://a.logto.io/m2m-mapi
 ```ts
 import { createManagementApi } from '@logto/api/management';
 
-// For Logto Cloud
-const { apiClient } = createManagementApi('your-tenant-id', {
+const { apiClient } = createManagementApi({
+  tenantId: 'your-tenant-id',
   clientId: 'your-client-id',
   clientSecret: 'your-client-secret',
 });
@@ -39,19 +39,44 @@ const response = await apiClient.get('/api/users');
 console.log(response.data);
 ```
 
+The positional `createManagementApi(tenantId, options)` form remains supported.
+
+#### Pagination
+
+Use `paginate()` to iterate over items from a paginated `GET` endpoint. The path, query parameters,
+path parameters, headers, and signal use the same generated types as `get()`.
+
+```ts
+for await (const user of apiClient.paginate('/api/users')) {
+  console.log(user);
+}
+```
+
+The iterator follows the Management API pagination headers and stops when there are no more items.
+It requests 100 items per page unless `page_size` is provided. When an audit log endpoint reports a
+capped total, the iterator continues until it receives an empty page because the final page is
+unknown. Breaking out of the loop stops further requests.
+
+API error responses throw `ManagementApiPaginationError`, which exposes `status`, response metadata
+and headers through `response`, and the parsed API error body as `cause`. The response body has
+already been read. Network, timeout, and abort errors propagate unchanged.
+
 #### Self-hosted / OSS
 
 ```ts
 import { createManagementApi } from '@logto/api/management';
 
-const { apiClient } = createManagementApi('default', {
+const { apiClient } = createManagementApi({
+  tenantId: 'default',
   clientId: 'your-client-id',
   clientSecret: 'your-client-secret',
   baseUrl: 'https://your-logto-instance.com',
-  apiIndicator: 'https://your-logto-instance.com/api',
 });
 ```
 
+If the Management API indicator cannot be derived from a tenant ID, omit `tenantId` and provide
+both `baseUrl` and `apiIndicator`.
+
 #### Timeouts
 
 Token fetches and Management API network requests have separate 10-second timeouts. The API request
@@ -67,8 +92,8 @@ 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.
+token also receives a `401`, it remains cached until the API returns a non-`401` response or the token
+expires. The SDK does not automatically retry the failed API request.
 
 #### Custom authentication
 

package/lib/client-credentials.d.ts

@@ -56,7 +56,7 @@ export declare class ClientCredentials {
      * 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. */
+    /** Allows a future 401 to invalidate the token after the API accepts it. */
     markAccessTokenAsValid(token: string): void;
     private fetchAccessToken;
     private requestAccessToken;

package/lib/client-credentials.js

@@ -77,7 +77,7 @@ export class ClientCredentials {
             this.awaitingValidationAfterRefresh = true;
         }
     }
-    /** Allows a future 401 to invalidate the token after it receives a successful API response. */
+    /** Allows a future 401 to invalidate the token after the API accepts it. */
     markAccessTokenAsValid(token) {
         if (this.accessToken?.value === token) {
             this.awaitingValidationAfterRefresh = false;