@monocloud/auth-nextjs 0.1.5 → 0.1.7

package/dist/index.d.mts

@@ -1,42 +1,41 @@
-import { _ as ProtectPagePageOptions, a as GroupOptions, b as RedirectToSignInOptions, c as MonoCloudAuthOptions, d as PageRouterApiOnAccessDeniedHandler, f as ProtectApiAppOptions, g as ProtectPagePageOnAccessDeniedType, h as ProtectOptions, i as ExtraAuthParams, l as MonoCloudMiddlewareOptions, m as ProtectAppPageOptions, n as AppRouterApiOnAccessDeniedHandler, o as IsUserInGroupOptions, p as ProtectApiPageOptions, r as AppRouterPageHandler, s as MonoCloudAuthHandler, t as AppRouterApiHandlerFn, u as NextMiddlewareResult, v as ProtectPagePageReturnType, x as RedirectToSignOutOptions, y as ProtectedAppServerComponent } from "./types-CsBjAJce.mjs";
-import { AccessToken, GetTokensOptions, GetTokensOptions as GetTokensOptions$1, MonoCloudAuthBaseError, MonoCloudCoreClient, MonoCloudHttpError, MonoCloudOPError, MonoCloudOidcClient, MonoCloudOptions, MonoCloudOptions as MonoCloudOptions$1, MonoCloudSession, MonoCloudSession as MonoCloudSession$1, MonoCloudTokenError, MonoCloudTokens, MonoCloudTokens as MonoCloudTokens$1, MonoCloudUser, MonoCloudValidationError } from "@monocloud/auth-node-core";
+import { A as ProtectedRouteMatcher, C as ProtectAppPageOptions, D as ProtectPagePageOptions, E as ProtectPagePageOnGroupAccessDeniedType, M as RedirectToSignInOptions, N as RedirectToSignOutOptions, O as ProtectPagePageReturnType, S as ProtectApiPageOptions, T as ProtectPagePageOnAccessDeniedType, _ as OnError, a as AppRouterContext, b as PageRouterApiOnGroupAccessDeniedHandler, c as ExtraAuthParams, d as MonoCloudAuthHandler, f as MonoCloudAuthOptions, g as NextMiddlewareResult, h as NextMiddlewareOnGroupAccessDenied, i as AppRouterApiOnGroupAccessDeniedHandler, j as ProtectedRoutes, k as ProtectedAppServerComponent, l as GroupOptions, m as NextMiddlewareOnAccessDenied, n as AppRouterApiHandlerFn, o as AppRouterPageHandler, p as MonoCloudMiddlewareOptions, r as AppRouterApiOnAccessDeniedHandler, s as CustomProtectedRouteMatcher, t as AppOnError, u as IsUserInGroupOptions, v as PageOnError, w as ProtectOptions, x as ProtectApiAppOptions, y as PageRouterApiOnAccessDeniedHandler } from "./types-xS_Me3Qg.mjs";
+import { AccessToken, Address, ApplicationState, Authenticators, AuthorizationParams, CodeChallengeMethod, DisplayOptions, GetTokensOptions, GetTokensOptions as GetTokensOptions$1, Group, IdTokenClaims, Indicator, Jwk, MonoCloudAuthBaseError, MonoCloudCookieOptions, MonoCloudCoreClient, MonoCloudHttpError, MonoCloudOPError, MonoCloudOptions, MonoCloudOptions as MonoCloudOptions$1, MonoCloudRequest, MonoCloudRoutes, MonoCloudSession, MonoCloudSession as MonoCloudSession$1, MonoCloudSessionOptions, MonoCloudSessionOptionsBase, MonoCloudSessionStore, MonoCloudStateOptions, MonoCloudStatePartialOptions, MonoCloudTokenError, MonoCloudTokens, MonoCloudTokens as MonoCloudTokens$1, MonoCloudUser, MonoCloudValidationError, OnBackChannelLogout, OnSessionCreating, OnSetApplicationState, Prompt, ResponseModes, ResponseTypes, SameSiteValues, SecurityAlgorithms, SessionLifetime, UserinfoResponse } from "@monocloud/auth-node-core";
 import { NextFetchEvent, NextMiddleware, NextProxy, NextRequest, NextResponse } from "next/server.js";
-import { IncomingMessage, ServerResponse } from "node:http";
+import { NextFetchEvent as NextFetchEvent$1, NextMiddleware as NextMiddleware$1, NextProxy as NextProxy$1, NextRequest as NextRequest$1, NextResponse as NextResponse$1 } from "next/server";
 import { NextApiHandler, NextApiRequest, NextApiResponse } from "next/types";
 import { ParsedUrlQuery } from "node:querystring";
+import { MonoCloudOidcClient, MonoCloudSession as MonoCloudSession$2 } from "@monocloud/auth-core";
+import { IncomingMessage, ServerResponse } from "node:http";
+import { NextApiHandler as NextApiHandler$1, NextApiRequest as NextApiRequest$1, NextApiResponse as NextApiResponse$1 } from "next";
 
 //#region src/monocloud-next-client.d.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)
- *
- * ```typescript
- * import { MonoCloudNextClient } from '@monocloud/auth-nextjs';
- *
- * export const monoCloud = new MonoCloudNextClient();
- * ```
- *
- * 3. Add MonoCloud middleware/proxy
+ * ## 2. Register middleware
  *
- * ```typescript
- * import { monoCloud } from "@/lib/monocloud";
+ * ```typescript:src/proxy.ts
+ * import { authMiddleware } from "@monocloud/auth-nextjs";
  *
