@monocloud/auth-nextjs 0.1.6 → 0.1.8

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { MonoCloudAuthBaseError, MonoCloudCoreClient, MonoCloudHttpError, MonoCloudOPError, MonoCloudTokenError, MonoCloudValidationError, MonoCloudValidationError as MonoCloudValidationError$1 } from "@monocloud/auth-node-core";
 import { NextRequest, NextResponse } from "next/server.js";
 import { ensureLeadingSlash, isAbsoluteUrl, isPresent } from "@monocloud/auth-node-core/internal";
-import { isUserInGroup } from "@monocloud/auth-node-core/utils";
+import { isUserInGroup as isUserInGroup$1 } from "@monocloud/auth-node-core/utils";
 import { serialize } from "cookie";
 
 //#region src/requests/monocloud-app-router-request.ts
@@ -284,35 +284,32 @@ const mergeResponse = (responses) => {
 //#endregion
 //#region src/monocloud-next-client.ts
 /**
-* The MonoCloud Next.js Client.
+* `MonoCloudNextClient` is the core SDK entry point for integrating MonoCloud authentication into a Next.js application.
 *
-* @example Using Environment Variables (Recommended)
+* It provides:
+* - Authentication middleware
+* - Route protection helpers
+* - Session and token access
+* - Redirect utilities
+* - Server-side enforcement helpers
 *
-* 1. Add following variables to your `.env`.
+* ## 1. Add environment variables
 *
-* ```bash
+* ```bash:.env.local
 * MONOCLOUD_AUTH_TENANT_DOMAIN=<tenant-domain>
 * MONOCLOUD_AUTH_CLIENT_ID=<client-id>
 * MONOCLOUD_AUTH_CLIENT_SECRET=<client-secret>
-* MONOCLOUD_AUTH_SCOPES=openid profile email # Default
+* MONOCLOUD_AUTH_SCOPES=openid profile email
 * MONOCLOUD_AUTH_APP_URL=http://localhost:3000
 * MONOCLOUD_AUTH_COOKIE_SECRET=<cookie-secret>
 * ```
 *
-* 2. Instantiate the client in a shared file (e.g., lib/monocloud.ts)
+* ## 2. Register middleware
 *
-* ```typescript
-* import { MonoCloudNextClient } from '@monocloud/auth-nextjs';
+* ```typescript:src/proxy.ts
+* import { authMiddleware } from "@monocloud/auth-nextjs";
 *
-* export const monoCloud = new MonoCloudNextClient();
-* ```
-*
-* 3. Add MonoCloud middleware/proxy
-*
-* ```typescript
-* import { monoCloud } from "@/lib/monocloud";
-*
-* export default monoCloud.authMiddleware();
+* export default authMiddleware();
 *
 * export const config = {
 *   matcher: [
@@ -321,218 +318,115 @@ const mergeResponse = (responses) => {
 * };
 * ```
 *
-* @example Using Constructor Options
+* ## Advanced usage
+*
+* ### Create a shared client instance
+*
+* By default, the SDK exposes function exports (for example, `authMiddleware()`, `getSession()`, `getTokens()`) that internally use a shared singleton `MonoCloudNextClient`.
+*
+* Create your own `MonoCloudNextClient` instance when you need multiple configurations, dependency injection, or explicit control over initialization.
+*
+* ```ts:src/monocloud.ts
+* import { MonoCloudNextClient } from "@monocloud/auth-nextjs";
+*
+* export const monoCloud = new MonoCloudNextClient();
+* ```
+*
+* ### Using instance methods
 *
-* ⚠️ Security Note: Never commit your credentials to version control. Load them from environment variables.
+* Once you create a client instance, call methods directly on it instead of using the default function exports.
 *
-* 1. Instantiate the client in a shared file (e.g., lib/monocloud.ts)
+* ```ts:src/app/page.tsx
+* import { monoCloud } from "@/monocloud";
 *
-* ```typescript
-* import { MonoCloudNextClient } from '@monocloud/auth-nextjs';
+* export default async function Page() {
+*   const session = await monoCloud.getSession();
+*
+*   if (!session) {
+*     return <>Not signed in</>;
+*   }
+*
+*   return <>Hello {session.user.name}</>;
+* }
+* ```
+*
+* #### Using constructor options
+*
+* When configuration is provided through both constructor options and environment variables, the values passed to the constructor take precedence. Environment variables are used only for options that are not explicitly supplied.
+*
+* ```ts:src/monocloud.ts
+* import { MonoCloudNextClient } from "@monocloud/auth-nextjs";
 *
 * export const monoCloud = new MonoCloudNextClient({
-*  tenantDomain: '<tenant-domain>',
-*  clientId: '<client-id>',
-*  clientSecret: '<client-secret>',
-*  scopes: 'openid profile email', // Default
-*  appUrl: 'http://localhost:3000',
-*  cookieSecret: '<cookie-secret>'
+*   tenantDomain: "<tenant-domain>",
+*   clientId: "<client-id>",
+*   clientSecret: "<client-secret>",
+*   appUrl: "http://localhost:3000",
+*   cookieSecret: "<cookie-secret>",
+*   defaultAuthParams: {
+*     scopes: "openid profile email",
+*   },
 * });
 * ```
-* 2. Add MonoCloud middleware/proxy
 *
-* ```typescript
-* import { monoCloud } from "@/lib/monocloud";
+* ### Modifying default routes
 *
-* export default monoCloud.authMiddleware();
+* If you customize any of the default auth route paths:
 *
-* export const config = {
-*   matcher: [
-*     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-*   ],
-* };
+* - Also set the corresponding `NEXT_PUBLIC_` environment variables so client-side helpers
+*   (for example `<SignIn />`, `<SignOut />`, and `useAuth()`) can discover the correct URLs.
+* - Update the **Application URLs** in your MonoCloud Dashboard to match the new paths.
+*
+* Example:
+*
+* ```bash:.env.local
+* MONOCLOUD_AUTH_CALLBACK_URL=/api/custom_callback
+* NEXT_PUBLIC_MONOCLOUD_AUTH_CALLBACK_URL=/api/custom_callback
 * ```
 *
-* <details>
-* <summary>All Environment Variables</summary>
-*  <h4>Core Configuration (Required)</h4>
-*
-*  <ul>
-*    <li><strong>MONOCLOUD_AUTH_CLIENT_ID : </strong>Unique identifier for your application/client.</li>
-*    <li><strong>MONOCLOUD_AUTH_CLIENT_SECRET : </strong>Application/client secret.</li>
-*    <li><strong>MONOCLOUD_AUTH_TENANT_DOMAIN : </strong>The domain of your MonoCloud tenant (e.g., https://your-tenant.us.monocloud.com).</li>
-*    <li><strong>MONOCLOUD_AUTH_APP_URL : </strong>The base URL where your application is hosted.</li>
-*    <li><strong>MONOCLOUD_AUTH_COOKIE_SECRET : </strong>A long, random string used to encrypt and sign session cookies.</li>
-*  </ul>
-*
-*  <h4>Authentication &amp; Security</h4>
-*
-*  <ul>
-*    <li><strong>MONOCLOUD_AUTH_SCOPES : </strong>A space-separated list of OIDC scopes to request (e.g., openid profile email).</li>
-*    <li><strong>MONOCLOUD_AUTH_RESOURCE : </strong>The default resource/audience identifier for access tokens.</li>
-*    <li><strong>MONOCLOUD_AUTH_USE_PAR : </strong>Enables Pushed Authorization Requests.</li>
-*    <li><strong>MONOCLOUD_AUTH_CLOCK_SKEW : </strong>The allowed clock drift in seconds when validating token timestamps.</li>
-*    <li><strong>MONOCLOUD_AUTH_FEDERATED_SIGNOUT : </strong>If true, signs the user out of MonoCloud (SSO sign-out) when they sign out of the app.</li>
-*    <li><strong>MONOCLOUD_AUTH_RESPONSE_TIMEOUT : </strong>The maximum time in milliseconds to wait for a response.</li>
-*    <li><strong>MONOCLOUD_AUTH_ALLOW_QUERY_PARAM_OVERRIDES : </strong>Allows dynamic overrides of auth parameters via URL query strings.</li>
-*    <li><strong>MONOCLOUD_AUTH_POST_LOGOUT_REDIRECT_URI : </strong>The URL users are sent to after a successful logout.</li>
-*    <li><strong>MONOCLOUD_AUTH_USER_INFO : </strong>Determines if user profile data from the UserInfo endpoint should be fetched after authorization code exchange.</li>
-*    <li><strong>MONOCLOUD_AUTH_REFETCH_USER_INFO : </strong>If true, re-fetches user information on every request to userinfo endpoint or when calling getTokens()</li>
-*    <li><strong>MONOCLOUD_AUTH_ID_TOKEN_SIGNING_ALG : </strong>The expected algorithm for signing ID tokens (e.g., RS256).</li>
-*    <li><strong>MONOCLOUD_AUTH_FILTERED_ID_TOKEN_CLAIMS : </strong>A space-separated list of claims to exclude from the session object.</li>
-*  </ul>
-*
-*  <h4>Routes</h4>
-*
-*   <aside>
-*     <strong>⚠️ Important: Modifying Default Routes</strong>
-*     <p>If you choose to customize any of the default route paths, you must adhere to the following requirements:</p>
-*     <ul>
-*       <li>
-*         <strong>Client-Side Synchronization:</strong> You must also define a corresponding <code>NEXT_PUBLIC_</code> version of the environment variable (e.g., <code>NEXT_PUBLIC_MONOCLOUD_AUTH_CALLBACK_URL</code>). This ensures that client-side components like <code>&lt;SignIn /&gt;</code>, <code>&lt;SignOut /&gt;</code>, and the <code>useAuth()</code> hook can correctly identify your custom endpoints.
-*       </li>
-*       <li>
-*         <strong>Dashboard Configuration:</strong> Changing these URLs will alter the endpoints required by MonoCloud. You must update the <strong>Application URLs</strong> section in your MonoCloud Dashboard to match these new paths.
-*       </li>
-*     </ul>
-*     <p><em>Example:</em></p>
-*     <code>
-*       MONOCLOUD_AUTH_CALLBACK_URL=/api/custom_callback<br />
-*       NEXT_PUBLIC_MONOCLOUD_AUTH_CALLBACK_URL=/api/custom_callback
-*     </code>
-*     <p>In this case, the Redirect URI in your dashboard should be set to: <code>http://localhost:3000/api/custom_callback</code> (assuming local development).</p>
-*   </aside>
-*
-*  <ul>
-*    <li><strong>MONOCLOUD_AUTH_CALLBACK_URL : </strong>The application path where MonoCloud sends the user after authentication.</li>
-*    <li><strong>MONOCLOUD_AUTH_SIGNIN_URL : </strong>The internal route path to trigger the sign-in.</li>
-*    <li><strong>MONOCLOUD_AUTH_SIGNOUT_URL : </strong>The internal route path to trigger the sign-out.</li>
-*    <li><strong>MONOCLOUD_AUTH_USER_INFO_URL : </strong>The route that exposes the current user's profile from userinfo endpoint.</li>
-*  </ul>
-*
-*  <h4>Session Cookie Settings</h4>
-*
-*  <ul>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_COOKIE_NAME : </strong>The name of the cookie used to store the user session.</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_COOKIE_PATH : </strong>The scope path for the session cookie.</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_COOKIE_DOMAIN : </strong>The domain scope for the session cookie.</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_COOKIE_HTTP_ONLY : </strong>Prevents client-side scripts from accessing the session cookie.</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_COOKIE_SECURE : </strong>Ensures the session cookie is only sent over HTTPS.</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_COOKIE_SAME_SITE : </strong>The SameSite policy for the session cookie (Lax, Strict, or None).</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_COOKIE_PERSISTENT : </strong>If true, the session survives browser restarts.</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_SLIDING : </strong>If true, the session will be a sliding session instead of absolute.</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_DURATION : </strong>The session lifetime in seconds.</li>
-*    <li><strong>MONOCLOUD_AUTH_SESSION_MAX_DURATION : </strong>The absolute maximum lifetime of a session in seconds.</li>
-*  </ul>
-*
-*  <h4>State Cookie Settings</h4>
-*
-*  <ul>
-*    <li><strong>MONOCLOUD_AUTH_STATE_COOKIE_NAME : </strong>The name of the cookie used to store OpenID state/nonce.</li>
-*    <li><strong>MONOCLOUD_AUTH_STATE_COOKIE_PATH : </strong>The scope path for the state cookie.</li>
-*    <li><strong>MONOCLOUD_AUTH_STATE_COOKIE_DOMAIN : </strong>The domain scope for the state cookie.</li>
-*    <li><strong>MONOCLOUD_AUTH_STATE_COOKIE_SECURE : </strong>Ensures the state cookie is only sent over HTTPS</li>
-*    <li><strong>MONOCLOUD_AUTH_STATE_COOKIE_SAME_SITE : </strong>The SameSite policy for the state cookie.</li>
-*    <li><strong>MONOCLOUD_AUTH_STATE_COOKIE_PERSISTENT : </strong>Whether the state cookie is persistent.</li>
-*  </ul>
-*
-*  <h4>Caching</h4>
-*
-*  <ul>
-*    <li><strong>MONOCLOUD_AUTH_JWKS_CACHE_DURATION : </strong>Duration in seconds to cache the JSON Web Key Set.</li>
-*    <li><strong>MONOCLOUD_AUTH_METADATA_CACHE_DURATION : </strong>Duration in seconds to cache the OpenID discovery metadata.</li>
-*  </ul>
-* </details>
+* When routes are overridden, the Redirect URI configured in the dashboard
+* must reflect the new path. For example, during local development:
 *
+* `http://localhost:3000/api/custom_callback`
 *
+* @category Classes
 */
 var MonoCloudNextClient = class {
 	/**
-	* The underlying OIDC client instance used for low-level OpenID Connect operations.
+	* This exposes the framework-agnostic MonoCloud client used internally by the Next.js SDK.
+	* Use it if you need access to lower-level functionality not directly exposed by MonoCloudNextClient.
 	*
-	* @example
-	* // Manually revoke an access token
-	* await client.oidcClient.revokeToken(accessToken, 'access_token');
+	* @returns Returns the underlying **Node client** instance.
+	*/
+	get coreClient() {
+		return this._coreClient;
+	}
+	/**
+	* This is intended for advanced scenarios requiring direct control over the authorization or token flow.
+	*
+	* @returns Returns the underlying **OIDC client** used for OpenID Connect operations.
 	*/
 	get oidcClient() {
 		return this.coreClient.oidcClient;
 	}
 	/**
-	* @param options Configuration options including domain, client ID, and secret.
+	* Creates a new client instance.
+	*
+	* @param options Optional configuration for initializing the MonoCloud client. If not provided, settings are automatically resolved from environment variables.
 	*/
 	constructor(options) {
 		const opt = {
 			...options ?? {},
-			userAgent: (options === null || options === void 0 ? void 0 : options.userAgent) ?? `@monocloud/auth-nextjs@0.1.6`,
+			userAgent: (options === null || options === void 0 ? void 0 : options.userAgent) ?? `@monocloud/auth-nextjs@0.1.8`,
 			debugger: (options === null || options === void 0 ? void 0 : options.debugger) ?? "@monocloud:auth-nextjs"
 		};
 		this.registerPublicEnvVariables();
-		this.coreClient = new MonoCloudCoreClient(opt);
+		this._coreClient = new MonoCloudCoreClient(opt);
 	}
 	/**
-	* Creates a **Next.js API route handler** (for both Pages Router and App Router)
-	* that processes all MonoCloud authentication endpoints
-	* (`/signin`, `/callback`, `/userinfo`, `/signout`).
-	*
-	* @param options Authentication configuration routes.
-	*
-	* **Note:** If you are already using `authMiddleware()`, you typically do **not**
-	* need this API route handler. This function is intended for applications where
-	* middleware cannot be used—such as statically generated (SSG) deployments that still
-	* require server-side authentication flows.
-	*
-	* @example App Router
-	*
-	* ```typescript
-	* // app/api/auth/[...monocloud]/route.ts
-	*
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export const GET = monoCloud.monoCloudAuth();
-	*```
-	*
-	* @example App Router with Response
-	*
-	* ```typescript
-	* import { monoCloud } from "@/lib/monocloud";
-	* import { NextRequest, NextResponse } from "next/server";
-	*
-	* export const GET = (req: NextRequest) => {
-	*   const authHandler = monoCloud.monoCloudAuth();
-	*
-	*   const res = new NextResponse();
-	*
-	*   res.cookies.set("last_auth_requested", `${Date.now()}`);
-	*
-	*   return authHandler(req, res);
-	* };
-	* ```
-	*
-	* @example Pages Router
-	*
-	* ```typescript
-	* // pages/api/auth/[...monocloud].ts
-	*
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export default monoCloud.monoCloudAuth();
-	*```
-	*
-	* @example Page Router with Response
-	*
-	* ```typescript
-	* import { monoCloud } from "@/lib/monocloud";
-	* import { NextApiRequest, NextApiResponse } from "next";
-	*
-	* export default function handler(req: NextApiRequest, res: NextApiResponse) {
-	*   const authHandler = monoCloud.monoCloudAuth();
-	*
-	*   res.setHeader("last_auth_requested", `${Date.now()}`);
-	*
-	*   return authHandler(req, res);
-	* }
-	* ```
-	*
+	* @see {@link monoCloudAuth} for full docs and examples.
+	* @param options Optional configuration for the auth handler.
+	* @returns Returns a Next.js-compatible handler for App Router route handlers or Pages Router API routes.
 	*/
 	monoCloudAuth(options) {
 		return (req, resOrCtx) => {
@@ -581,7 +475,7 @@ var MonoCloudNextClient = class {
 				const { redirect } = await import("next/navigation");
 				return redirect(signInRoute.toString());
 			}
-			if ((options === null || options === void 0 ? void 0 : options.groups) && !isUserInGroup(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) {
+			if ((options === null || options === void 0 ? void 0 : options.groups) && !isUserInGroup$1(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) {
 				if (options.onGroupAccessDenied) return options.onGroupAccessDenied({
 					...params,
 					user: session.user
@@ -623,7 +517,7 @@ var MonoCloudNextClient = class {
 					permanent: false
 				} };
 			}
-			if ((options === null || options === void 0 ? void 0 : options.groups) && !isUserInGroup(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) {
+			if ((options === null || options === void 0 ? void 0 : options.groups) && !isUserInGroup$1(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) {
 				var _options$onGroupAcces;
 				const customProps = await ((_options$onGroupAcces = options.onGroupAccessDenied) === null || _options$onGroupAcces === void 0 ? void 0 : _options$onGroupAcces.call(options, {
 					...context,
@@ -669,7 +563,7 @@ var MonoCloudNextClient = class {
 			}
 			return mergeResponse([res, NextResponse.json({ message: "unauthorized" }, { status: 401 })]);
 		}
-		if ((options === null || options === void 0 ? void 0 : options.groups) && !isUserInGroup(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) {
+		if ((options === null || options === void 0 ? void 0 : options.groups) && !isUserInGroup$1(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) {
 			if (options.onGroupAccessDenied) {
 				const result = await options.onGroupAccessDenied(req, ctx, session.user);
 				if (result instanceof NextResponse) return mergeResponse([res, result]);
@@ -687,7 +581,7 @@ var MonoCloudNextClient = class {
 			if (options === null || options === void 0 ? void 0 : options.onAccessDenied) return options.onAccessDenied(req, res);
 			return res.status(401).json({ message: "unauthorized" });
 		}
-		if ((options === null || options === void 0 ? void 0 : options.groups) && !isUserInGroup(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) {
+		if ((options === null || options === void 0 ? void 0 : options.groups) && !isUserInGroup$1(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) {
 			if (options.onGroupAccessDenied) return options.onGroupAccessDenied(req, res, session.user);
 			return res.status(403).json({ message: "forbidden" });
 		}
@@ -752,7 +646,7 @@ var MonoCloudNextClient = class {
 			return mergeResponse([nxtResp, NextResponse.redirect(signInRoute)]);
 		}
 		const groupsClaim = (options === null || options === void 0 ? void 0 : options.groupsClaim) ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM;
-		if (allowedGroups && !isUserInGroup(session.user, allowedGroups, groupsClaim)) {
+		if (allowedGroups && !isUserInGroup$1(session.user, allowedGroups, groupsClaim)) {
 			if (options === null || options === void 0 ? void 0 : options.onGroupAccessDenied) {
 				const result = await options.onGroupAccessDenied(req, evt, session.user);
 				if (result instanceof NextResponse) return mergeResponse([nxtResp, result]);
@@ -824,52 +718,9 @@ var MonoCloudNextClient = class {
 		return await this.coreClient.isAuthenticated(request, response);
 	}
 	/**
-	* Redirects the user to the sign-in flow if they are not authenticated.
-	*
-	* **This helper is App Router only and is designed for server environments (server components, route handlers, and server actions).**
-	*
-	* @param options Options to customize the sign-in.
-	*
-	* @returns
-	*
-	* @example React Server Component
-	*
-	* ```tsx
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export default async function Home() {
-	*   await monoCloud.protect();
-	*
-	*   return <>You are signed in.</>;
-	* }
-	* ```
-	*
-	* @example API Handler
-	*
-	* ```typescript
-	* import { NextResponse } from "next/server";
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export const GET = async () => {
-	*   await monoCloud.protect();
-	*
-	*   return NextResponse.json({ secret: "ssshhhh!!!" });
-	* };
-	* ```
-	*
-	* @example Server Action
-	*
-	* ```typescript
-	* "use server";
-	*
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export async function getMessage() {
-	*   await monoCloud.protect();
-	*
-	*   return { secret: "sssshhhhh!!!" };
-	* }
-	* ```
+	* @see {@link protect} for full docs and examples.
+	* @param options Optional configuration for redirect behavior (for example, return URL or sign-in parameters).
+	* @returns Resolves if the user is authenticated; otherwise triggers a redirect.
 	*/
 	async protect(options) {
 		var _options$authParams19, _options$authParams20, _options$authParams21, _options$authParams22, _options$authParams23, _options$authParams24, _options$authParams25, _options$authParams26, _options$authParams27;
@@ -878,7 +729,7 @@ var MonoCloudNextClient = class {
 		try {
 			const session = await this.getSession();
 			if (session && !(options === null || options === void 0 ? void 0 : options.groups)) return;
-			if (session && options && options.groups && isUserInGroup(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) return;
+			if (session && (options === null || options === void 0 ? void 0 : options.groups) && isUserInGroup$1(session.user, options.groups, options.groupsClaim ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options.matchAll)) return;
 			const { headers } = await import("next/headers");
 			path = (await headers()).get("x-monocloud-path") ?? "/";
 		} catch {
@@ -943,66 +794,9 @@ var MonoCloudNextClient = class {
 		return await this.coreClient.isUserInGroup(request, response, groups, (options === null || options === void 0 ? void 0 : options.groupsClaim) ?? process.env.MONOCLOUD_AUTH_GROUPS_CLAIM, options === null || options === void 0 ? void 0 : options.matchAll);
 	}
 	/**
-	* Redirects the user to the sign-in flow.
-	*
-	* **This helper is App Router only and is designed for server environments (server components, route handlers, and server actions).**
-	*
-	* @param options Options to customize the sign-in.
-	*
-	* @returns
-	*
-	* @example React Server Component
-	*
-	* ```tsx
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export default async function Home() {
-	*   const allowed = await monoCloud.isUserInGroup(["admin"]);
-	*
-	*   if (!allowed) {
-	*     await monoCloud.redirectToSignIn({ returnUrl: "/home" });
-	*   }
-	*
-	*   return <>You are signed in.</>;
-	* }
-	* ```
-	*
-	* @example Server Action
-	*
-	* ```typescript
-	* "use server";
-	*
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export async function protectedAction() {
-	*   const session = await monoCloud.getSession();
-	*
-	*   if (!session) {
-	*     await monoCloud.redirectToSignIn();
-	*   }
-	*
-	*   return { data: "Sensitive Data" };
-	* }
-	* ```
-	*
-	* @example API Handler
-	*
-	* ```typescript
-	* import { NextResponse } from "next/server";
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export const GET = async () => {
-	*   const session = await monoCloud.getSession();
-	*
-	*   if (!session) {
-	*     await monoCloud.redirectToSignIn({
-	*       returnUrl: "/dashboard",
-	*     });
-	*   }
-	*
-	*   return NextResponse.json({ data: "Protected content" });
-	* };
-	* ```
+	* @see {@link redirectToSignIn} for full docs and examples.
+	* @param options Optional configuration for the redirect, such as `returnUrl` or additional sign-in parameters.
+	* @returns Never resolves. Triggers a redirect to the sign-in flow.
 	*/
 	async redirectToSignIn(options) {
 		const { routes, appUrl } = this.coreClient.getOptions();
@@ -1016,8 +810,8 @@ var MonoCloudNextClient = class {
 		if (options === null || options === void 0 ? void 0 : options.returnUrl) signInRoute.searchParams.set("return_url", options.returnUrl);
 		if (options === null || options === void 0 ? void 0 : options.maxAge) signInRoute.searchParams.set("max_age", options.maxAge.toString());
 		if (options === null || options === void 0 ? void 0 : options.authenticatorHint) signInRoute.searchParams.set("authenticator_hint", options.authenticatorHint);
-		if (Array.isArray(options === null || options === void 0 ? void 0 : options.scopes)) signInRoute.searchParams.set("scope", options.scopes.join(" "));
-		if (Array.isArray(options === null || options === void 0 ? void 0 : options.resource)) signInRoute.searchParams.set("resource", options.resource.join(" "));
+		if (options === null || options === void 0 ? void 0 : options.scopes) signInRoute.searchParams.set("scope", options.scopes);
+		if (options === null || options === void 0 ? void 0 : options.resource) signInRoute.searchParams.set("resource", options.resource);
 		if (options === null || options === void 0 ? void 0 : options.display) signInRoute.searchParams.set("display", options.display);
 		if (options === null || options === void 0 ? void 0 : options.uiLocales) signInRoute.searchParams.set("ui_locales", options.uiLocales);
 		if (Array.isArray(options === null || options === void 0 ? void 0 : options.acrValues)) signInRoute.searchParams.set("acr_values", options.acrValues.join(" "));
@@ -1027,65 +821,9 @@ var MonoCloudNextClient = class {
 		redirect(signInRoute.toString());
 	}
 	/**
-	* Redirects the user to the sign-out flow.
-	*
-	* **This helper is App Router only and is designed for server environments (server components, route handlers, and server actions).**
-	*
-	* @param options Options to customize the sign out.
-	*
-	* @returns
-	*
-	* @example React Server Component
-	*
-	* ```tsx
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export default async function Page() {
-	*   const session = await monoCloud.getSession();
-	*
-	*   // Example: Force sign-out if a specific condition is met (e.g., account suspended)
-	*   if (session?.user.isSuspended) {
-	*     await monoCloud.redirectToSignOut();
-	*   }
-	*
-	*   return <>Welcome User</>;
-	* }
-	* ```
-	*
-	* @example Server Action
-	*
-	* ```typescript
-	* "use server";
-	*
-	* import { monoCloud } from "@/lib/monocloud";
-	*
-	* export async function signOutAction() {
-	*   const session = await monoCloud.getSession();
-	*
-	*   if (session) {
-	*     await monoCloud.redirectToSignOut();
-	*   }
-	* }
-	* ```
-	*
-	* @example API Handler
-	*
-	* ```typescript
-	* import { monoCloud } from "@/lib/monocloud";
-	* import { NextResponse } from "next/server";
-	*
-	* export const GET = async () => {
-	*   const session = await monoCloud.getSession();
-	*
-	*   if (session) {
-	*     await monoCloud.redirectToSignOut({
-	*       postLogoutRedirectUri: "/goodbye",
-	*     });
-	*   }
-	*
-	*   return NextResponse.json({ status: "already_signed_out" });
-	* };
-	* ```
+	* @see {@link redirectToSignOut} for full docs and examples.
+	* @param options Optional configuration for the redirect, such as `postLogoutRedirectUri` or additional sign-out parameters.
+	* @returns Never resolves. Triggers a redirect to the sign-out flow.
 	*/
 	async redirectToSignOut(options) {
 		var _options$postLogoutRe;
@@ -1114,5 +852,275 @@ var MonoCloudNextClient = class {
 };
 
 //#endregion
-export { MonoCloudAuthBaseError, MonoCloudHttpError, MonoCloudNextClient, MonoCloudOPError, MonoCloudTokenError, MonoCloudValidationError };
+//#region src/initialize.ts
+let instance;
+/**
+* Retrieves the singleton instance of the MonoCloudNextClient.
+* Initializes it lazily on the first call.
+*/
+const getInstance = () => {
+	instance ??= new MonoCloudNextClient();
+	return instance;
+};
+/**
+* Creates a Next.js catch-all auth route handler (Pages Router and App Router) for the built-in routes (`/signin`, `/callback`, `/userinfo`, `/signout`).
+*
+* Mount this handler on a catch-all route (e.g. `/api/auth/[...monocloud]`).
+*
+* > If you already use `authMiddleware()`, you typically don’t need this handler. Use `monoCloudAuth()` when middleware cannot be used or when auth routes need customization.
+*
+* @example App Router
+* ```tsx:src/app/api/auth/[...monocloud]/route.ts tab="App Router" tab-group="monoCloudAuth"
+* import { monoCloudAuth } from "@monocloud/auth-nextjs";
+*
+* export const GET = monoCloudAuth();
+*```
+*
+* @example App Router (Response)
+* ```tsx:src/app/api/auth/[...monocloud]/route.ts tab="App Router (Response)" tab-group="monoCloudAuth"
+* import { monoCloudAuth } from "@monocloud/auth-nextjs";
+* import { NextRequest, NextResponse } from "next/server";
+*
+* export const GET = (req: NextRequest) => {
+*   const authHandler = monoCloudAuth();
+*
+*   const res = new NextResponse();
+*
+*   res.cookies.set("last_auth_requested", `${Date.now()}`);
+*
+*   return authHandler(req, res);
+* };
+* ```
+*
+* @example Pages Router
+* ```tsx:src/pages/api/auth/[...monocloud].ts tab="Pages Router" tab-group="monoCloudAuth"
+* import { monoCloudAuth } from "@monocloud/auth-nextjs";
+*
+* export default monoCloudAuth();
+*```
+*
+* @example Pages Router (Response)
+* ```tsx:src/pages/api/auth/[...monocloud].ts tab="Pages Router (Response)" tab-group="monoCloudAuth"
+* import { monoCloudAuth } from "@monocloud/auth-nextjs";
+* import { NextApiRequest, NextApiResponse } from "next";
+*
+* export default function handler(req: NextApiRequest, res: NextApiResponse) {
+*   const authHandler = monoCloudAuth();
+*
+*   res.setHeader("last_auth_requested", `${Date.now()}`);
+*
+*   return authHandler(req, res);
+* }
+* ```
+*
+* @param options Optional configuration for the auth handler.
+* @returns Returns a Next.js-compatible handler for App Router route handlers or Pages Router API routes.
+*
+* @category Functions
+*/
+function monoCloudAuth(options) {
+	return getInstance().monoCloudAuth(options);
+}
+function authMiddleware(...args) {
+	return getInstance().authMiddleware(...args);
+}
+function getSession(...args) {
+	return getInstance().getSession(...args);
+}
+function getTokens(...args) {
+	return getInstance().getTokens(...args);
+}
+function isAuthenticated(...args) {
+	return getInstance().isAuthenticated(...args);
+}
+/**
+* Ensures the current user is authenticated. If not, redirects to the sign-in flow.
+*
+* > **App Router only.** Intended for Server Components, Route Handlers, and Server Actions.
+*
+* @example Server Component
+* ```tsx:src/app/page.tsx tab="Server Component" tab-group="protect"
+* import { protect } from "@monocloud/auth-nextjs";
+*
+* export default async function Home() {
+*   await protect();
+*
+*   return <>You are signed in.</>;
+* }
+* ```
+*
+* @example Server Action
+* ```tsx:src/action.ts tab="Server Action" tab-group="protect"
+* "use server";
+*
+* import { protect } from "@monocloud/auth-nextjs";
+*
+* export async function getMessage() {
+*   await protect();
+*
+*   return { secret: "sssshhhhh!!!" };
+* }
+* ```
+*
+* @example API Handler
+* ```tsx:src/app/api/protected/route.ts tab="API Handler" tab-group="protect"
+* import { protect } from "@monocloud/auth-nextjs";
+* import { NextResponse } from "next/server";
+*
+* export const GET = async () => {
+*   await protect();
+*
+*   return NextResponse.json({ secret: "ssshhhh!!!" });
+* };
+* ```
+*
+* @param options Optional configuration for redirect behavior (for example, return URL or sign-in parameters).
+* @returns Resolves if the user is authenticated; otherwise triggers a redirect.
+*
+* @category Functions
+*/
+function protect(options) {
+	return getInstance().protect(options);
+}
+function protectApi(handler, options) {
+	return getInstance().protectApi(handler, options);
+}
+function protectPage(...args) {
+	return getInstance().protectPage(...args);
+}
+function isUserInGroup(...args) {
+	return getInstance().isUserInGroup(...args);
+}
+/**
+* Redirects the user to the sign-in flow.
+*
+* > **App Router only**. Intended for use in Server Components, Route Handlers, and Server Actions.
+*
+* This helper performs a server-side redirect to the configured sign-in route. Execution does not continue after the redirect is triggered.
+*
+* @example Server Component
+* ```tsx:src/app/page.tsx tab="Server Component" tab-group="redirect-to-sign-in"
+* import { isUserInGroup, redirectToSignIn } from "@monocloud/auth-nextjs";
+*
+* export default async function Home() {
+*   const allowed = await isUserInGroup(["admin"]);
+*
+*   if (!allowed) {
+*     await redirectToSignIn({ returnUrl: "/home" });
+*   }
+*
+*   return <>You are signed in.</>;
+* }
+* ```
+*
+* @example Server Action
+* ```tsx:src/action.ts tab="Server Action" tab-group="redirect-to-sign-in"
+* "use server";
+*
+* import { getSession, redirectToSignIn } from "@monocloud/auth-nextjs";
+*
+* export async function protectedAction() {
+*   const session = await getSession();
+*
+*   if (!session) {
+*     await redirectToSignIn();
+*   }
+*
+*   return { data: "Sensitive Data" };
+* }
+* ```
+*
+* @example API Handler
+* ```tsx:src/app/api/protected/route.ts tab="API Handler" tab-group="redirect-to-sign-in"
+* import { getSession, redirectToSignIn } from "@monocloud/auth-nextjs";
+* import { NextResponse } from "next/server";
+*
+* export const GET = async () => {
+*   const session = await getSession();
+*
+*   if (!session) {
+*     await redirectToSignIn({
+*       returnUrl: "/dashboard",
+*     });
+*   }
+*
+*   return NextResponse.json({ data: "Protected content" });
+* };
+* ```
+*
+* @param options Optional configuration for the redirect, such as `returnUrl` or additional sign-in parameters.
+* @returns Never resolves. Triggers a redirect to the sign-in flow.
+*
+* @category Functions
+*/
+function redirectToSignIn(options) {
+	return getInstance().redirectToSignIn(options);
+}
+/**
+* Redirects the user to the sign-out flow.
+*
+* > **App Router only**. Intended for use in Server Components, Route Handlers, and Server Actions.
+*
+* This helper performs a server-side redirect to the configured sign-out route. Execution does not continue after the redirect is triggered.
+*
+* @example Server Component
+* ```tsx:src/app/page.tsx tab="Server Component" tab-group="redirect-to-sign-out"
+* import { getSession, redirectToSignOut } from "@monocloud/auth-nextjs";
+*
+* export default async function Page() {
+*   const session = await getSession();
+*
+*   // Example: Force sign-out if a specific condition is met (e.g., account suspended)
+*   if (session?.user.isSuspended) {
+*     await redirectToSignOut();
+*   }
+*
+*   return <>Welcome User</>;
+* }
+* ```
+*
+* @example Server Action
+* ```tsx:src/action.ts tab="Server Action" tab-group="redirect-to-sign-out"
+* "use server";
+*
+* import { getSession, redirectToSignOut } from "@monocloud/auth-nextjs";
+*
+* export async function signOutAction() {
+*   const session = await getSession();
+*
+*   if (session) {
+*     await redirectToSignOut();
+*   }
+* }
+* ```
+*
+* @example API Handler
+* ```tsx:src/app/api/signout/route.ts tab="API Handler" tab-group="redirect-to-sign-out"
+* import { getSession, redirectToSignOut } from "@monocloud/auth-nextjs";
+* import { NextResponse } from "next/server";
+*
+* export const GET = async () => {
+*   const session = await getSession();
+*
+*   if (session) {
+*     await redirectToSignOut({
+*       postLogoutRedirectUri: "/goodbye",
+*     });
+*   }
+*
+*   return NextResponse.json({ status: "already_signed_out" });
+* };
+* ```
+*
+* @param options Optional configuration for the redirect, such as `postLogoutRedirectUri` or additional sign-out parameters.
+* @returns Never resolves. Triggers a redirect to the sign-out flow.
+*
+* @category Functions
+*/
+function redirectToSignOut(options) {
+	return getInstance().redirectToSignOut(options);
+}
+
+//#endregion
+export { MonoCloudAuthBaseError, MonoCloudHttpError, MonoCloudNextClient, MonoCloudOPError, MonoCloudTokenError, MonoCloudValidationError, authMiddleware, getSession, getTokens, isAuthenticated, isUserInGroup, monoCloudAuth, protect, protectApi, protectPage, redirectToSignIn, redirectToSignOut };
 //# sourceMappingURL=index.mjs.map