@logto/api 1.44.0-beta.0 → 1.44.0-beta.1

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

package/lib/generated-types/management.js

@@ -1,5 +1 @@
-/**
- * This file was auto-generated by openapi-typescript.
- * Do not make direct changes to the file.
- */
 export {};

package/lib/management.d.ts

@@ -1,6 +1,8 @@
 import { type Client } from 'openapi-fetch';
 import { ClientCredentials } from './client-credentials.js';
 import { type paths } from './generated-types/management.js';
+import { type PaginateMethod } from './pagination.js';
+export { ManagementApiPaginationError } from './pagination.js';
 /**
  * Options for creating a Management API client.
  */
@@ -17,14 +19,12 @@ export type CreateManagementApiOptions = {
      */
     clientSecret: string;
     /**
-     * Override the base URL generated from the tenant ID.
-     * Useful for testing or custom deployments.
+     * The base URL for the Logto instance. Required when the tenant ID is omitted.
      * Trailing slashes are ignored.
      */
     baseUrl?: string;
     /**
-     * Override the API indicator for the management API.
-     * Useful for testing or custom deployments.
+     * The resource indicator for the Management API. Required when the tenant ID is omitted.
      */
     apiIndicator?: string;
     /**
@@ -47,6 +47,17 @@ export type CreateManagementApiOptions = {
      */
     requestTimeout?: number;
 };
+/**
+ * Object options for creating a Management API client. Provide a tenant ID to derive the defaults,
+ * or provide both the base URL and API indicator directly.
+ */
+export type CreateManagementApiConfig = (CreateManagementApiOptions & {
+    tenantId: string;
+}) | (CreateManagementApiOptions & {
+    tenantId?: never;
+    baseUrl: string;
+    apiIndicator: string;
+});
 /**
  * Options for creating an API client with custom token authentication.
  */
@@ -97,8 +108,11 @@ type LowercaseHttpMethods = {
     patch: Client<paths>['PATCH'];
     trace: Client<paths>['TRACE'];
 };
-/** A typed Management API client with lowercase HTTP methods. */
-export type ManagementApiClient = Client<paths> & LowercaseHttpMethods;
+type PaginationMethod = {
+    paginate: PaginateMethod<paths>;
+};
+/** A typed Management API client with lowercase HTTP methods and pagination support. */
+export type ManagementApiClient = Client<paths> & LowercaseHttpMethods & PaginationMethod;
 /**
  * Creates an API client with custom token authentication.
  *
@@ -138,7 +152,7 @@ type ManagementApiReturnType = {
     clientCredentials: ClientCredentials;
 };
 /**
- * Creates a Management API client with the specified tenant ID and options.
+ * Creates a Management API client from a tenant ID or an explicit base URL and API indicator.
  *
  * Before using this function, ensure that you have created a machine-to-machine application in
  * Logto and granted it access to the Management API. See the documentation for more details:
@@ -148,16 +162,17 @@ type ManagementApiReturnType = {
  * This function sets up the API client with the necessary authentication using client credentials.
  * It will automatically handle token retrieval and renewal as needed.
  *
- * @param tenantId The tenant ID for which to create the Management API client. For OSS deployments,
- * you can pass any string as the tenant ID, for example, 'default'.
- * @param options The options for creating the Management API client, including client ID and secret.
+ * @param tenantIdOrConfig A tenant ID, or object options containing a tenant ID or an explicit base
+ * URL and API indicator.
+ * @param options The client options when the first argument is a tenant ID.
  * @returns An object containing the API client and client credentials instance.
  * @example
  * ```ts
  * import { createManagementApi } from '@logto/api/management';
  *
  * // Logto Cloud example
- * const { apiClient, clientCredentials } = createManagementApi('my-tenant-id', {
+ * const { apiClient, clientCredentials } = createManagementApi({
+ *   tenantId: 'my-tenant-id',
  *   clientId: 'my-client-id',
  *   clientSecret: 'my-client-secret',
  * });
@@ -170,13 +185,13 @@ type ManagementApiReturnType = {
  * @example
  * ```ts
  * // OSS example
- * const { apiClient, clientCredentials } = createManagementApi('default', {
+ * const { apiClient, clientCredentials } = createManagementApi({
+ *   tenantId: 'default',
  *   clientId: 'my-client-id',
  *   clientSecret: 'my-client-secret',
  *   baseUrl: 'https://my-oss-logto-instance.com',
- *   apiIndicator: 'https://default.logto.app/api',
  * });
  * ```
  */