- * export default monoCloud.authMiddleware();
+ * export default authMiddleware();
  *
  * export const config = {
  *   matcher: [
@@ -45,1926 +44,1638 @@ import { ParsedUrlQuery } from "node:querystring";
  * };
  * ```
  *
- * @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
  */
 declare class MonoCloudNextClient {
+  private readonly _coreClient;
   /**
-   * The underlying MonoCloud Node Core Client instance.
-   *
-   * This property exposes the framework-agnostic node core client used by the Next.js client.
-   * You can access this to use low-level methods not directly exposed by the Next.js wrapper.
+   * 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 destroy session
-   * ```typescript
-   * // req and res must implement IMonoCloudCookieRequest/Response
-   * await monoCloud.coreClient.destroySession(request, response);
-   * ```
+   * @returns Returns the underlying **Node client** instance.
    */
-  readonly coreClient: MonoCloudCoreClient;
+  get coreClient(): MonoCloudCoreClient;
   /**
-   * The underlying OIDC client instance used for low-level OpenID Connect operations.
+   * This is intended for advanced scenarios requiring direct control over the authorization or token flow.
    *
-   * @example
-   * // Manually revoke an access token
-   * await client.oidcClient.revokeToken(accessToken, 'access_token');
+   * @returns Returns the underlying **OIDC client** used for OpenID Connect operations.
    */
   get oidcClient(): MonoCloudOidcClient;
   /**
-   * @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?: MonoCloudOptions$1);
   /**
-   * 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?: MonoCloudAuthOptions): MonoCloudAuthHandler;
   /**
-   *
-   * ## App Router
-   *
-   * Restricts access to server-rendered pages in your Next.js App Router application, ensures that only authenticated (and optionally authorized) users can view the page.
-   *
-   * **Note⚠️ - When using groups to protect a page, 'Access Denied' is rendered by default when the user does not belong to the groups.
-   *  To display a custom component, pass the `onGroupAccessDenied` parameter.**
-   *
-   * @param component The App Router server component that protectPage wraps and secures
-   * @param options App Router `protectPage()` configuration options
-   *
-   * @returns A protected page handler.
-   *
-   * @example
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default monoCloud.protectPage(async function Home({ user }) {
-   *  return <>Hi {user.email}. You accessed a protected page.</>;
-   * });
-   * ```
-   *
-   * @example App Router with options
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default monoCloud.protectPage(
-   *   async function Home({ user }) {
-   *     return <>Hi {user.email}. You accessed a protected page.</>;
-   *   },
-   *   {
-   *     returnUrl: "/dashboard",
-   *     groups: ["admin"],
-   *   }
-   * );
-   * ```
+   * @see {@link protectPage} for full docs and examples.
+   * @param component The App Router server component to protect.
+   * @param options Optional configuration for authentication, authorization, and custom access handling (`onAccessDenied`, `onGroupAccessDenied`).
+   * @returns A wrapped page component that enforces authentication before rendering.
    */
   protectPage(component: ProtectedAppServerComponent, options?: ProtectAppPageOptions): AppRouterPageHandler;
   /**
-   * ## Pages Router
-   *
-   * Restricts access to server-rendered pages in your Next.js Pages Router application, ensures that only authenticated (and optionally authorized) users can view the page.
-   *
-   * **Note⚠️ - When using groups to protect a page, the page will be rendered even if the user does not belong to the groups.
-   * You should check the props for `groupAccessDenied` boolean value to determine whether the user is
-   * allowed to access the page. Alternatively, you can pass `onGroupAccessDenied` parameter to return custom props.**
-   *
-   * @param options Pages Router `protectPage()` configuration options
-   *
-   * @typeParam P - The type of parameters accepted by the page handler.
-   * @typeParam Q - The type of query parameters parsed from the URL.
-   *
-   * @returns A protected page handler.
-   *
-   * @example
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { InferGetServerSidePropsType } from "next";
-   *
-   * export default function Home({
-   *   user,
-   * }: InferGetServerSidePropsType<typeof getServerSideProps>) {
-   *   return <>Hi {user.email}. You accessed a protected page.</>;
-   * }
-   *
-   * export const getServerSideProps = monoCloud.protectPage();
-   * ```
-   *
-   * @example Pages Router with options
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { GetServerSidePropsContext, InferGetServerSidePropsType } from "next";
-   *
-   * export default function Home({
-   *   user,
-   *   url,
-   * }: InferGetServerSidePropsType<typeof getServerSideProps>) {
-   *   console.log(url);
-   *   return <div>Hi {user?.email}. You accessed a protected page.</div>;
-   * }
-   *
-   * export const getServerSideProps = monoCloud.protectPage({
-   *   returnUrl: "/dashboard",
-   *   groups: ["admin"],
-   *   getServerSideProps: async (context: GetServerSidePropsContext) => ({
-   *     props: { url: context.resolvedUrl },
-   *   }),
-   * });
-   * ```
+   * @see {@link protectPage} for full docs and examples.
+   * @param options Optional configuration for authentication, authorization, and custom access handling (`onAccessDenied`, `onGroupAccessDenied`).
+   * @typeParam P - Props returned from getServerSideProps.
+   * @typeParam Q - Query parameters parsed from the URL.
+   * @returns A getServerSideProps wrapper that enforces authentication before executing the page logic.
    */
   protectPage<P extends Record<string, any> = Record<string, any>, Q extends ParsedUrlQuery = ParsedUrlQuery>(options?: ProtectPagePageOptions<P, Q>): ProtectPagePageReturnType<P, Q>;
   private protectAppPage;
   private protectPagePage;
   /**
-   * ## App Router
-   *
-   * Secures Next.js App Router APIs. It ensures only authenticated (and optionally authorized) requests can access the route.
-   *
-   * @param handler The api route handler function to protect
-   * @param options App Router `protectApi()` configuration options
-   *
-   * @returns Protected route handler
-   *
-   * @example
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextResponse } from "next/server";
-   *
-   * export const GET = monoCloud.protectApi(async () => {
-   *   return NextResponse.json({
-   *     message: "You accessed a protected endpoint",
-   *   });
-   * });
-   * ```
+   * @see {@link protectApi} for full docs and examples.
+   * @param handler The route handler to protect.
+   * @param options Optional configuration controlling authentication and authorization behavior.
+   * @returns Returns a wrapped handler that enforces authentication (and optional authorization) before invoking the original handler.
    */
   protectApi(handler: AppRouterApiHandlerFn, options?: ProtectApiAppOptions): AppRouterApiHandlerFn;
   /**
-   * ## Pages Router
-   *
-   * Secures Next.js Pages Router APIs. It ensures only authenticated (and optionally authorized) requests can access the route.
-   *
-   * @param handler The api route handler function to protect
-   * @param options Pages Router `protectApi()` configuration options
-   *
-   * @returns Protected route handler
-   *
-   * @example
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { NextApiRequest, NextApiResponse } from "next";
-   *
-   * export default monoCloud.protectApi(
-   *   async (req: NextApiRequest, res: NextApiResponse) => {
-   *     return res.json({
-   *       message: "You accessed a protected endpoint",
-   *     });
-   *   }
-   * );
-   * ```
+   * @see {@link protectApi} for full docs and examples.
+   * @param handler - The route handler to protect.
+   * @param options Optional configuration controlling authentication and authorization behavior.
+   * @returns Returns a wrapped handler that enforces authentication (and optional authorization) before invoking the original handler.
    */
   protectApi(handler: NextApiHandler, options?: ProtectApiPageOptions): NextApiHandler;
   private protectAppApi;
   private protectPageApi;
   /**
-   * A middleware/proxy that protects pages and APIs and handles authentication.
-   *
-   * @param options Middleware configuration options
-   *
-   * @returns A Next.js middleware/proxy function.
-   *
-   * @example Protect All Routes
-   *
-   * - Default behavior: protect all routes matched by `config.matcher`
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default monoCloud.authMiddleware();
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example Protect Selected Routes
-   *
-   * - Protect only the routes listed in `protectedRoutes`
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default monoCloud.authMiddleware({
-   *   protectedRoutes: ["/api/admin", "^/api/protected(/.*)?$"],
-   * });
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   *```
-   *
-   * @example Make All Routes Public
-   *
-   * - Do not protect any routes; MonoCloud still handles auth endpoints
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default monoCloud.authMiddleware({
-   *   protectedRoutes: [],
-   * });
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example Protect Routes Dynamically
-   *
-   * - Decide at runtime which routes to protect
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default monoCloud.authMiddleware({
-   *   protectedRoutes: (req) => {
-   *     return req.nextUrl.pathname.startsWith("/api/protected");
-   *   },
-   * });
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example Protect routes based on groups
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default monoCloud.authMiddleware({
-   *   // group names or IDs
-   *   protectedRoutes: [
-   *     {
-   *       groups: ["admin", "editor", "537e7c3d-a442-4b5b-b308-30837aa045a4"],
-   *       routes: ["/internal", "/api/internal(.*)"],
-   *     },
-   *   ],
-   * });
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
+   * @see {@link authMiddleware} for full docs and examples.
+   * @param options Optional configuration that controls how authentication is enforced (for example, redirect behavior, route matching, or custom handling of unauthenticated requests).
+   * @returns Returns a Next.js middleware result (`NextResponse`, redirect, or `undefined` to continue processing).
    */
   authMiddleware(options?: MonoCloudMiddlewareOptions): NextMiddleware | NextProxy;
   /**
-   * A middleware that protects pages and APIs and handles authentication.
-   *
-   * @param request The Next.js fetch event object.
-   * @param event The associated fetch event [Docs](https://nextjs.org/docs/app/api-reference/file-conventions/proxy#waituntil-and-nextfetchevent).
-   *
-   * @returns A promise resolving to a Next.js middleware result or a Next.js middleware result.
-   *
-   * @example Nest Custom Middleware
-   *
-   * - Use your own middleware wrapper and call MonoCloud only for specific routes
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextFetchEvent, NextRequest, NextResponse } from "next/server";
-   *
-   * export default function customMiddleware(req: NextRequest, evt: NextFetchEvent) {
-   *   if (req.nextUrl.pathname.startsWith("/api/protected")) {
-   *     return monoCloud.authMiddleware(req, evt);
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
+   * @see {@link authMiddleware} for full docs and examples.
+   * @param request Incoming Next.js middleware request used to resolve authentication state.
+   * @param event Next.js middleware event providing lifecycle hooks such as `waitUntil`.
+   * @returns Returns a Next.js middleware result (`NextResponse`, redirect, or `undefined` to continue processing).
    */
   authMiddleware(request: NextRequest, event: NextFetchEvent): Promise<NextMiddlewareResult> | NextMiddlewareResult;
   private authMiddlewareHandler;
   private handleAuthRoutes;
   /**
-   * ## SSR Components, Actions, Middleware or API Handlers
-   *
-   * Retrieves the session object for the currently authenticated user on the server.
-   *
-   * **Use Case:**
-   * - App Router Server Components (RSC).
-   * - Server Actions
-   * - Route Handlers (App Router only).
-   * - Middleware (App Router and Pages Router).
-   *
-   * *Note: If the session cannot be resolved or an underlying error occurs, the promise rejects with an error.*
-   *
-   * @returns `MonoCloudSession` if found, or `undefined`.
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextResponse } from "next/server";
-   *
-   * export default async function middleware() {
-   *   const session = await monoCloud.getSession();
-   *
-   *   if (!session) {
-   *     return new NextResponse("User not signed in", { status: 401 });
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example App Router API Handler
-   *
-   * ```typescript
-   * import { NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async () => {
-   *   const session = await monoCloud.getSession();
-   *
-   *   return NextResponse.json({ name: session?.user.name });
-   * };
-   * ```
-   *
-   * @example React Server Components
-   *
-   * ```tsx
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default async function Home() {
-   *   const session = await monoCloud.getSession();
-   *
-   *   return <div>{session?.user.name}</div>;
-   * }
-   * ```
-   *
-   * @example Server Action
-   *
-   * ```typescript
-   * "use server";
-   *
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export async function getUserAction() {
-   *   const session = await monoCloud.getSession();
-   *
-   *   return { name: session?.user.name };
-   * }
-   * ```
-   *
+   * @see {@link getSession} for full docs and examples.
+   * @returns Returns the resolved session, or `undefined` if none exists.
    */
   getSession(): Promise<MonoCloudSession$1 | undefined>;
   /**
-   * ## Middleware/Proxy or Route Handlers
-   *
-   * Retrieves the session object for the currently authenticated user on the server.
-   *
-   * **Use Case:**
-   * - Middleware (for both App and Pages Router).
-   * - App Router Route Handlers (API routes).
-   * - Edge functions.
-   *
-   * *Note: If the session cannot be resolved or an underlying error occurs, the promise rejects with an error.*
-   *
-   * @param req NextRequest
-   * @param res An optional `NextResponse` instance. Pass this if you have already initialized a response; otherwise, omit this parameter.
-   *
-   * @returns `MonoCloudSession` if found, or `undefined`.
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextRequest, NextResponse } from "next/server";
-   *
-   * export default async function middleware(req: NextRequest) {
-   *   const session = await monoCloud.getSession(req);
-   *
-   *   if (!session) {
-   *     return new NextResponse("User not signed in", { status: 401 });
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example Middleware/Proxy (Custom Response)
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextRequest, NextResponse } from "next/server";
-   *
-   * export default async function middleware(req: NextRequest) {
-   *   const res = NextResponse.next();
-   *
-   *   const session = await monoCloud.getSession(req, res);
-   *
-   *   if (!session) {
-   *     return new NextResponse("User not signed in", { status: 401 });
-   *   }
-   *
-   *   res.headers.set("x-auth-status", "active");
-   *
-   *   return res;
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example API Handler
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const session = await monoCloud.getSession(req);
-   *
-   *   return NextResponse.json({ name: session?.user.name });
-   * };
-   * ```
-   *
-   * @example API Handler with NextResponse
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const res = new NextResponse("YOUR CUSTOM RESPONSE");
-   *
-   *   const session = await monoCloud.getSession(req, res);
-   *
-   *   if (session?.user) {
-   *     res.cookies.set("something", "important");
-   *   }
-   *
-   *   return res;
-   * };
-   * ```
+   * @see {@link getSession} for full docs and examples.
+   * @param req Incoming request used to read authentication cookies and headers to resolve the current user's session.
+   * @param res Optional response to update if session resolution requires refreshed authentication cookies or headers.
+   * @returns Returns the resolved session, or `undefined` if none exists.
    */
   getSession(req: NextRequest | Request, res?: NextResponse | Response): Promise<MonoCloudSession$1 | undefined>;
   /**
-   * ## Pages Router (Node.js Runtime)
-   *
-   * Retrieves the session object for the currently authenticated user on the server.
-   *
-   * *Note: If the session cannot be resolved or an underlying error occurs, the promise rejects with an error.*
-   *
-   * @param req NextApiRequest
-   * @param res NextApiResponse
-   *
-   * @returns `MonoCloudSession` if found, or `undefined`.
-   *
-   * @example API Handler
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { NextApiRequest, NextApiResponse } from "next";
-   *
-   * type Data = {
-   *   name?: string;
-   * };
-   *
-   * export default async function handler(
-   *   req: NextApiRequest,
-   *   res: NextApiResponse<Data>
-   * ) {
-   *   const session = await monoCloud.getSession(req, res);
-   *
-   *   res.status(200).json({ name: session?.user.name });
-   * }
-   * ```
-   *
-   * @example SSR Component
-   *
-   * ```typescript
-   * import { monoCloud } from "@/monocloud";
-   * import type {
-   *   GetServerSideProps,
-   *   GetServerSidePropsContext,
-   *   InferGetServerSidePropsType,
-   * } from "next";
-   *
-   * type HomeProps = InferGetServerSidePropsType<typeof getServerSideProps>;
-   *
-   * export default function Home({ session }: HomeProps) {
-   *   return <pre>Session: {JSON.stringify(session, null, 2)}</pre>;
-   * }
-   *
-   * export const getServerSideProps = (async (
-   *   context: GetServerSidePropsContext,
-   * ) => {
-   *   const session = await monoCloud.getSession(
-   *     context.req,
-   *     context.res,
-   *   );
-   *
-   *   return {
-   *     props: {
-   *       session: session ?? null,
-   *     },
-   *   };
-   * }) satisfies GetServerSideProps;
-   * ```
+   * @see {@link getSession} for full docs and examples.
+   * @param req Incoming Node.js request used to read authentication cookies and resolve the current user's session.
+   * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.
+   * @returns Returns the resolved session, or `undefined` if none exists.
    */
   getSession(req: NextApiRequest | IncomingMessage, res: NextApiResponse | ServerResponse<IncomingMessage>): Promise<MonoCloudSession$1 | undefined>;
   /**
-   * ## SSR Components, Actions, Middleware or API Handlers
-   *
-   * Retrieves the tokens for the currently signed-in user. Optionally refreshes/fetches new tokens.
-   *
-   * **Use Case:**
-   * - App Router Server Components (RSC).
-   * - Server Actions
-   * - Route Handlers (App Router only).
-   * - Middleware (App Router and Pages Router).
-   *
-   * @param options Configuration options for token retrieval.
-   *
-   * @returns
-   *
-   * @throws {@link MonoCloudValidationError} If session is not found
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextResponse } from "next/server";
-   *
-   * export default async function middleware() {
-   *   const tokens = await monoCloud.getTokens();
-   *
-   *   if (tokens.isExpired) {
-   *     return new NextResponse("Tokens expired", { status: 401 });
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example App Router API Handler
-   *
-   * ```typescript
-   * import { NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async () => {
-   *   const tokens = await monoCloud.getTokens();
-   *
-   *   return NextResponse.json({ expired: tokens.isExpired });
-   * };
-   * ```
-   *
-   * @example React Server Components
-   *
-   * ```tsx
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default async function Home() {
-   *   const tokens = await monoCloud.getTokens();
-   *
-   *   return <div>Expired: {tokens.isExpired.toString()}</div>;
-   * }
-   * ```
-   *
-   * @example Server Action
-   *
-   * ```typescript
-   * "use server";
-   *
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export async function getExpiredAction() {
-   *   const tokens = await monoCloud.getTokens();
-   *
-   *   return { expired: tokens.isExpired };
-   * }
-   * ```
-   *
-   * @example Refresh Default Token
-   *
-   *  The default token is an access token with scopes set through `MONOCLOUD_AUTH_SCOPES` or
-   * `options.defaultAuthParams.scopes`, and resources set through `MONOCLOUD_AUTH_RESOURCE` or
-   * `options.defaultAuthParams.resource`. This token is refreshed when calling getTokens without resource and scopes parameters.
-   *
-   * ```typescript
-   * import { NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async () => {
-   * // Although the token refreshes automatically upon expiration, we are manually refreshing it here.
-   * const tokens = await monoCloud.getTokens({ forceRefresh: true });
-   *
-   * return NextResponse.json({ accessToken: tokens?.accessToken });
-   * };
-   * ```
-   *
-   * @example Request new access token for resource(s)
-   *
-   * **Note: Ensure that the resources and scopes are included in the initial authorization flow**
-   *
-   * The following example shows how to request a new token scoped to two non-exclusive resources.
-   *
-   * ```typescript
-   * import { NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async () => {
-   *   const tokens = await monoCloud.getTokens({
-   *     resource: "https://first.example.com https://second.example.com",
-   *     scopes: "read:first read:second shared",
-   *   });
-   *
-   *   return NextResponse.json({ accessToken: tokens?.accessToken });
-   * };
-   * ```
-   *
-   * @example Request an exclusive token
-   *
-   * **Note: Ensure that the resources and scopes are included in the initial authorization flow**
-   *
-   * ```typescript
-   * import { NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async () => {
-   *   const tokens = await monoCloud.getTokens({
-   *     resource: "https://exclusive.example.com",
-   *     scopes: "read:exclusive shared",
-   *   });
-   *
-   *   return NextResponse.json({ accessToken: tokens?.accessToken });
-   * };
-   * ```
+   * @see {@link getTokens} for full docs and examples.
+   * @param options Optional configuration controlling refresh behavior and resource/scope selection.
+   * @returns The current user's tokens, refreshed if necessary.
+   * @throws {@link MonoCloudValidationError} If no valid session exists.
    */
   getTokens(options?: GetTokensOptions$1): Promise<MonoCloudTokens$1>;
   /**
-   * ## Middleware/Proxy or Route Handlers
-   *
-   * Retrieves the tokens for the currently signed-in user. Optionally refreshes/fetches new tokens.
-   *
-   * **Use Case:**
-   * - Middleware (for both App and Pages Router).
-   * - App Router Route Handlers (API routes).
-   * - Edge functions.
-   *
-   * @param req NextRequest
-   * @param options Configuration options for token retrieval.
-   *
-   * @returns
-   *
-   * @throws {@link MonoCloudValidationError} If session is not found
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextRequest, NextResponse } from "next/server";
-   *
-   * export default async function middleware(req: NextRequest) {
-   *   const tokens = await monoCloud.getTokens(req);
-   *
-   *   if (tokens.isExpired) {
-   *     return new NextResponse("Tokens expired", { status: 401 });
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example App Router API Handler
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const tokens = await monoCloud.getTokens(req);
-   *
-   *   return NextResponse.json({ expired: tokens?.isExpired });
-   * };
-   * ```
-   *
-   * @example Refresh Default Token
-   *
-   *  The default token is an access token with scopes set through `MONOCLOUD_AUTH_SCOPES` or
-   * `options.defaultAuthParams.scopes`, and resources set through `MONOCLOUD_AUTH_RESOURCE` or
-   * `options.defaultAuthParams.resource`. This token is refreshed when calling getTokens without parameters.
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   // Although the token refreshes automatically upon expiration, we are manually refreshing it here.
-   *   const tokens = await monoCloud.getTokens(req, { forceRefresh: true });
-   *
-   *   return NextResponse.json({ accessToken: tokens?.accessToken });
-   * };
-   * ```
-   *
-   * @example Request new access token for resource(s)
-   *
-   * **Note: Ensure that the resources and scopes are included in the initial authorization flow**
-   *
-   * The following example shows how to request a new token scoped to two non-exclusive resources.
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const tokens = await monoCloud.getTokens(req, {
-   *     resource: "https://first.example.com https://second.example.com",
-   *     scopes: "read:first read:second shared",
-   *   });
-   *
-   *   return NextResponse.json({ accessToken: tokens?.accessToken });
-   * };
-   * ```
-   *
-   * @example Request an exclusive token
-   *
-   * **Note: Ensure that the resources and scopes are included in the initial authorization flow**
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const tokens = await monoCloud.getTokens(req, {
-   *     resource: "https://exclusive.example.com",
-   *     scopes: "read:exclusive shared",
-   *   });
-   *
-   *   return NextResponse.json({ accessToken: tokens?.accessToken });
-   * };
-   * ```
+   * @see {@link getTokens} for full docs and examples.
+   * @param req Incoming request used to resolve authentication from cookies and headers.
+   * @param options Optional configuration controlling refresh behavior and resource/scope selection.
+   * @returns The current user's tokens, refreshed if necessary.
+   * @throws {@link MonoCloudValidationError} If no valid session exists.
    */
   getTokens(req: NextRequest | Request, options?: GetTokensOptions$1): Promise<MonoCloudTokens$1>;
   /**
-   * ## Middleware/Proxy or Route Handlers (Custom Response)
-   *
-   * Retrieves the tokens for the currently signed-in user. Optionally refreshes/fetches new tokens and updates the provided response object.
-   *
-   * **Use Case:**
-   * - Middleware (when modifying the response).
-   * - App Router Route Handlers (when a NextResponse is already initialized).
-   *
-   * @param req NextRequest
-   * @param res An optional `NextResponse` instance. Pass this if you have already initialized a response and want token updates (e.g., refreshing) to be applied to it.
-   * @param options Configuration options for token retrieval.
-   *
-   * @returns
-   *
-   * @throws {@link MonoCloudValidationError} If session is not found
-   *
-   * @example Middleware/Proxy
-   *
-   *```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextRequest, NextResponse } from "next/server";
-   *
-   * export default async function middleware(req: NextRequest) {
-   *   const res = NextResponse.next();
-   *
-   *   const tokens = await monoCloud.getTokens(req, res);
-   *
-   *   res.headers.set("x-tokens-expired", tokens.isExpired.toString());
-   *
-   *   return res;
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example API Handler with NextResponse
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const res = new NextResponse("Custom Body");
-   *
-   *   const tokens = await monoCloud.getTokens(req, res);
-   *
-   *   if (!tokens.isExpired) {
-   *     res.headers.set("x-auth-status", "active");
-   *   }
-   *
-   *   return res;
-   * };
-   * ```
-   *
-   * @example Refresh Default Token
-   *
-   * The default token is an access token with scopes set through `MONOCLOUD_AUTH_SCOPES` or
-   * `options.defaultAuthParams.scopes`, and resources set through `MONOCLOUD_AUTH_RESOURCE` or
-   * `options.defaultAuthParams.resource`. This token is refreshed when calling getTokens without parameters.
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const res = new NextResponse("Custom Body");
-   *
-   *   // Although the token refreshes automatically upon expiration, we are manually refreshing it here.
-   *   const tokens = await monoCloud.getTokens(req, res, { forceRefresh: true });
-   *
-   *   if (!tokens.isExpired) {
-   *     res.headers.set("x-auth-status", "active");
-   *   }
-   *
-   *   return res;
-   * };
-   * ```
-   *
-   * @example Request new access token for resource(s)
-   *
-   * **Note: Ensure that the resources and scopes are included in the initial authorization flow**
-   *
-   * The following example shows how to request a new token scoped to two non-exclusive resources.
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const res = new NextResponse("Custom Body");
-   *
-   *   const tokens = await monoCloud.getTokens(req, res, {
-   *     resource: "https://first.example.com https://second.example.com",
-   *     scopes: "read:first read:second shared",
-   *   });
-   *
-   *   if (!tokens.isExpired) {
-   *     res.headers.set("x-auth-status", "active");
-   *   }
-   *
-   *   return res;
-   * };
-   * ```
-   *
-   * @example Request an exclusive token
-   *
-   * **Note: Ensure that the resources and scopes are included in the initial authorization flow**
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const res = new NextResponse("Custom Body");
-   *
-   *   const tokens = await monoCloud.getTokens(req, res, {
-   *     resource: "https://exclusive.example.com",
-   *     scopes: "read:exclusive shared",
-   *   });
-   *
-   *   if (!tokens.isExpired) {
-   *     res.headers.set("x-auth-status", "active");
-   *   }
-   *
-   *   return res;
-   * };
-   * ```
+   * @see {@link getTokens} for full docs and examples.
+   * @param req Incoming request used to resolve authentication from cookies and headers.
+   * @param res Existing response to update with refreshed authentication cookies or headers.
+   * @param options Optional configuration controlling refresh behavior and resource/scope selection.
+   * @returns The current user's tokens, refreshed if necessary.
+   * @throws {@link MonoCloudValidationError} If no valid session exists.
    */
   getTokens(req: NextRequest | Request, res: NextResponse | Response, options?: GetTokensOptions$1): Promise<MonoCloudTokens$1>;
   /**
-   * ## Pages Router (Node.js Runtime)
-   *
-   * Retrieves the tokens for the currently signed-in user. Optionally refreshes/fetches new tokens.
-   *
-   * @param req The `NextApiRequest` or `IncomingMessage`.
-   * @param res The `NextApiResponse` or `ServerResponse`.
-   * @param options Configuration options for token retrieval.
-   *
-   * @returns
-   *
-   * @throws {@link MonoCloudValidationError} If session is not found
-   *
-   * @example API Route
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { NextApiRequest, NextApiResponse } from "next";
-   *
-   * export default async function handler(
-   *   req: NextApiRequest,
-   *   res: NextApiResponse
-   * ) {
-   *   const tokens = await monoCloud.getTokens(req, res);
-   *
-   *   res.status(200).json({ accessToken: tokens?.accessToken });
-   * }
-   * ```
-   *
-   * @example SSR Component
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { GetServerSideProps, InferGetServerSidePropsType } from "next";
-   *
-   * type HomeProps = InferGetServerSidePropsType<typeof getServerSideProps>;
-   *
-   * export default function Home({ tokens }: HomeProps) {
-   *   return <pre>Tokens: {JSON.stringify(tokens, null, 2)}</pre>;
-   * }
-   *
-   * export const getServerSideProps: GetServerSideProps = async (context) => {
-   *   const tokens = await monoCloud.getTokens(context.req, context.res);
-   *
-   *   return {
-   *     props: {
-   *       tokens: tokens ?? null,
-   *     },
-   *   };
-   * };
-   * ```
-   *
-   * @example Refresh Default Token
-   *
-   *  The default token is an access token with scopes set through `MONOCLOUD_AUTH_SCOPES` or
-   * `options.defaultAuthParams.scopes`, and resources set through `MONOCLOUD_AUTH_RESOURCE` or
-   * `options.defaultAuthParams.resource`. This token is refreshed when calling getTokens without parameters.
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { NextApiRequest, NextApiResponse } from "next";
-   *
-   * export default async function handler(
-   *   req: NextApiRequest,
-   *   res: NextApiResponse
-   * ) {
-   *   // Although the token refreshes automatically upon expiration, we are manually refreshing it here.
-   *   const tokens = await monoCloud.getTokens(req, res, { forceRefresh: true });
-   *
-   *   res.status(200).json({ accessToken: tokens?.accessToken });
-   * }
-   * ```
-   *
-   * @example Request new access token for resource(s)
-   *
-   *  **Note: Ensure that the resources and scopes are included in the initial authorization flow**
-   *
-   *  The following example shows how to request a new token scoped to two non-exclusive resources.
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { NextApiRequest, NextApiResponse } from "next";
-   *
-   * export default async function handler(
-   *   req: NextApiRequest,
-   *   res: NextApiResponse
-   * ) {
-   *   const tokens = await monoCloud.getTokens(req, res, {
-   *     resource: "https://first.example.com https://second.example.com",
-   *     scopes: "read:first read:second shared",
-   *   });
-   *
-   *   res.status(200).json({ accessToken: tokens?.accessToken });
-   * }
-   * ```
-   *
-   * @example Request an exclusive token
-   *
-   *  **Note: Ensure that the resources and scopes are included in the initial authorization flow**
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { NextApiRequest, NextApiResponse } from "next";
-   *
-   * export default async function handler(
-   *   req: NextApiRequest,
-   *   res: NextApiResponse
-   * ) {
-   *   const tokens = await monoCloud.getTokens(req, res, {
-   *     resource: "https://exclusive.example.com",
-   *     scopes: "read:exclusive shared",
-   *   });
-   *
-   *   res.status(200).json({ accessToken: tokens?.accessToken });
-   * }
-   * ```
+   * @see {@link getTokens} for full docs and examples.
+   * @param req Incoming Node.js request used to resolve authentication from cookies.
+   * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.
+   * @param options Optional configuration controlling refresh behavior and resource/scope selection.
+   * @returns The current user's tokens, refreshed if necessary.
+   * @throws {@link MonoCloudValidationError} If no valid session exists.
    */
   getTokens(req: NextApiRequest | IncomingMessage, res: NextApiResponse | ServerResponse<IncomingMessage>, options?: GetTokensOptions$1): Promise<MonoCloudTokens$1>;
   /**
-   * ## SSR Components, Actions, Middleware or API Handlers
-   *
-   * Checks if the current user is authenticated.
-   *
-   * **Use Case:**
-   * - App Router Server Components (RSC).
-   * - Server Actions
-   * - Route Handlers (App Router only).
-   * - Middleware (App Router and Pages Router).
-   *
-   * @returns `true` if the user is authenticated, otherwise `false`.
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextResponse } from "next/server";
-   *
-   * export default async function middleware() {
-   *   const authenticated = await monoCloud.isAuthenticated();
-   *
-   *   if (!authenticated) {
-   *     return new NextResponse("User not signed in", { status: 401 });
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example App Router API Handler
-   *
-   * ```typescript
-   * import { NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async () => {
-   *   const authenticated = await monoCloud.isAuthenticated();
-   *
-   *   return NextResponse.json({ authenticated });
-   * };
-   * ```
-   *
-   * @example React Server Components
-   *
-   * ```tsx
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default async function Home() {
-   *   const authenticated = await monoCloud.isAuthenticated();
-   *
-   *   return <div>Authenticated: {authenticated.toString()}</div>;
-   * }
-   * ```
-   *
-   * @example Server Action
-   *
-   * ```typescript
-   * "use server";
-   *
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export async function checkAuthAction() {
-   *   const authenticated = await monoCloud.isAuthenticated();
-   *
-   *   return { authenticated };
-   * }
-   * ```
+   * @see {@link isAuthenticated} for full docs and examples.
+   * @returns Returns `true` if a valid session exists; otherwise `false`.
    */
   isAuthenticated(): Promise<boolean>;
   /**
-   * ## Middleware/Proxy or Route Handlers
-   *
-   * Checks if the current user is authenticated.
-   *
-   * **Use Case:**
-   * - Middleware (for both App and Pages Router).
-   * - App Router Route Handlers (API routes).
-   * - Edge functions.
-   *
-   * @param req NextRequest
-   * @param res An optional `NextResponse` instance. Pass this if you have already initialized a response; otherwise, omit this parameter.
-   *
-   * @returns `true` if the user is authenticated, otherwise `false`.
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextRequest, NextResponse } from "next/server";
-   *
-   * export default async function middleware(req: NextRequest) {
-   *   const authenticated = await monoCloud.isAuthenticated(req);
-   *
-   *   if (!authenticated) {
-   *     return new NextResponse("User not signed in", { status: 401 });
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example Middleware/Proxy (Custom Response)
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextRequest, NextResponse } from "next/server";
-   *
-   * export default async function middleware(req: NextRequest) {
-   *   const res = NextResponse.next();
-   *
-   *   const authenticated = await monoCloud.isAuthenticated(req, res);
-   *
-   *   if (!authenticated) {
-   *     return new NextResponse("User not signed in", { status: 401 });
-   *   }
-   *
-   *   res.headers.set("x-authenticated", "true");
-   *
-   *   return res;
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example API Handler
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const authenticated = await monoCloud.isAuthenticated(req);
-   *
-   *   return NextResponse.json({ authenticated });
-   * };
-   * ```
-   *
-   * @example API Handler with NextResponse
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const res = new NextResponse("YOUR CUSTOM RESPONSE");
-   *
-   *   const authenticated = await monoCloud.isAuthenticated(req, res);
-   *
-   *   if (authenticated) {
-   *     res.cookies.set("something", "important");
-   *   }
-   *
-   *   return res;
-   * };
-   * ```
+   * @see {@link isAuthenticated} for full docs and examples.
+   * @param req Incoming request used to resolve authentication from cookies and headers.
+   * @param res Optional response to update if refreshed authentication cookies or headers are required.
+   * @returns Returns `true` if a valid session exists; otherwise `false`.
    */
   isAuthenticated(req: NextRequest | Request, res?: NextResponse | Response): Promise<boolean>;
   /**
-   * ## Pages Router (Node.js Runtime)
-   *
-   * Checks if the current user is authenticated.
-   *
-   * @param req NextApiRequest
-   * @param res NextApiResponse
-   *
-   * @returns `true` if the user is authenticated, otherwise `false`.
-   *
-   * @example API Handler
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { NextApiRequest, NextApiResponse } from "next";
-   *
-   * type Data = {
-   *   authenticated: boolean;
-   * };
-   *
-   * export default async function handler(
-   *   req: NextApiRequest,
-   *   res: NextApiResponse<Data>
-   * ) {
-   *   const authenticated = await monoCloud.isAuthenticated(req, res);
-   *
-   *   res.status(200).json({ authenticated });
-   * }
-   * ```
-   *
-   * @example SSR Component
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { GetServerSideProps, InferGetServerSidePropsType } from "next";
-   *
-   * type HomeProps = InferGetServerSidePropsType<typeof getServerSideProps>;
-   *
-   * export default function Home({ authenticated }: HomeProps) {
-   *   return <pre>User is {authenticated ? "logged in" : "guest"}</pre>;
-   * }
-   *
-   * export const getServerSideProps: GetServerSideProps = async (context) => {
-   *   const authenticated = await monoCloud.isAuthenticated(
-   *     context.req,
-   *     context.res
-   *   );
-   *
-   *   return {
-   *     props: {
-   *       authenticated,
-   *     },
-   *   };
-   * };
-   * ```
+   * @see {@link isAuthenticated} for full docs and examples.
+   * @param req Incoming Node.js request used to resolve authentication from cookies.
+   * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.
+   * @returns Returns `true` if a valid session exists; otherwise `false`.
    */
   isAuthenticated(req: NextApiRequest | IncomingMessage, res: NextApiResponse | ServerResponse<IncomingMessage>): Promise<boolean>;
   /**
-   * 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.
    */
   protect(options?: ProtectOptions): Promise<void>;
   /**
-   * ## SSR Components, Actions, Middleware or API Handlers
-   *
-   * Checks if the currently authenticated user is a member of any of the specified groups.
-   *
-   * **Use Case:**
-   * - App Router Server Components (RSC).
-   * - Server Actions
-   * - Route Handlers (App Router only).
-   * - Middleware (App Router and Pages Router).
-   *
-   * @param groups A list of group names or IDs to check against the user's group memberships.
-   * @param options Configuration options.
-   *
-   * @returns
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextResponse } from "next/server";
-   *
-   * export default async function middleware() {
-   *   const isAdmin = await monoCloud.isUserInGroup(["admin"]);
-   *
-   *   if (!isAdmin) {
-   *     return new NextResponse("User is not admin", { status: 403 });
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example App Router API Handler
-   *
-   * ```typescript
-   * import { NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async () => {
-   *   const allowed = await monoCloud.isUserInGroup(["admin", "editor"]);
-   *
-   *   if (!allowed) {
-   *     return new NextResponse("Forbidden", { status: 403 });
-   *   }
-   *
-   *   return NextResponse.json({ status: "success" });
-   * };
-   * ```
-   *
-   * @example React Server Components
-   *
-   * ```tsx
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export default async function AdminPanel() {
-   *   const isAdmin = await monoCloud.isUserInGroup(["admin"]);
-   *
-   *   if (!isAdmin) {
-   *     return <div>Access Denied</div>;
-   *   }
-   *
-   *   return <div>Admin Control Panel</div>;
-   * }
-   * ```
-   *
-   * @example Server Action
-   *
-   * ```typescript
-   * "use server";
-   *
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export async function deletePostAction() {
-   *   const canDelete = await monoCloud.isUserInGroup(["admin", "editor"]);
-   *
-   *   if (!canDelete) {
-   *     return { success: false };
-   *   }
-   *
-   *   return { success: true };
-   * }
-   * ```
+   * @see {@link isUserInGroup} for full docs and examples.
+   * @param groups Group IDs or names to check against the user's group memberships.
+   * @param options Optional configuration controlling how group membership is evaluated.
+   * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.
    */
   isUserInGroup(groups: string[], options?: IsUserInGroupOptions): Promise<boolean>;
   /**
-   * ## Middleware/Proxy or Route Handlers
-   *
-   * Checks if the currently authenticated user is a member of any of the specified groups.
-   *
-   * **Use Case:**
-   * - Middleware (for both App and Pages Router).
-   * - App Router Route Handlers (API routes).
-   * - Edge functions.
-   *
-   * @param req NextRequest
-   * @param groups A list of group names or IDs to check against the user's group memberships.
-   * @param options Configuration options.
-   *
-   * @returns
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextRequest, NextResponse } from "next/server";
-   *
-   * export default async function middleware(req: NextRequest) {
-   *   const isAdmin = await monoCloud.isUserInGroup(req, ["admin"]);
-   *
-   *   if (!isAdmin) {
-   *     return new NextResponse("User is not admin", { status: 403 });
-   *   }
-   *
-   *   return NextResponse.next();
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example App Router API Handler
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const isMember = await monoCloud.isUserInGroup(req, ["admin", "editor"]);
-   *
-   *   return NextResponse.json({ isMember });
-   * };
-   * ```
+   * @see {@link isUserInGroup} for full docs and examples.
+   * @param req Incoming request used to resolve authentication from cookies and headers.
+   * @param groups Group IDs or names to check against the user's group memberships.
+   * @param options Optional configuration controlling how group membership is evaluated.
+   * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.
    */
   isUserInGroup(req: NextRequest | Request, groups: string[], options?: IsUserInGroupOptions): Promise<boolean>;
   /**
-   * ## Middleware/Proxy or Route Handlers (Custom Response)
-   *
-   * Checks if the currently authenticated user is a member of any of the specified groups.
-   *
-   * **Use Case:**
-   * - Middleware (when modifying the response).
-   * - App Router Route Handlers (when a NextResponse is already initialized).
-   *
-   * @param req NextRequest
-   * @param res An optional `NextResponse` instance. Pass this if you have already initialized a response and want token updates to be applied to it.
-   * @param groups A list of group names or IDs to check against the user's group memberships.
-   * @param options Configuration options.
-   *
-   * @returns
-   *
-   * @example Middleware/Proxy
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import { NextRequest, NextResponse } from "next/server";
-   *
-   * export default async function middleware(req: NextRequest) {
-   *   const res = NextResponse.next();
-   *
-   *   const isAdmin = await monoCloud.isUserInGroup(req, res, ["admin"]);
-   *
-   *   if (!isAdmin) {
-   *     return new NextResponse("User is not admin", { status: 403 });
-   *   }
-   *
-   *   res.headers.set("x-user", "admin");
-   *
-   *   return res;
-   * }
-   *
-   * export const config = {
-   *   matcher: [
-   *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
-   *   ],
-   * };
-   * ```
-   *
-   * @example API Handler with NextResponse
-   *
-   * ```typescript
-   * import { NextRequest, NextResponse } from "next/server";
-   * import { monoCloud } from "@/lib/monocloud";
-   *
-   * export const GET = async (req: NextRequest) => {
-   *   const res = new NextResponse("Restricted Content");
-   *
-   *   const allowed = await monoCloud.isUserInGroup(req, res, ["admin"]);
-   *
-   *   if (!allowed) {
-   *     return new NextResponse("Not Allowed", res);
-   *   }
-   *
-   *   return res;
-   * };
-   * ```
+   * @see {@link isUserInGroup} for full docs and examples.
+   * @param req Incoming request used to resolve authentication from cookies and headers.
+   * @param res Existing response to update with refreshed authentication cookies or headers when required.
+   * @param groups Group IDs or names to check against the user's group memberships.
+   * @param options Optional configuration controlling how group membership is evaluated.
+   * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.
    */
   isUserInGroup(req: NextRequest | Request, res: NextResponse | Response, groups: string[], options?: IsUserInGroupOptions): Promise<boolean>;
   /**
-   * ## Pages Router (Node.js Runtime)
-   *
-   * Checks if the currently authenticated user is a member of any of the specified groups.
-   *
-   * @param req The `NextApiRequest` or `IncomingMessage`.
-   * @param res The `NextApiResponse` or `ServerResponse`.
-   * @param groups A list of group names or IDs to check against the user's group memberships.
-   * @param options Configuration options.
-   *
-   * @returns
-   *
-   * @example API Route
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { NextApiRequest, NextApiResponse } from "next";
-   *
-   * export default async function handler(
-   *   req: NextApiRequest,
-   *   res: NextApiResponse
-   * ) {
-   *   const isAdmin = await monoCloud.isUserInGroup(req, res, ["admin"]);
-   *
-   *   if (!isAdmin) {
-   *     return res.status(403).json({ error: "Forbidden" });
-   *   }
-   *
-   *   res.status(200).json({ message: "Welcome Admin" });
-   * }
-   * ```
-   *
-   * @example SSR Component
-   *
-   * ```typescript
-   * import { monoCloud } from "@/lib/monocloud";
-   * import type { GetServerSideProps, InferGetServerSidePropsType } from "next";
-   *
-   * type HomeProps = InferGetServerSidePropsType<typeof getServerSideProps>;
-   *
-   * export default function Home({ isAdmin }: HomeProps) {
-   *   return <div>User is admin: {isAdmin.toString()}</div>;
-   * }
-   *
-   * export const getServerSideProps: GetServerSideProps = async (context) => {
-   *   const isAdmin = await monoCloud.isUserInGroup(context.req, context.res, [
-   *     "admin",
-   *   ]);
-   *
-   *   return {
-   *     props: {
-   *       isAdmin,
-   *     },
-   *   };
-   * };
-   * ```
+   * @see {@link isUserInGroup} for full docs and examples.
+   * @param req Incoming Node.js request used to resolve authentication from cookies.
+   * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.
+   * @param groups Group IDs or names to check against the user's group memberships.
+   * @param options Optional configuration controlling how group membership is evaluated.
+   * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.
    */
   isUserInGroup(req: NextApiRequest | IncomingMessage, res: NextApiResponse | ServerResponse<IncomingMessage>, groups: string[], options?: IsUserInGroupOptions): Promise<boolean>;
   /**
-   * 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.
    */
   redirectToSignIn(options?: RedirectToSignInOptions): Promise<void>;
   /**
-   * 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.
    */
   redirectToSignOut(options?: RedirectToSignOutOptions): Promise<void>;
   private getOptions;
   private registerPublicEnvVariables;
 }
 //#endregion
