auth0 4.28.0 → 5.0.0-beta.0

package/README.md

@@ -1,15 +1,17 @@
 ![Node.js client library for Auth0](https://cdn.auth0.com/website/sdks/banner/node-auth0-banner.png)
 
 ![Release](https://img.shields.io/npm/v/auth0)
-[![Codecov](https://img.shields.io/codecov/c/github/auth0/node-auth0)](https://codecov.io/gh/auth0/node-auth0)
+[![Codecov](https://img.shields.io/codecov/c/github/fern-demo/auth0-node-sdk)](https://codecov.io/gh/fern-demo/auth0-node-sdk)
 ![Downloads](https://img.shields.io/npm/dw/auth0)
 [![License](https://img.shields.io/:license-mit-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Ffern-demo%2Fauth0-node-sdk)
 
 📚 [Documentation](#documentation) - 🚀 [Getting Started](#getting-started) - 💻 [API Reference](#api-reference) - 💬 [Feedback](#feedback)
 
 ## Documentation
 
 - [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0
+- [API Reference](https://github.com/fern-demo/auth0-node-sdk/blob/HEAD/./reference.md) - full reference for this library
 
 ## Getting Started
 
@@ -17,7 +19,7 @@
 
 This library supports the following tooling versions:
 
-- Node.js: `>=18`
+- Node.js: `^20.19.0 || ^22.12.0 || ^24.0.0`
 
 ### Installation
 
@@ -34,51 +36,667 @@ npm install auth0
 This client can be used to access Auth0's [Authentication API](https://auth0.com/docs/api/authentication).
 
 ```js
-import { AuthenticationClient } from 'auth0';
+import { AuthenticationClient } from "auth0";
 
 const auth0 = new AuthenticationClient({
-  domain: '{YOUR_TENANT_AND REGION}.auth0.com',
-  clientId: '{OPTIONAL_CLIENT_ID}',
-  clientSecret: '{OPTIONAL_CLIENT_SECRET}',
+    domain: "{YOUR_TENANT_AND REGION}.auth0.com",
+    clientId: "{YOUR_CLIENT_ID}",
+    clientSecret: "{OPTIONAL_CLIENT_SECRET}",
 });
 ```
 
-See [more examples](https://github.com/auth0/node-auth0/blob/master/EXAMPLES.md#authentication-client).
-
 #### Management API Client
 
 The Auth0 Management API is meant to be used by back-end servers or trusted parties performing administrative tasks. Generally speaking, anything that can be done through the Auth0 dashboard (and more) can also be done through this API.
 
-Initialize your client class with a client ID, client secret and a domain.
+Initialize your client class with a domain and token:
+
+```js
+import { ManagementClient } from "auth0";
+
+const management = new ManagementClient({
+    domain: "{YOUR_TENANT_AND REGION}.auth0.com",
+    token: "{YOUR_API_V2_TOKEN}",
+});
+```
+
+Or use client credentials:
 
 ```js
-import { ManagementClient } from 'auth0';
+import { ManagementClient } from "auth0";
 
-var management = new ManagementClient({
-  domain: '{YOUR_TENANT_AND REGION}.auth0.com',
-  clientId: '{YOUR_CLIENT_ID}',
-  clientSecret: '{YOUR_CLIENT_SECRET}',
+const management = new ManagementClient({
+    domain: "{YOUR_TENANT_AND REGION}.auth0.com",
+    clientId: "{YOUR_CLIENT_ID}",
+    clientSecret: "{YOUR_CLIENT_SECRET}",
+    withCustomDomainHeader: "auth.example.com", // Optional: Auto-applies to whitelisted endpoints
 });
 ```
 
-Or, initialize your client class with an API v2 token and a domain.
+#### UserInfo API Client
+
+This client can be used to retrieve user profile information.
 
 ```js
-import { ManagementClient } from 'auth0';
+import { UserInfoClient } from "auth0";
 
-var management = new ManagementClient({
-  domain: '{YOUR_TENANT_AND REGION}.auth0.com',
-  token: '{YOUR_API_V2_TOKEN}',
+const userInfo = new UserInfoClient({
+    domain: "{YOUR_TENANT_AND REGION}.auth0.com",
 });
+
+// Get user info with an access token
+const userProfile = await userInfo.getUserInfo(accessToken);
 ```
 
-See [more examples](https://github.com/auth0/node-auth0/blob/master/EXAMPLES.md#management-client).
+## Legacy Usage
+
+If you are migrating from the legacy `node-auth0` package (v4.x) or need to maintain compatibility with legacy code, you can use the legacy export which provides the `node-auth0` v4.x API interface.
+
+### Installing Legacy Version
+
+The legacy version (`node-auth0` v4.x) is available through the `/legacy` export path:
+
+```js
+// Import the legacy version (node-auth0 v4.x API)
+import { ManagementClient, AuthenticationClient } from "auth0/legacy";
+
+// Or using CommonJS
+const { ManagementClient, AuthenticationClient } = require("auth0/legacy");
+```
+
+### Legacy Configuration
+
+The legacy API uses the `node-auth0` v4.x configuration format and method signatures, which are different from the current v5 API:
+
+#### Legacy Management Client
+
+```js
+import { ManagementClient } from "auth0/legacy";
+
+const management = new ManagementClient({
+    domain: "{YOUR_TENANT_AND REGION}.auth0.com",
+    clientId: "{YOUR_CLIENT_ID}",
+    clientSecret: "{YOUR_CLIENT_SECRET}",
+    scope: "read:users update:users",
+});
+
+// Legacy API methods use promise-based patterns (node-auth0 v4.x style)
+management.users
+    .getAll()
+    .then((users) => console.log(users))
+    .catch((err) => console.error(err));
+
+// Or with async/await
+try {
+    const users = await management.users.getAll();
+    console.log(users);
+} catch (err) {
+    console.error(err);
+}
+```
+
+#### Legacy Authentication Client
+
+```js
+import { AuthenticationClient } from "auth0/legacy";
+
+const auth0 = new AuthenticationClient({
+    domain: "{YOUR_TENANT_AND REGION}.auth0.com",
+    clientId: "{YOUR_CLIENT_ID}",
+    clientSecret: "{YOUR_CLIENT_SECRET}",
+});
+
+// Legacy authentication methods (node-auth0 v4.x style)
+auth0.oauth
+    .passwordGrant({
+        username: "user@example.com",
+        password: "password",
+        audience: "https://api.example.com",
+    })
+    .then((userData) => {
+        console.log(userData);
+    })
+    .catch((err) => {
+        console.error("Authentication error:", err);
+    });
+
+// Or with async/await
+try {
+    const userData = await auth0.oauth.passwordGrant({
+        username: "user@example.com",
+        password: "password",
+        audience: "https://api.example.com",
+    });
+    console.log(userData);
+} catch (err) {
+    console.error("Authentication error:", err);
+}
+```
+
+### Migration from Legacy (node-auth0 v4) to v5
+
+When migrating from `node-auth0` v4.x to the current v5 SDK, note the following key differences:
+
+1. **Method Names**: Many method names have changed to be more descriptive
+2. **Type Safety**: Enhanced TypeScript support with better type definitions
+3. **Error Handling**: Unified error handling with specific error types
+4. **Configuration**: Simplified configuration options
+
+#### Example Migration
+
+**Legacy (node-auth0 v4.x) code:**
+
+```js
+const { ManagementClient } = require("auth0/legacy");
+
+const management = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    clientId: "YOUR_CLIENT_ID",
+    clientSecret: "YOUR_CLIENT_SECRET",
+    scope: "read:users",
+});
+
+// With promises
+management.users
+    .getAll({ search_engine: "v3" })
+    .then((users) => {
+        console.log(users);
+    })
+    .catch((err) => {
+        console.error(err);
+    });
+
+// Or with async/await
+try {
+    const users = await management.users.getAll({ search_engine: "v3" });
+    console.log(users);
+} catch (err) {
+    console.error(err);
+}
+```
+
+**v5 equivalent:**
+
+```js
+import { ManagementClient } from "auth0";
+
+const management = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    clientId: "YOUR_CLIENT_ID",
+    clientSecret: "YOUR_CLIENT_SECRET",
+});
+
+// With promises
+management.users
+    .list({
+        searchEngine: "v3",
+    })
+    .then((users) => {
+        console.log(users);
+    })
+    .catch((error) => {
+        console.error(error);
+    });
+
+// Or with async/await
+try {
+    const users = await management.users.list({
+        searchEngine: "v3",
+    });
+    console.log(users);
+} catch (error) {
+    console.error(error);
+}
+```
+
+## Request and Response Types
+
+The SDK exports all request and response types as TypeScript interfaces. You can import them directly:
+
+```typescript
+import { ManagementClient, Management, ManagementError } from "auth0";
+
+const client = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    token: "YOUR_TOKEN",
+});
+
+// Use the request type
+const listParams: Management.ListActionsRequestParameters = {
+    triggerId: "post-login",
+    actionName: "my-action",
+};
+
+const actions = await client.actions.list(listParams);
+```
 
 ## API Reference
 
-- [AuthenticationClient](https://auth0.github.io/node-auth0/classes/auth.AuthenticationClient.html)
-- [ManagementClient](https://auth0.github.io/node-auth0/classes/management.ManagementClient.html)
-- [UserInfoClient](https://auth0.github.io/node-auth0/classes/userinfo.UserInfoClient.html)
+### Generated Documentation
+
+- [Full Reference](./reference.md) - complete API reference guide
+
+### Key Classes
+
+- **ManagementClient** - for Auth0 Management API operations
+- **AuthenticationClient** - for Auth0 Authentication API operations
+- **UserInfoClient** - for retrieving user profile information
+
+## Exception Handling
+
+When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error
+will be thrown.
+
+```typescript
+import { ManagementError } from "auth0";
+
+try {
+    await client.actions.create({
+        name: "my-action",
+        supported_triggers: [{ id: "post-login" }],
+        code: "exports.onExecutePostLogin = async (event, api) => { console.log('Hello World'); };",
+    });
+} catch (err) {
+    if (err instanceof ManagementError) {
+        console.log(err.statusCode);
+        console.log(err.message);
+        console.log(err.body);
+        console.log(err.rawResponse);
+    }
+}
+```
+
+## Pagination
+
+Some list endpoints are paginated. The SDK provides an iterator so that you can simply loop over the items:
+
+```typescript
+import { ManagementClient } from "auth0";
+
+const client = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    token: "YOUR_TOKEN",
+});
+
+const response = await client.actions.list();
+for await (const item of response) {
+    console.log(item);
+}
+
+// Or you can manually iterate page-by-page
+let page = await client.actions.list();
+while (page.hasNextPage()) {
+    page = await page.getNextPage();
+}
+```
+
+## Advanced
+
+### Additional Headers
+
+If you would like to send additional headers as part of the request, use the `headers` request option.
+
+```typescript
+const response = await client.actions.create(
+    {
+        name: "my-action",
+        supported_triggers: [{ id: "post-login" }],
+    },
+    {
+        headers: {
+            "X-Custom-Header": "custom value",
+        },
+    },
+);
+```
+
+### Request Helpers
+
+The SDK provides convenient helper functions for common request configuration patterns:
+
+```typescript
+import { ManagementClient, CustomDomainHeader, withTimeout, withRetries, withHeaders, withAbortSignal } from "auth0";
+
+const client = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    token: "YOUR_TOKEN",
+});
+
+// Example 1: Use custom domain header for specific requests
+const reqOptions = {
+    ...CustomDomainHeader("auth.example.com"),
+    timeoutInSeconds: 30,
+};
+await client.actions.list({}, reqOptions);
+
+// Example 2: Combine multiple options
+const reqOptions = {
+    ...withTimeout(30),
+    ...withRetries(3),
+    ...withHeaders({
+        "X-Request-ID": crypto.randomUUID(),
+        "X-Operation-Source": "admin-dashboard",
+    }),
+};
+await client.actions.list({}, reqOptions);
+
+// Example 3: For automatic custom domain header on whitelisted endpoints
+const client = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    token: "YOUR_TOKEN",
+    withCustomDomainHeader: "auth.example.com", // Auto-applies to whitelisted endpoints
+});
+
+// Example 4: Request cancellation
+const controller = new AbortController();
+const reqOptions = {
+    ...withAbortSignal(controller.signal),
+    ...withTimeout(30),
+};
+const promise = client.actions.list({}, reqOptions);
+
+// Cancel after 10 seconds
+setTimeout(() => controller.abort(), 10000);
+```
+
+Available helper functions:
+
+- `CustomDomainHeader(domain)` - Configure custom domain header for specific requests
+- `withTimeout(seconds)` - Set request timeout
+- `withRetries(count)` - Configure retry attempts
+- `withHeaders(headers)` - Add custom headers
+- `withAbortSignal(signal)` - Enable request cancellation
+
+To apply the custom domain header globally across your application, use the withCustomDomainHeader option when initializing the ManagementClient. This will automatically inject the header for all whitelisted endpoints.
+
+### Retries
+
+The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long
+as the request is deemed retryable and the number of retry attempts has not grown larger than the configured
+retry limit (default: 2).
+
+A request is deemed retryable when any of the following HTTP status codes is returned:
+
+- [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout)
+- [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests)
+- [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500) (Internal Server Errors)
+
+Use the `maxRetries` request option to configure this behavior.
+
+```typescript
+const response = await client.actions.create(
+    {
+        name: "my-action",
+        supported_triggers: [{ id: "post-login" }],
+    },
+    {
+        maxRetries: 0, // override maxRetries at the request level
+    },
+);
+```
+
+### Timeouts
+
+The SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior.
+
+```typescript
+const response = await client.actions.create(
+    {
+        name: "my-action",
+        supported_triggers: [{ id: "post-login" }],
+    },
+    {
+        timeoutInSeconds: 30, // override timeout to 30s
+    },
+);
+```
+
+### Aborting Requests
+
+The SDK allows users to abort requests at any point by passing in an abort signal.
+
+```typescript
+const controller = new AbortController();
+const response = await client.actions.create(
+    {
+        name: "my-action",
+        supported_triggers: [{ id: "post-login" }],
+    },
+    {
+        abortSignal: controller.signal,
+    },
+);
+controller.abort(); // aborts the request
+```
+
+### Access Raw Response Data
+
+The SDK provides access to raw response data, including headers, through the `.withRawResponse()` method.
+The `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property.
+
+```typescript
+const { data, rawResponse } = await client.actions
+    .create({
+        name: "my-action",
+        supported_triggers: [{ id: "post-login" }],
+    })
+    .withRawResponse();
+
+console.log(data);
+console.log(rawResponse.headers);
+```
+
+### Runtime Compatibility
+
+The SDK defaults to `node-fetch` but will use the global fetch client if present. The SDK works in the following
+runtimes:
+
+- Node.js 20.19.0+, 22.12.0+, 24+
+- Vercel
+- Cloudflare Workers
+- Deno v1.25+
+- Bun 1.0+
+- React Native
+
+### Customizing Fetch Client
+
+The SDK defaults to `node-fetch` but will use the global fetch client if present. For most use cases, you can simply ensure your preferred fetch implementation is available globally.
+
+```typescript
+import { ManagementClient } from "auth0";
+
+// Example 1: Add request logging using a custom fetcher
+const client = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    token: "YOUR_TOKEN",
+    fetcher: async (args) => {
+        console.log(`Making ${args.method} request to: ${args.url}`);
+
+        // Use the global fetch (built into Node.js 18+)
+        const response = await fetch(args.url, {
+            method: args.method,
+            headers: args.headers as Record<string, string>,
+            body: args.body ? JSON.stringify(args.body) : undefined,
+        });
+
+        const rawResponse = {
+            headers: response.headers,
+            redirected: response.redirected,
+            status: response.status,
+            statusText: response.statusText,
+            type: response.type,
+            url: response.url,
+        };
+
+        if (response.ok) {
+            return {
+                ok: true as const,
+                body: await response.json(),
+                headers: response.headers,
+                rawResponse,
+            };
+        } else {
+            return {
+                ok: false as const,
+                error: {
+                    reason: "status-code" as const,
+                    statusCode: response.status,
+                    body: await response.text(),
+                },
+                rawResponse,
+            };
+        }
+    },
+});
+
+// Example 2: Add custom headers to all requests
+const clientWithHeaders = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    token: "YOUR_TOKEN",
+    fetcher: async (args) => {
+        // Add custom headers
+        const headers = {
+            ...(args.headers as Record<string, string>),
+            "X-Custom-Header": "my-value",
+            "X-Request-ID": crypto.randomUUID(),
+        };
+
+        const response = await fetch(args.url, {
+            method: args.method,
+            headers,
+            body: args.body ? JSON.stringify(args.body) : undefined,
+        });
+
+        const rawResponse = {
+            headers: response.headers,
+            redirected: response.redirected,
+            status: response.status,
+            statusText: response.statusText,
+            type: response.type,
+            url: response.url,
+        };
+
+        if (response.ok) {
+            return {
+                ok: true as const,
+                body: await response.json(),
+                headers: response.headers,
+                rawResponse,
+            };
+        } else {
+            return {
+                ok: false as const,
+                error: {
+                    reason: "status-code" as const,
+                    statusCode: response.status,
+                    body: await response.text(),
+                },
+                rawResponse,
+            };
+        }
+    },
+});
+
+// Example 3: Complete custom implementation with axios (advanced)
+import axios from "axios";
+
+const clientWithAxios = new ManagementClient({
+    domain: "your-tenant.auth0.com",
+    token: "YOUR_TOKEN",
+    fetcher: async (args) => {
+        try {
+            // Process headers to resolve any Supplier functions/promises
+            const resolvedHeaders: Record<string, string> = {};
+            if (args.headers) {
+                for (const [key, value] of Object.entries(args.headers)) {
+                    if (value !== undefined) {
+                        // Handle Supplier type: could be string, Promise<string>, or () => string | Promise<string>
+                        const resolvedValue = typeof value === "function" ? await value() : await value;
+                        if (typeof resolvedValue === "string") {
+                            resolvedHeaders[key] = resolvedValue;
+                        } else if (resolvedValue != null) {
+                            resolvedHeaders[key] = String(resolvedValue);
+                        }
+                    }
+                }
+            }
+
+            const response = await axios({
+                url: args.url,
+                method: args.method,
+                headers: resolvedHeaders, // Now properly typed for axios
+                data: args.body,
+                timeout: args.timeoutMs || 60000,
+                params: args.queryParameters,
+                validateStatus: () => true, // Don't throw on HTTP error status codes
+            });
+
+            // Convert axios headers to Web API Headers format for rawResponse
+            const rawHeaders = new Headers();
+            Object.entries(response.headers).forEach(([key, value]) => {
+                if (typeof value === "string") {
+                    rawHeaders.set(key, value);
+                } else if (Array.isArray(value)) {
+                    rawHeaders.set(key, value.join(", "));
+                } else if (value != null) {
+                    rawHeaders.set(key, String(value));
+                }
+            });
+
+            if (response.status >= 200 && response.status < 400) {
+                return {
+                    ok: true,
+                    body: response.data,
+                    headers: response.headers, // axios headers for legacy compatibility
+                    rawResponse: {
+                        headers: rawHeaders, // Web API Headers for rawResponse
+                        redirected: false, // axios doesn't provide this info directly
+                        status: response.status,
+                        statusText: response.statusText,
+                        type: "basic", // axios doesn't provide this, default to 'basic'
+                        url: response.config.url || args.url,
+                    },
+                };
+            } else {
+                return {
+                    ok: false,
+                    error: {
+                        reason: "status-code",
+                        statusCode: response.status,
+                        body: response.data,
+                    },
+                    rawResponse: {
+                        headers: rawHeaders,
+                        redirected: false,
+                        status: response.status,
+                        statusText: response.statusText,
+                        type: "basic",
+                        url: response.config.url || args.url,
+                    },
+                };
+            }
+        } catch (error: any) {
+            return {
+                ok: false,
+                error: {
+                    reason: "unknown",
+                    errorMessage: error?.message || "Unknown error occurred",
+                },
+                rawResponse: {
+                    headers: new Headers(), // Empty Headers object for network errors
+                    redirected: false,
+                    status: 0,
+                    statusText: "Network Error",
+                    type: "error",
+                    url: args.url,
+                },
+            };
+        }
+    },
+});
+```
+
+Note: When using a custom `fetcher`, you need to return an object that matches the expected API response format with `ok`, `body`, `headers`, and `rawResponse` properties.
 
 ## Feedback
 
@@ -89,9 +707,17 @@ We appreciate feedback and contribution to this repo! Before you get started, pl
 - [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
 - [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
 
+While we value open-source contributions to this SDK, this library is generated programmatically.
+Additions made directly to this library would have to be moved over to our generation code,
+otherwise they would be overwritten upon the next generated release. Feel free to open a PR as
+a proof of concept, but know that we will not be able to merge it as-is. We suggest opening
+an issue first to discuss with us!
+
+On the other hand, contributions to the README are always very welcome!
+
 ### Raise an issue
 
-To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/auth0/node-auth0/issues).
+To provide feedback or report a bug, please [raise an issue on our issue tracker](https://github.com/fern-demo/auth0-node-sdk/issues).
 
 ### Vulnerability Reporting
 
@@ -110,5 +736,5 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
   Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
 </p>
 <p align="center">
-  This project is licensed under the MIT license. See the <a href="https://github.com/auth0/node-auth0/blob/master/LICENSE"> LICENSE</a> file for more info.
+  This project is licensed under the MIT license. See the <a href="./LICENSE"> LICENSE</a> file for more info.
 </p>