+export declare function createManagementApi(config: CreateManagementApiConfig): ManagementApiReturnType;
 export declare function createManagementApi(tenantId: string, options: CreateManagementApiOptions): ManagementApiReturnType;
-export {};

package/lib/management.js

@@ -1,6 +1,8 @@
 import createClient from 'openapi-fetch';
 import { ClientCredentials } from './client-credentials.js';
+import { createPaginate } from './pagination.js';
 import { normalizeTimeout, toTimeoutMilliseconds } from './timeout.js';
+export { ManagementApiPaginationError } from './pagination.js';
 /**
  * Returns the base URL for the Management API based on the tenant ID.
  * @param tenantId The tenant ID to construct the base URL.
@@ -29,8 +31,8 @@ const createRequestTimeoutFetch = (requestTimeout) => async (request, requestIni
     ]);
     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.
+const addClientMethods = (client) => 
+// eslint-disable-next-line @silverhand/fp/no-mutating-assign -- Keep the original client identity while adding convenience methods.
 Object.assign(client, {
     get: client.GET,
     put: client.PUT,
@@ -40,6 +42,7 @@ Object.assign(client, {
     head: client.HEAD,
     patch: client.PATCH,
     trace: client.TRACE,
+    paginate: createPaginate(client.GET),
 });
 /**
  * Creates an API client with custom token authentication.
@@ -82,53 +85,33 @@ export function createApiClient(options) {
             return request;
         },
     });
-    return addLowercaseHttpMethods(client);
+    return addClientMethods(client);
 }
-/**
- * Creates a Management API client with the specified tenant ID and options.
- *
- * Before using this function, ensure that you have created a machine-to-machine application in
- * Logto and granted it access to the Management API. See the documentation for more details:
- *
- * https://a.logto.io/m2m-mapi
- *
- * This function sets up the API client with the necessary authentication using client credentials.
- * It will automatically handle token retrieval and renewal as needed.
- *
- * @param tenantId The tenant ID for which to create the Management API client. For OSS deployments,
- * you can pass any string as the tenant ID, for example, 'default'.
- * @param options The options for creating the Management API client, including client ID and secret.
- * @returns An object containing the API client and client credentials instance.
- * @example
- * ```ts
- * import { createManagementApi } from '@logto/api/management';
- *
- * // Logto Cloud example
- * const { apiClient, clientCredentials } = createManagementApi('my-tenant-id', {
- *   clientId: 'my-client-id',
- *   clientSecret: 'my-client-secret',
- * });
- *
- * // Use apiClient to make requests to the Management API
- * const response = await apiClient.get('/api/users');
- * console.log(response.data);
- * ```
- *
- * @example
- * ```ts
- * // OSS example
- * const { apiClient, clientCredentials } = createManagementApi('default', {
- *   clientId: 'my-client-id',
- *   clientSecret: 'my-client-secret',
- *   baseUrl: 'https://my-oss-logto-instance.com',
- *   apiIndicator: 'https://default.logto.app/api',
- * });
- * ```
- */
-export function createManagementApi(tenantId, options) {
-    const { clientId, clientSecret, tokenRequestTimeout, getTokenRequestSignal, requestTimeout } = options;
-    const baseUrl = normalizeBaseUrl(options.baseUrl ?? getBaseUrl(tenantId));
-    const apiIndicator = options.apiIndicator ?? getManagementApiIndicator(tenantId);
+const resolveManagementApiArguments = (tenantIdOrConfig, options) => {
+    if (typeof tenantIdOrConfig === 'string') {
+        if (!options) {
+            throw new TypeError('Options are required when creating a Management API client by tenant ID');
+        }
+        return { tenantId: tenantIdOrConfig, options };
+    }
+    if (!tenantIdOrConfig) {
+        throw new TypeError('Provide a tenant ID or both baseUrl and apiIndicator');
+    }
+    return { tenantId: tenantIdOrConfig.tenantId, options: tenantIdOrConfig };
+};
+export function createManagementApi(tenantIdOrConfig, options) {
+    const { tenantId, options: resolvedOptions } = resolveManagementApiArguments(tenantIdOrConfig, options);
+    if (tenantId !== undefined && tenantId.trim().length === 0) {
+        throw new TypeError('Tenant ID must not be empty');
+    }
+    const { clientId, clientSecret, tokenRequestTimeout, getTokenRequestSignal, requestTimeout } = resolvedOptions;
+    const configuredBaseUrl = resolvedOptions.baseUrl ?? (tenantId === undefined ? undefined : getBaseUrl(tenantId));
+    const apiIndicator = resolvedOptions.apiIndicator ??
+        (tenantId === undefined ? undefined : getManagementApiIndicator(tenantId));
+    if (configuredBaseUrl === undefined || apiIndicator === undefined) {
+        throw new TypeError('Provide a tenant ID or both baseUrl and apiIndicator');
+    }
+    const baseUrl = normalizeBaseUrl(configuredBaseUrl);
     const clientCredentials = new ClientCredentials({
         clientId,
         clientSecret,

package/lib/pagination.d.ts

@@ -0,0 +1,37 @@
+import type { Client, ClientPathsWithMethod, MaybeOptionalInit, MethodResponse } from 'openapi-fetch';
+type GetOperation<Paths extends NonNullable<unknown>, Path extends keyof Paths> = Paths[Path] extends {
+    get: infer Operation;
+} ? Operation : never;
+type OperationQuery<Operation> = Operation extends {
+    parameters: {
+        query?: infer Query;
+    };
+} ? NonNullable<Query> : never;
+type SupportsPagination<Operation> = [OperationQuery<Operation>] extends [never] ? false : 'page' extends keyof OperationQuery<Operation> ? 'page_size' extends keyof OperationQuery<Operation> ? true : false : false;
+type GetPath<Paths extends NonNullable<unknown>> = ClientPathsWithMethod<Client<Paths>, 'get'>;
+type PaginatedGetPath<Paths extends NonNullable<unknown>> = {
+    [Path in GetPath<Paths>]: SupportsPagination<GetOperation<Paths, Path>> extends true ? MethodResponse<Client<Paths>, 'get', Path> extends readonly unknown[] ? Path : never : never;
+}[GetPath<Paths>];
+type PaginationItem<Paths extends NonNullable<unknown>, Path extends PaginatedGetPath<Paths>> = MethodResponse<Client<Paths>, 'get', Path> extends ReadonlyArray<infer Item> ? Item : never;
+type GetInit<Paths extends NonNullable<unknown>, Path extends PaginatedGetPath<Paths>> = MaybeOptionalInit<{
+    get: GetOperation<Paths, Path>;
+}, 'get'>;
+type PaginationOptions<Paths extends NonNullable<unknown>, Path extends PaginatedGetPath<Paths>> = Omit<NonNullable<GetInit<Paths, Path>>, 'parseAs'> & {
+    parseAs?: never;
+};
+type PaginationInit<Paths extends NonNullable<unknown>, Path extends PaginatedGetPath<Paths>> = undefined extends GetInit<Paths, Path> ? [PaginationOptions<Paths, Path>?] : [PaginationOptions<Paths, Path>];
+/** Iterates over items returned by a paginated Management API GET endpoint. */
+export type PaginateMethod<Paths extends NonNullable<unknown>> = <Path extends PaginatedGetPath<Paths>>(path: Path, ...init: PaginationInit<Paths, Path>) => AsyncGenerator<PaginationItem<Paths, Path>, void, undefined>;
+/** An error response returned while iterating over a paginated Management API endpoint. */
+export declare class ManagementApiPaginationError extends Error {
+    /**
+     * The error response metadata and headers. Its body has already been read by openapi-fetch; the
+     * parsed error body is available as `cause`.
+     */
+    readonly response: Response;
+    readonly status: number;
+    constructor(response: Response, options?: ErrorOptions);
+}
+/** Creates a typed pagination method backed by an openapi-fetch GET method. */
+export declare const createPaginate: <Paths extends NonNullable<unknown>>(get: Client<Paths>["GET"]) => PaginateMethod<Paths>;
+export {};

package/lib/pagination.js

@@ -0,0 +1,66 @@
+const defaultPageSize = 100;
+const hasNextLink = (headers) => headers
+    .get('Link')
+    ?.split(',')
+    .some((link) => /;\s*rel=(?:"next"|next)(?:\s*;|\s*$)/iu.test(link.trim())) ?? false;
+const isTotalNumberCapped = (headers) => headers.get('Total-Number-Is-Capped')?.toLowerCase() === 'true';
+/** An error response returned while iterating over a paginated Management API endpoint. */
+export class ManagementApiPaginationError extends Error {
+    constructor(response, options) {
+        super(`Management API pagination request failed with status ${response.status}`, options);
+        this.name = 'ManagementApiPaginationError';
+        this.response = response;
+        this.status = response.status;
+    }
+}
+/** Creates a typed pagination method backed by an openapi-fetch GET method. */
+export const createPaginate = (get) => {
+    // eslint-disable-next-line no-restricted-syntax -- The runtime adapter narrows openapi-fetch's generic GET method after the public type validates the path and options.
+    const getPage = get;
+    const paginate = (path, options = {}) => {
+        const { params = {}, parseAs, ...requestOptions } = options;
+        if (parseAs !== undefined) {
+            throw new TypeError('The paginate method only supports JSON array responses');
+        }
+        const query = params.query ?? {};
+        const firstPage = query.page === undefined ? 1 : query.page;
+        if (typeof firstPage !== 'number' || !Number.isSafeInteger(firstPage) || firstPage < 1) {
+            throw new RangeError('The page parameter must be a positive safe integer');
+        }
+        const pageSize = query.page_size ?? defaultPageSize;
+        const iterate = async function* () {
+            /* eslint-disable-next-line @silverhand/fp/no-let, @silverhand/fp/no-mutation -- Pagination advances one page at a time without retaining prior page responses. */
+            for (let page = firstPage; page <= Number.MAX_SAFE_INTEGER; page += 1) {
+                // eslint-disable-next-line no-await-in-loop -- Each request depends on the previous response's pagination headers.
+                const result = await getPage(path, {
+                    ...requestOptions,
+                    params: {
+                        ...params,
+                        query: {
+                            ...query,
+                            page,
+                            page_size: pageSize,
+                        },
+                    },
+                });
+                if ('error' in result) {
+                    throw new ManagementApiPaginationError(result.response, { cause: result.error });
+                }
+                if (!Array.isArray(result.data)) {
+                    throw new TypeError('Expected a paginated Management API response to contain an array');
+                }
+                if (result.data.length === 0) {
+                    return;
+                }
+                yield* result.data;
+                if (!isTotalNumberCapped(result.response.headers) &&
+                    !hasNextLink(result.response.headers)) {
+                    return;
+                }
+            }
+        };
+        return iterate();
+    };
+    // eslint-disable-next-line no-restricted-syntax -- The public generic type adds generated path and item types to the runtime iterator.
+    return paginate;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/api",
-  "version": "1.44.0-beta.0",
+  "version": "1.44.0-beta.1",
   "description": "Logto API types and clients.",
   "author": "Silverhand Inc. <contact@silverhand.io>",
   "homepage": "https://github.com/logto-io/logto#readme",
@@ -26,6 +26,18 @@
   "bugs": {
     "url": "https://github.com/logto-io/logto/issues"
   },
+  "scripts": {
+    "precommit": "lint-staged",
+    "prepublishOnly": "pnpm generate-types && pnpm build",
+    "generate-types": "./generate-types.sh",
+    "build": "./check-types.sh && rm -rf lib/ && tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "lint": "eslint --ext .ts src",
+    "lint:report": "pnpm lint --format json --output-file report.json",
+    "test": "vitest run src",
+    "test:watch": "vitest src --watch",
+    "test:ci": "pnpm run test --silent --coverage"
+  },
   "engines": {
     "node": "^22.14.0 || ^24.0.0"
   },
@@ -49,15 +61,5 @@
     ],
     "extends": "@silverhand"
   },
-  "prettier": "@silverhand/eslint-config/.prettierrc",
-  "scripts": {
-    "precommit": "lint-staged",
-    "generate-types": "./generate-types.sh",
-    "build": "./check-types.sh && rm -rf lib/ && tsc -p tsconfig.build.json",
-    "lint": "eslint --ext .ts src",
-    "lint:report": "pnpm lint --format json --output-file report.json",
-    "test": "vitest run src",
-    "test:watch": "vitest src --watch",
-    "test:ci": "pnpm run test --silent --coverage"
-  }
-}
+  "prettier": "@silverhand/eslint-config/.prettierrc"
+}