-export { type AccessToken, type AppRouterApiOnAccessDeniedHandler, type ExtraAuthParams, type GetTokensOptions, type GroupOptions, type IsUserInGroupOptions, MonoCloudAuthBaseError, type MonoCloudAuthOptions, MonoCloudHttpError, type MonoCloudMiddlewareOptions, MonoCloudNextClient, MonoCloudOPError, type MonoCloudOptions, type MonoCloudSession, MonoCloudTokenError, type MonoCloudTokens, type MonoCloudUser, MonoCloudValidationError, type PageRouterApiOnAccessDeniedHandler, type ProtectApiAppOptions, type ProtectApiPageOptions, type ProtectAppPageOptions, type ProtectOptions, type ProtectPagePageOnAccessDeniedType, type ProtectPagePageOptions, type ProtectPagePageReturnType, type RedirectToSignInOptions, type RedirectToSignOutOptions };
+//#region src/initialize.d.ts
+/**
+ * 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
+ */
+declare function monoCloudAuth(options?: MonoCloudAuthOptions): MonoCloudAuthHandler;
+/**
+ * Creates a Next.js authentication middleware that protects routes.
+ *
+ * By default, all routes matched by `config.matcher` are protected unless configured otherwise.
+ *
+ * @example Protect All Routes
+ * ```tsx:src/proxy.ts tab="Protect All Routes" tab-group="auth-middleware"
+ * import { authMiddleware } from "@monocloud/auth-nextjs";
+ *
+ * export default authMiddleware();
+ *
+ * export const config = {
+ *   matcher: [
+ *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
+ *   ],
+ * };
+ * ```
+ *
+ * @example Protect Selected Routes
+ * ```tsx:src/proxy.ts tab="Protect Selected Routes" tab-group="auth-middleware"
+ * import { authMiddleware } from "@monocloud/auth-nextjs";
+ *
+ * export default authMiddleware({
+ *   protectedRoutes: ["/api/admin", "^/api/protected(/.*)?$"],
+ * });
+ *
+ * export const config = {
+ *   matcher: [
+ *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
+ *   ],
+ * };
+ *```
+ *
+ * @example No Protected Routes
+ * ```tsx:src/proxy.ts tab="No Protected Routes" tab-group="auth-middleware"
+ * import { authMiddleware } from "@monocloud/auth-nextjs";
+ *
+ * export default authMiddleware({
+ *   protectedRoutes: [],
+ * });
+ *
+ * export const config = {
+ *   matcher: [
+ *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
+ *   ],
+ * };
+ * ```
+ *
+ * @example Dynamic
+ * ```tsx:src/proxy.ts tab="Dynamic" tab-group="auth-middleware"
+ * import { authMiddleware } from "@monocloud/auth-nextjs";
+ *
+ * export default authMiddleware({
+ *   protectedRoutes: (req) => {
+ *     return req.nextUrl.pathname.startsWith("/api/protected");
+ *   },
+ * });
+ *
+ * export const config = {
+ *   matcher: [
+ *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
+ *   ],
+ * };
+ * ```
+ *
+ * @example Group Protection
+ * ```tsx:src/proxy.ts tab="Group Protection" tab-group="auth-middleware"
+ * import { authMiddleware } from "@monocloud/auth-nextjs";
+ *
+ * export default authMiddleware({
+ *   protectedRoutes: [
+ *     {
+ *       groups: ["admin", "editor", "537e7c3d-a442-4b5b-b308-30837aa045a4"],
+ *       routes: ["/internal", "/api/internal(.*)"],
+ *     },
+ *   ],
+ * });
+ *
+ * export const config = {
+ *   matcher: [
+ *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
+ *   ],
+ * };
+ * ```
+ *
+ * @param options Optional configuration that controls how authentication is enforced (for example, redirect behavior, route matching, or custom handling of unauthenticated requests).
+ * @returns Returns a Next.js middleware result, such as a NextResponse, redirect, or undefined to continue processing.
+ *
+ * @category Functions
+ */
+declare function authMiddleware(options?: MonoCloudMiddlewareOptions): NextMiddleware$1 | NextProxy$1;
+/**
+ * Executes the authentication middleware manually.
+ *
+ * Intended for advanced scenarios where the middleware is composed within custom logic.
+ *
+ * @example Composing with custom middleware
+ *
+ * ```tsx:src/proxy.ts title="Composing with custom middleware"
+ * import { authMiddleware } from "@monocloud/auth-nextjs";
+ * import { NextFetchEvent, NextRequest, NextResponse } from "next/server";
+ *
+ * export default function customMiddleware(req: NextRequest, evt: NextFetchEvent) {
+ *   if (req.nextUrl.pathname.startsWith("/api/protected")) {
+ *     return authMiddleware(req, evt);
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ *
+ * export const config = {
+ *   matcher: [
+ *     "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
+ *   ],
+ * };
+ * ```
+ *
+ * @param request Incoming Next.js middleware request used to resolve authentication state.
+ * @param event Next.js middleware event providing lifecycle hooks such as `waitUntil`.
+ * @returns Returns a Next.js middleware result (`NextResponse`, redirect, or `undefined` to continue processing).
+ *
+ * @category Functions
+ */
+declare function authMiddleware(request: NextRequest$1, event: NextFetchEvent$1): Promise<NextMiddlewareResult> | NextMiddlewareResult;
+/**
+ * Retrieves the current user's session using the active server request context.
+ *
+ * Intended for Server Components, Server Actions, Route Handlers, and Middleware where the request is implicitly available.
+ *
+ * @example Server Component
+ * ```tsx:src/app/page.tsx tab="Server Component" tab-group="session-ssr"
+ * import { getSession } from "@monocloud/auth-nextjs";
+ *
+ * export default async function Home() {
+ *   const session = await getSession();
+ *
+ *   return <div>{session?.user.name}</div>;
+ * }
+ * ```
+ *
+ * @example Server Action
+ * ```tsx:src/action.ts tab="Server Action" tab-group="session-ssr"
+ * "use server";
+ *
+ * import { getSession } from "@monocloud/auth-nextjs";
+ *
+ * export async function getUserAction() {
+ *   const session = await getSession();
+ *
+ *   return { name: session?.user.name };
+ * }
+ * ```
+ *
+ * @example API Handler
+ * ```tsx:src/app/api/user/route.ts tab="API Handler" tab-group="session-ssr"
+ * import { getSession } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export const GET = async () => {
+ *   const session = await getSession();
+ *
+ *   return NextResponse.json({ name: session?.user.name });
+ * };
+ * ```
+ *
+ * @example Middleware
+ * ```tsx:src/proxy.ts tab="Middleware" tab-group="session-ssr"
+ * import { getSession } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export default async function proxy() {
+ *   const session = await getSession();
+ *
+ *   if (!session) {
+ *     return new NextResponse("User not signed in", { status: 401 });
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @returns Returns the resolved session, or `undefined` if none exists.
+ *
+ * @category Functions
+ */
+declare function getSession(): Promise<MonoCloudSession$2 | undefined>;
+/**
+ * Retrieves the current user's session using an explicit Web or Next.js request.
+ *
+ * Use this overload when you already have access to a `Request` or `NextRequest` (for example in Middleware or Route Handlers).
+ *
+ * @example Middleware (Request)
+ * ```tsx:src/proxy.ts tab="Middleware (Request)" tab-group="session-route-handler"
+ * import { getSession } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export default async function proxy(req: NextRequest) {
+ *   const session = await getSession(req);
+ *
+ *   if (!session) {
+ *     return new NextResponse("User not signed in", { status: 401 });
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @example Middleware (Response)
+ * ```tsx:src/proxy.ts tab="Middleware (Response)" tab-group="session-route-handler"
+ * import { getSession } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export default async function proxy(req: NextRequest) {
+ *   const res = NextResponse.next();
+ *
+ *   const session = await getSession(req, res);
+ *
+ *   if (!session) {
+ *     return new NextResponse("User not signed in", { status: 401 });
+ *   }
+ *
+ *   res.headers.set("x-auth-status", "active");
+ *
+ *   return res;
+ * }
+ * ```
+ *
+ * @example API Handler (Request)
+ * ```tsx:src/app/api/user/route.ts tab="API Handler (Request)" tab-group="session-route-handler"
+ * import { getSession } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export const GET = async (req: NextRequest) => {
+ *   const session = await getSession(req);
+ *
+ *   return NextResponse.json({ name: session?.user.name });
+ * };
+ * ```
+ *
+ * @example API Handler (Response)
+ * ```tsx:src/app/api/user/route.ts tab="API Handler (Response)" tab-group="session-route-handler"
+ * import { getSession } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export const GET = async (req: NextRequest) => {
+ *   const res = new NextResponse("YOUR CUSTOM RESPONSE");
+ *
+ *   const session = await getSession(req, res);
+ *
+ *   if (session?.user) {
+ *     res.cookies.set("something", "important");
+ *   }
+ *
+ *   return res;
+ * };
+ * ```
+ *
+ * @param req Incoming request used to read authentication cookies and headers to resolve the current user's session.
+ * @param res Optional response to update if session resolution requires refreshed authentication cookies or headers.
+ * @returns Returns the resolved session, or `undefined` if none exists.
+ *
+ * @category Functions
+ */
+declare function getSession(req: NextRequest$1 | Request, res?: NextResponse$1 | Response): Promise<MonoCloudSession$2 | undefined>;
+/**
+ * Retrieves the current user's session in the Pages Router or Node.js runtime.
+ *
+ * Use this overload in API routes or `getServerSideProps`, where Node.js request and response objects are available.
+ *
+ * @example Pages Router (Pages)
+ * ```tsx:src/pages/index.tsx tab="Pages Router (Pages)" tab-group="session-pages"
+ * import { getSession, MonoCloudSession } from "@monocloud/auth-nextjs";
+ * import { GetServerSideProps } from "next";
+ *
+ * type Props = {
+ *   session?: MonoCloudSession;
+ * };
+ *
+ * export default function Home({ session }: Props) {
+ *   return <pre>Session: {JSON.stringify(session, null, 2)}</pre>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {
+ *   const session = await getSession(ctx.req, ctx.res);
+ *
+ *   return {
+ *     props: {
+ *       session
+ *     }
+ *   };
+ * };
+ * ```
+ * @example Pages Router (API)
+ * ```tsx:src/pages/api/user.ts tab="Pages Router (API)" tab-group="session-pages"
+ * import { getSession } from "@monocloud/auth-nextjs";
+ * import { NextApiRequest, NextApiResponse } from "next";
+ *
+ * export default async function handler(
+ *   req: NextApiRequest,
+ *   res: NextApiResponse
+ * ) {
+ *   const session = await getSession(req, res);
+ *
+ *   res.status(200).json({ name: session?.user.name });
+ * }
+ * ```
+ *
+ * @param req Incoming Node.js request used to read authentication cookies and resolve the current user's session.
+ * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.
+ * @returns Returns the resolved session, or `undefined` if none exists.
+ *
+ * @category Functions
+ */
+declare function getSession(req: NextApiRequest$1 | IncomingMessage, res: NextApiResponse$1 | ServerResponse<IncomingMessage>): Promise<MonoCloudSession$2 | undefined>;
+/**
+ * Retrieves the current user's tokens using the active server request context.
+ *
+ * @example Server Component
+ * ```tsx:src/app/page.tsx tab="Server Component" tab-group="tokens-ssr"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ *
+ * export default async function Home() {
+ *   const tokens = await getTokens();
+ *
+ *   return <div>Expired: {tokens.isExpired.toString()}</div>;
+ * }
+ * ```
+ *
+ * @example Server Action
+ * ```tsx:src/action.ts tab="Server Action" tab-group="tokens-ssr"
+ * "use server";
+ *
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ *
+ * export async function getExpiredAction() {
+ *   const tokens = await getTokens();
+ *
+ *   return { expired: tokens.isExpired };
+ * }
+ * ```
+ *
+ * @example API Handler
+ * ```tsx:src/app/api/tokens/route.ts tab="API Handler" tab-group="tokens-ssr"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export const GET = async () => {
+ *   const tokens = await getTokens();
+ *
+ *   return NextResponse.json({ expired: tokens.isExpired });
+ * };
+ * ```
+ *
+ * @example Middleware
+ * ```tsx:src/proxy.ts tab="Middleware" tab-group="tokens-ssr"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export default async function proxy() {
+ *   const tokens = await getTokens();
+ *
+ *   if (tokens.isExpired) {
+ *     return new NextResponse("Tokens expired", { status: 401 });
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @example Refresh the default token
+ *
+ * The **default token** is the access token associated with your default authorization parameters:
+ * - Scopes: `MONOCLOUD_AUTH_SCOPES` or `options.defaultAuthParams.scopes`
+ * - Resource: `MONOCLOUD_AUTH_RESOURCE` or `options.defaultAuthParams.resource`
+ *
+ * Calling `getTokens()` returns the current token set and **refreshes the default token automatically when needed** (for example, if it has expired). To force a refresh even when it isn’t expired, use `forceRefresh: true`.
+ *
+ * ```tsx:src/app/page.tsx title="Refresh default token"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export const GET = async () => {
+ *   // Forces a refresh of the default token
+ *   const tokens = await getTokens({ forceRefresh: true });
+ *
+ *   return NextResponse.json({ accessToken: tokens?.accessToken });
+ * };
+ * ```
+ *
+ * @example Request an access token for resource(s)
+ *
+ * Use `resource` and `scopes` to request an access token for one or more resources.
+ *
+ * > The requested resource and scopes must be included in the initial authorization flow (so the user has consented / the session is eligible to mint that token).
+ *
+ * ```tsx:src/app/page.tsx title="Request a new access token for resource(s)"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export const GET = async () => {
+ *   const tokens = await getTokens({
+ *     resource: "https://first.example.com https://second.example.com",
+ *     scopes: "read:first read:second shared",
+ *   });
+ *
+ *   return NextResponse.json({ accessToken: tokens?.accessToken });
+ * };
+ * ```
+ *
+ * @param options Optional configuration controlling refresh behavior and resource/scope selection.
+ * @returns The current user's tokens, refreshed if necessary.
+ * @throws {@link MonoCloudValidationError} If no valid session exists.
+ *
+ * @category Functions
+ */
+declare function getTokens(options?: GetTokensOptions$1): Promise<MonoCloudTokens$1>;
+/**
+ * Retrieves the current user's tokens using an explicit Web or Next.js request.
+ *
+ * Use this overload when you already have access to a `Request` or `NextRequest` (for example, in Middleware or Route Handlers).
+ *
+ * @example Middleware (Request)
+ * ```tsx:src/proxy.ts tab="Middleware (Request)" tab-group="tokens-route-handler-request"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export default async function proxy(req: NextRequest) {
+ *   const tokens = await getTokens(req);
+ *
+ *   if (tokens.isExpired) {
+ *     return new NextResponse("Tokens expired", { status: 401 });
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @example API Handler (Request)
+ * ```tsx:src/app/api/tokens/route.ts tab="API Handler (Request)" tab-group="tokens-route-handler-request"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export const GET = async (req: NextRequest) => {
+ *   const tokens = await getTokens(req);
+ *
+ *   return NextResponse.json({ expired: tokens?.isExpired });
+ * };
+ * ```
+ *
+ * @param req Incoming request used to resolve authentication from cookies and headers.
+ * @param options Optional configuration controlling refresh behavior and resource/scope selection.
+ * @returns The current user's tokens, refreshed if necessary.
+ * @throws {@link MonoCloudValidationError} If no valid session exists.
+ *
+ * @category Functions
+ */
+declare function getTokens(req: NextRequest$1 | Request, options?: GetTokensOptions$1): Promise<MonoCloudTokens$1>;
+/**
+ * Retrieves the current user's tokens using an explicit request and response.
+ *
+ * Use this overload when you have already created a response and want refreshed authentication cookies or headers applied to it.
+ *
+ * @example Middleware (Response)
+ *```tsx:src/proxy.ts tab="Middleware (Response)" tab-group="tokens-route-handler-response"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export default async function proxy(req: NextRequest) {
+ *   const res = NextResponse.next();
+ *
+ *   const tokens = await getTokens(req, res);
+ *
+ *   res.headers.set("x-tokens-expired", tokens.isExpired.toString());
+ *
+ *   return res;
+ * }
+ * ```
+ *
+ * @example API Handler (Response)
+ * ```tsx:src/app/api/tokens/route.ts tab="API Handler (Response)" tab-group="tokens-route-handler-response"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export const GET = async (req: NextRequest) => {
+ *   const res = new NextResponse("Custom Body");
+ *
+ *   const tokens = await getTokens(req, res);
+ *
+ *   if (!tokens.isExpired) {
+ *     res.headers.set("x-auth-status", "active");
+ *   }
+ *
+ *   return res;
+ * };
+ * ```
+ *
+ * @param req Incoming request used to resolve authentication from cookies and headers.
+ * @param res Existing response to update with refreshed authentication cookies or headers.
+ * @param options Optional configuration controlling refresh behavior and resource/scope selection.
+ * @returns The current user's tokens, refreshed if necessary.
+ * @throws {@link MonoCloudValidationError} If no valid session exists.
+ *
+ * @category Functions
+ */
+declare function getTokens(req: NextRequest$1 | Request, res: NextResponse$1 | Response, options?: GetTokensOptions$1): Promise<MonoCloudTokens$1>;
+/**
+ * Retrieves the current user's tokens in the Pages Router or Node.js runtime.
+ *
+ * Use this overload in API routes or `getServerSideProps`, where Node.js request and response objects are available.
+ *
+ * @example Pages Router (Pages)
+ * ```tsx:src/pages/index.tsx tab="Pages Router (Pages)" tab-group="tokens-pages"
+ * import { getTokens, MonoCloudTokens } from "@monocloud/auth-nextjs";
+ * import { GetServerSideProps } from "next";
+ *
+ * type Props = {
+ *   tokens: MonoCloudTokens;
+ * };
+ *
+ * export default function Home({ tokens }: Props) {
+ *   return <pre>Tokens: {JSON.stringify(tokens, null, 2)}</pre>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {
+ *   const tokens = await getTokens(ctx.req, ctx.res);
+ *
+ *   return {
+ *     props: {
+ *       tokens: tokens
+ *     }
+ *   };
+ * };
+ * ```
+ *
+ * @example Pages Router (API)
+ * ```tsx:src/pages/api/tokens.ts tab="Pages Router (API)" tab-group="tokens-pages"
+ * import { getTokens } from "@monocloud/auth-nextjs";
+ * import { NextApiRequest, NextApiResponse } from "next";
+ *
+ * export default async function handler(
+ *   req: NextApiRequest,
+ *   res: NextApiResponse
+ * ) {
+ *   const tokens = await getTokens(req, res);
+ *
+ *   res.status(200).json({ accessToken: tokens?.accessToken });
+ * }
+ * ```
+ *
+ * @param req Incoming Node.js request used to resolve authentication from cookies.
+ * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.
+ * @param options Optional configuration controlling refresh behavior and resource/scope selection.
+ * @returns The current user's tokens, refreshed if necessary.
+ * @throws {@link MonoCloudValidationError} If no valid session exists.
+ *
+ * @category Functions
+ */
+declare function getTokens(req: NextApiRequest$1 | IncomingMessage, res: NextApiResponse$1 | ServerResponse<IncomingMessage>, options?: GetTokensOptions$1): Promise<MonoCloudTokens$1>;
+/**
+ * Checks whether the current user is authenticated using the active server request context.
+ *
+ * Intended for Server Components, Server Actions, Route Handlers, and Middleware where the request is implicitly available.
+ *
+ * @example Server Component
+ * ```tsx:src/app/page.tsx tab="Server Component" tab-group="is-authenticated-ssr"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ *
+ * export default async function Home() {
+ *   const authenticated = await isAuthenticated();
+ *
+ *   return <div>Authenticated: {authenticated.toString()}</div>;
+ * }
+ * ```
+ *
+ * @example Server Action
+ * ```tsx:src/action.ts tab="Server Action" tab-group="is-authenticated-ssr"
+ * "use server";
+ *
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ *
+ * export async function checkAuthAction() {
+ *   const authenticated = await isAuthenticated();
+ *
+ *   return { authenticated };
+ * }
+ * ```
+ *
+ * @example API Handler
+ * ```tsx:src/app/api/authenticated/route.ts tab="API Handler" tab-group="is-authenticated-ssr"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export const GET = async () => {
+ *   const authenticated = await isAuthenticated();
+ *
+ *   return NextResponse.json({ authenticated });
+ * };
+ * ```
+ *
+ * @example Middleware
+ * ```tsx:src/proxy.ts tab="Middleware" tab-group="is-authenticated-ssr"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export default async function proxy() {
+ *   const authenticated = await isAuthenticated();
+ *
+ *   if (!authenticated) {
+ *     return new NextResponse("User not signed in", { status: 401 });
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @returns Returns `true` if a valid session exists; otherwise `false`.
+ *
+ * @category Functions
+ */
+declare function isAuthenticated(): Promise<boolean>;
+/**
+ * Checks whether the current user is authenticated using an explicit Web or Next.js request.
+ *
+ * Use this overload when you already have access to a `Request` or `NextRequest` (for example, in Middleware or Route Handlers).
+ *
+ * @example Middleware (Request)
+ * ```tsx:src/proxy.ts tab="Middleware (Request)" tab-group="is-authenticated-route-handler"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export default async function proxy(req: NextRequest) {
+ *   const authenticated = await isAuthenticated(req);
+ *
+ *   if (!authenticated) {
+ *     return new NextResponse("User not signed in", { status: 401 });
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @example Middleware (Response)
+ * ```tsx:src/proxy.ts tab="Middleware (Response)" tab-group="is-authenticated-route-handler"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export default async function proxy(req: NextRequest) {
+ *   const res = NextResponse.next();
+ *
+ *   const authenticated = await isAuthenticated(req, res);
+ *
+ *   if (!authenticated) {
+ *     return new NextResponse("User not signed in", { status: 401 });
+ *   }
+ *
+ *   res.headers.set("x-authenticated", "true");
+ *
+ *   return res;
+ * }
+ * ```
+ *
+ * @example API Handler (Request)
+ * ```tsx:src/app/api/authenticated/route.ts tab="API Handler (Request)" tab-group="is-authenticated-route-handler"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export const GET = async (req: NextRequest) => {
+ *   const authenticated = await isAuthenticated(req);
+ *
+ *   return NextResponse.json({ authenticated });
+ * };
+ * ```
+ *
+ * @example API Handler (Response)
+ * ```tsx:src/app/api/authenticated/route.ts tab="API Handler (Response)" tab-group="is-authenticated-route-handler"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export const GET = async (req: NextRequest) => {
+ *   const res = new NextResponse("YOUR CUSTOM RESPONSE");
+ *
+ *   const authenticated = await isAuthenticated(req, res);
+ *
+ *   if (authenticated) {
+ *     res.cookies.set("something", "important");
+ *   }
+ *
+ *   return res;
+ * };
+ * ```
+ *
+ * @param req Incoming request used to resolve authentication from cookies and headers.
+ * @param res Optional response to update if refreshed authentication cookies or headers are required.
+ * @returns Returns `true` if a valid session exists; otherwise `false`.
+ *
+ * @category Functions
+ */
+declare function isAuthenticated(req: NextRequest$1 | Request, res?: NextResponse$1 | Response): Promise<boolean>;
+/**
+ * Checks whether the current user is authenticated in the Pages Router or Node.js runtime.
+ *
+ * Use this overload in API routes or `getServerSideProps`, where Node.js request and response objects are available.
+ *
+ * @example Pages Router (Pages)
+ * ```tsx:src/pages/index.tsx tab="Pages Router (Pages)" tab-group="is-authenticated-pages"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ * import { GetServerSideProps } from "next";
+ *
+ * type Props = {
+ *   authenticated: boolean;
+ * };
+ *
+ * export default function Home({ authenticated }: Props) {
+ *   return <pre>User is {authenticated ? "logged in" : "guest"}</pre>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {
+ *   const authenticated = await isAuthenticated(ctx.req, ctx.res);
+ *
+ *   return {
+ *     props: {
+ *       authenticated
+ *     }
+ *   };
+ * };
+ * ```
+ *
+ * @example Pages Router (API)
+ * ```tsx:src/pages/api/authenticated.ts tab="Pages Router (API)" tab-group="is-authenticated-pages"
+ * import { isAuthenticated } from "@monocloud/auth-nextjs";
+ * import { NextApiRequest, NextApiResponse } from "next";
+ *
+ * export default async function handler(
+ *   req: NextApiRequest,
+ *   res: NextApiResponse
+ * ) {
+ *   const authenticated = await isAuthenticated(req, res);
+ *
+ *   res.status(200).json({ authenticated });
+ * }
+ * ```
+ *
+ * @param req Incoming Node.js request used to resolve authentication from cookies.
+ * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.
+ * @returns Returns `true` if a valid session exists; otherwise `false`.
+ *
+ * @category Functions
+ */
+declare function isAuthenticated(req: NextApiRequest$1 | IncomingMessage, res: NextApiResponse$1 | ServerResponse<IncomingMessage>): Promise<boolean>;
+/**
+ * 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
+ */
+declare function protect(options?: ProtectOptions): Promise<void>;
+/**
+ * Wraps an App Router API route handler and ensures that only authenticated (and optionally authorized) requests can access the route.
+ *
+ * Intended for Next.js App Router Route Handlers.
+ *
+ * @example
+ * ```tsx:src/app/api/protected/route.ts
+ * import { protectApi } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export const GET = protectApi(async () => {
+ *   return NextResponse.json({
+ *     message: "You accessed a protected endpoint",
+ *   });
+ * });
+ * ```
+ *
+ * @param handler The route handler to protect.
+ * @param options Optional configuration controlling authentication and authorization behavior.
+ * @returns Returns a wrapped handler that enforces authentication (and optional authorization) before invoking the original handler.
+ *
+ * @category Functions
+ */
+declare function protectApi(handler: AppRouterApiHandlerFn, options?: ProtectApiAppOptions): AppRouterApiHandlerFn;
+/**
+ * Wraps a Pages Router API route handler and ensures that only authenticated (and optionally authorized) requests can access the route.
+ *
+ * Intended for Next.js Pages Router API routes.
+ *
+ * @example
+ * ```tsx:src/pages/api/protected.ts
+ * import { protectApi } from "@monocloud/auth-nextjs";
+ * import { NextApiRequest, NextApiResponse } from "next";
+ *
+ * export default protectApi(
+ *   async (req: NextApiRequest, res: NextApiResponse) => {
+ *     return res.json({
+ *       message: "You accessed a protected endpoint",
+ *     });
+ *   }
+ * );
+ * ```
+ *
+ * @param handler - The route handler to protect.
+ * @param options Optional configuration controlling authentication and authorization behavior.
+ * @returns Returns a wrapped handler that enforces authentication (and optional authorization) before invoking the original handler.
+ *
+ * @category Functions
+ */
+declare function protectApi(handler: NextApiHandler$1, options?: ProtectApiPageOptions): NextApiHandler$1;
+/**
+ * Restricts access to App Router server-rendered pages.
+ *
+ * **Access control**
+ * - If the user is not authenticated, `onAccessDenied` is invoked (or default behavior applies).
+ * - If the user is authenticated but fails group checks, `onGroupAccessDenied` is invoked (or the default "Access Denied" view is rendered).
+ *
+ * Both behaviors can be customized via options.
+ *
+ * @example Basic Usage
+ * ```tsx:src/app/page.tsx tab="Basic Usage" tab-group="protectPage-app"
+ * import { protectPage } from "@monocloud/auth-nextjs";
+ *
+ * export default protectPage(async function Home({ user }) {
+ *  return <>Hi {user.email}. You accessed a protected page.</>;
+ * });
+ * ```
+ *
+ * @example With Options
+ * ```tsx:src/app/page.tsx tab="With Options" tab-group="protectPage-app"
+ * import { protectPage } from "@monocloud/auth-nextjs";
+ *
+ * export default protectPage(
+ *   async function Home({ user }) {
+ *     return <>Hi {user.email}. You accessed a protected page.</>;
+ *   },
+ *   {
+ *     returnUrl: "/dashboard",
+ *     groups: ["admin"],
+ *   }
+ * );
+ * ```
+ *
+ * @param component The App Router server component to protect.
+ * @param options Optional configuration for authentication, authorization, and custom access handling (`onAccessDenied`, `onGroupAccessDenied`).
+ * @returns A wrapped page component that enforces authentication before rendering.
+ *
+ * @category Functions
+ */
+declare function protectPage(component: ProtectedAppServerComponent, options?: ProtectAppPageOptions): AppRouterPageHandler;
+/**
+ * Restricts access to Pages Router server-rendered pages using `getServerSideProps`.
+ *
+ * **Access control**
+ * - If the user is not authenticated, `onAccessDenied` is invoked (or default behavior applies).
+ * - If the user is authenticated but fails group checks, the page can still render and `groupAccessDenied` is provided in props. Use `onGroupAccessDenied` to customize the props or behavior.
+ *
+ * Both behaviors can be customized via options.
+ *
+ * @example Basic Usage
+ * ```tsx:src/pages/index.tsx tab="Basic Usage" tab-group="protectPage-page"
+ * import { protectPage, MonoCloudUser } from "@monocloud/auth-nextjs";
+ *
+ * type Props = {
+ *   user: MonoCloudUser;
+ * };
+ *
+ * export default function Home({ user }: Props) {
+ *   return <>Hi {user.email}. You accessed a protected page.</>;
+ * }
+ *
+ * export const getServerSideProps = protectPage();
+ * ```
+ *
+ * @example With Options
+ * ```tsx:src/pages/index.tsx tab="With Options" tab-group="protectPage-page"
+ * import { protectPage, MonoCloudUser } from "@monocloud/auth-nextjs";
+ * import { GetServerSidePropsContext } from "next";
+ *
+ * type Props = {
+ *   user: MonoCloudUser;
+ *   url: string;
+ * };
+ *
+ * export default function Home({ user, url }: Props) {
+ *   console.log(url);
+ *   return <div>Hi {user?.email}. You accessed a protected page.</div>;
+ * }
+ *
+ * export const getServerSideProps = protectPage({
+ *   returnUrl: "/dashboard",
+ *   groups: ["admin"],
+ *   getServerSideProps: async (context: GetServerSidePropsContext) => ({
+ *     props: { url: context.resolvedUrl }
+ *   })
+ * });
+ * ```
+ *
+ * @param options Optional configuration for authentication, authorization, and custom access handling (`onAccessDenied`, `onGroupAccessDenied`).
+ * @typeParam P - Props returned from getServerSideProps.
+ * @typeParam Q - Query parameters parsed from the URL.
+ * @returns A getServerSideProps wrapper that enforces authentication before executing the page logic.
+ *
+ * @category Functions
+ */
+declare function protectPage<P extends Record<string, any> = Record<string, any>, Q extends ParsedUrlQuery = ParsedUrlQuery>(options?: ProtectPagePageOptions<P, Q>): ProtectPagePageReturnType<P, Q>;
+/**
+ * Checks whether the currently authenticated user is a member of **any** of the specified groups.
+ *
+ * The `groups` parameter accepts group identifiers (IDs or names).
+ *
+ * The authenticated user's session may contain groups represented as:
+ * - Group IDs
+ * - Group names
+ * - `Group` objects (for example, `{ id: string; name: string }`)
+ *
+ * Matching is always performed against the group's **ID** and **name**, regardless of how the group is represented in the session.
+ *
+ * @example Server Component
+ * ```tsx:src/app/page.tsx tab="Server Component" tab-group="is-user-in-group-rsc"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ *
+ * export default async function AdminPanel() {
+ *   const isAdmin = await isUserInGroup(["admin"]);
+ *
+ *   if (!isAdmin) {
+ *     return <div>Access Denied</div>;
+ *   }
+ *
+ *   return <div>Admin Control Panel</div>;
+ * }
+ * ```
+ *
+ * @example Server Action
+ * ```tsx:src/action.ts tab="Server Action" tab-group="is-user-in-group-rsc"
+ * "use server";
+ *
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ *
+ * export async function deletePostAction() {
+ *   const canDelete = await isUserInGroup(["admin", "editor"]);
+ *
+ *   if (!canDelete) {
+ *     return { success: false };
+ *   }
+ *
+ *   return { success: true };
+ * }
+ * ```
+ *
+ * @example API Handler
+ * ```tsx:src/app/api/group-check/route.ts tab="API Handler" tab-group="is-user-in-group-rsc"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export const GET = async () => {
+ *   const allowed = await isUserInGroup(["admin", "editor"]);
+ *
+ *   if (!allowed) {
+ *     return new NextResponse("Forbidden", { status: 403 });
+ *   }
+ *
+ *   return NextResponse.json({ status: "success" });
+ * };
+ * ```
+ *
+ * @example Middleware
+ * ```tsx:src/proxy.ts tab="Middleware" tab-group="is-user-in-group-rsc"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ * import { NextResponse } from "next/server";
+ *
+ * export default async function proxy() {
+ *   const isAdmin = await isUserInGroup(["admin"]);
+ *
+ *   if (!isAdmin) {
+ *     return new NextResponse("User is not admin", { status: 403 });
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @param groups Group IDs or names to check against the user's group memberships.
+ * @param options Optional configuration controlling how group membership is evaluated.
+ * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.
+ *
+ * @category Functions
+ */
+declare function isUserInGroup(groups: string[], options?: IsUserInGroupOptions): Promise<boolean>;
+/**
+ * Checks group membership using an explicit Web or Next.js request.
+ *
+ * Use this overload when you already have access to a `Request` or `NextRequest` (for example, in Middleware or Route Handlers).
+ *
+ * @example Middleware (Request)
+ * ```tsx:src/proxy.ts tab="Middleware (Request)" tab-group="is-user-in-group-request"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export default async function proxy(req: NextRequest) {
+ *   const isAdmin = await isUserInGroup(req, ["admin"]);
+ *
+ *   if (!isAdmin) {
+ *     return new NextResponse("User is not admin", { status: 403 });
+ *   }
+ *
+ *   return NextResponse.next();
+ * }
+ * ```
+ *
+ * @example API Handler (Request)
+ * ```tsx:src/app/api/group-check/route.ts tab="API Handler (Request)" tab-group="is-user-in-group-request"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export const GET = async (req: NextRequest) => {
+ *   const isMember = await isUserInGroup(req, ["admin", "editor"]);
+ *
+ *   return NextResponse.json({ isMember });
+ * };
+ * ```
+ *
+ * @param req Incoming request used to resolve authentication from cookies and headers.
+ * @param groups Group IDs or names to check against the user's group memberships.
+ * @param options Optional configuration controlling how group membership is evaluated.
+ * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.
+ *
+ * @category Functions
+ */
+declare function isUserInGroup(req: NextRequest$1 | Request, groups: string[], options?: IsUserInGroupOptions): Promise<boolean>;
+/**
+ * Checks group membership using an explicit request and response.
+ *
+ * Use this overload when you have already created a response and want refreshed authentication cookies or headers applied to it.
+ *
+ * @example Middleware (Response)
+ * ```tsx:src/proxy.ts tab="Middleware (Response)" tab-group="is-user-in-group-response"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export default async function proxy(req: NextRequest) {
+ *   const res = NextResponse.next();
+ *
+ *   const isAdmin = await isUserInGroup(req, res, ["admin"]);
+ *
+ *   if (!isAdmin) {
+ *     return new NextResponse("User is not admin", { status: 403 });
+ *   }
+ *
+ *   res.headers.set("x-user", "admin");
+ *
+ *   return res;
+ * }
+ * ```
+ *
+ * @example API Handler (Response)
+ * ```tsx:src/app/api/group-check/route.ts tab="API Handler (Response)" tab-group="is-user-in-group-response"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ * import { NextRequest, NextResponse } from "next/server";
+ *
+ * export const GET = async (req: NextRequest) => {
+ *   const res = new NextResponse("Restricted Content");
+ *
+ *   const allowed = await isUserInGroup(req, res, ["admin"]);
+ *
+ *   if (!allowed) {
+ *     return new NextResponse("Not Allowed", res);
+ *   }
+ *
+ *   return res;
+ * };
+ * ```
+ *
+ * @param req Incoming request used to resolve authentication from cookies and headers.
+ * @param res Existing response to update with refreshed authentication cookies or headers when required.
+ * @param groups Group IDs or names to check against the user's group memberships.
+ * @param options Optional configuration controlling how group membership is evaluated.
+ * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.
+ *
+ * @category Functions
+ */
+declare function isUserInGroup(req: NextRequest$1 | Request, res: NextResponse$1 | Response, groups: string[], options?: IsUserInGroupOptions): Promise<boolean>;
+/**
+ * Checks group membership in the Pages Router or Node.js runtime.
+ *
+ * Use this overload in API routes or `getServerSideProps`, where Node.js request and response objects are available.
+ *
+ * @example Pages Router (Pages)
+ * ```tsx:src/pages/index.tsx tab="Pages Router (Pages)" tab-group="is-user-in-group-pages"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ * import { GetServerSideProps } from "next";
+ *
+ * type Props = {
+ *   isAdmin: boolean;
+ * };
+ *
+ * export default function Home({ isAdmin }: Props) {
+ *   return <div>User is admin: {isAdmin.toString()}</div>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<Props> = async (ctx) => {
+ *   const isAdmin = await isUserInGroup(ctx.req, ctx.res, ["admin"]);
+ *
+ *   return {
+ *     props: {
+ *       isAdmin
+ *     }
+ *   };
+ * };
+ * ```
+ *
+ * @example Pages Router (API)
+ * ```tsx:src/pages/api/group-check.ts tab="Pages Router (API)" tab-group="is-user-in-group-pages"
+ * import { isUserInGroup } from "@monocloud/auth-nextjs";
+ * import { NextApiRequest, NextApiResponse } from "next";
+ *
+ * export default async function handler(
+ *   req: NextApiRequest,
+ *   res: NextApiResponse
+ * ) {
+ *   const isAdmin = await isUserInGroup(req, res, ["admin"]);
+ *
+ *   if (!isAdmin) {
+ *     return res.status(403).json({ error: "Forbidden" });
+ *   }
+ *
+ *   res.status(200).json({ message: "Welcome Admin" });
+ * }
+ * ```
+ *
+ * @param req Incoming Node.js request used to resolve authentication from cookies.
+ * @param res Outgoing Node.js response used to apply refreshed authentication cookies when required.
+ * @param groups Group IDs or names to check against the user's group memberships.
+ * @param options Optional configuration controlling how group membership is evaluated.
+ * @returns Returns `true` if the user belongs to at least one specified group; otherwise `false`.
+ *
+ * @category Functions
+ */
+declare function isUserInGroup(req: NextApiRequest$1 | IncomingMessage, res: NextApiResponse$1 | ServerResponse<IncomingMessage>, groups: string[], options?: IsUserInGroupOptions): Promise<boolean>;
+/**
+ * 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
+ */
+declare function redirectToSignIn(options?: RedirectToSignInOptions): Promise<void>;
+/**
+ * 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
+ */
+declare function redirectToSignOut(options?: RedirectToSignOutOptions): Promise<void>;
+//#endregion
+export { type AccessToken, type Address, type AppOnError, type AppRouterApiHandlerFn, type AppRouterApiOnAccessDeniedHandler, type AppRouterApiOnGroupAccessDeniedHandler, type AppRouterContext, type AppRouterPageHandler, type ApplicationState, type Authenticators, type AuthorizationParams, type CodeChallengeMethod, type CustomProtectedRouteMatcher, type DisplayOptions, type ExtraAuthParams, type GetTokensOptions, type Group, type GroupOptions, type IdTokenClaims, type Indicator, type IsUserInGroupOptions, type Jwk, MonoCloudAuthBaseError, type MonoCloudAuthHandler, type MonoCloudAuthOptions, type MonoCloudCookieOptions, MonoCloudHttpError, type MonoCloudMiddlewareOptions, MonoCloudNextClient, MonoCloudOPError, type MonoCloudOptions, type MonoCloudRequest, type MonoCloudRoutes, type MonoCloudSession, type MonoCloudSessionOptions, type MonoCloudSessionOptionsBase, type MonoCloudSessionStore, type MonoCloudStateOptions, type MonoCloudStatePartialOptions, MonoCloudTokenError, type MonoCloudTokens, type MonoCloudUser, MonoCloudValidationError, type NextMiddlewareOnAccessDenied, type NextMiddlewareOnGroupAccessDenied, type NextMiddlewareResult, type OnBackChannelLogout, type OnError, type OnSessionCreating, type OnSetApplicationState, type PageOnError, type PageRouterApiOnAccessDeniedHandler, type PageRouterApiOnGroupAccessDeniedHandler, type Prompt, type ProtectApiAppOptions, type ProtectApiPageOptions, type ProtectAppPageOptions, type ProtectOptions, type ProtectPagePageOnAccessDeniedType, type ProtectPagePageOnGroupAccessDeniedType, type ProtectPagePageOptions, type ProtectPagePageReturnType, type ProtectedAppServerComponent, type ProtectedRouteMatcher, type ProtectedRoutes, type RedirectToSignInOptions, type RedirectToSignOutOptions, type ResponseModes, type ResponseTypes, type SameSiteValues, type SecurityAlgorithms, type SessionLifetime, type UserinfoResponse, authMiddleware, getSession, getTokens, isAuthenticated, isUserInGroup, monoCloudAuth, protect, protectApi, protectPage, redirectToSignIn, redirectToSignOut };
 //# sourceMappingURL=index.d.mts.map