@adonisjs/auth 9.5.0 → 10.0.0-next.0

package/build/modules/session_guard/remember_me_token.d.ts

@@ -3,6 +3,16 @@ import { Secret } from '@adonisjs/core/helpers';
  * Remember me token represents an opaque token that can be
  * used to automatically login a user without asking them
  * to re-login
+ *
+ * @example
+ * const token = new RememberMeToken({
+ *   identifier: 1,
+ *   tokenableId: 123,
+ *   hash: 'sha256hash',
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ *   expiresAt: new Date(Date.now() + 86400000)
+ * })
  */
 export declare class RememberMeToken {
     /**
@@ -11,6 +21,15 @@ export declare class RememberMeToken {
      *
      * Returns null when unable to decode the token because of
      * invalid format or encoding.
+     *
+     * @param value - The token value to decode
+     *
+     * @example
+     * const decoded = RememberMeToken.decode('abc123.def456')
+     * if (decoded) {
+     *   console.log('Token ID:', decoded.identifier)
+     *   console.log('Secret:', decoded.secret.release())
+     * }
      */
     static decode(value: string): null | {
         identifier: string;
@@ -19,6 +38,14 @@ export declare class RememberMeToken {
     /**
      * Creates a transient token that can be shared with the persistence
      * layer.
+     *
+     * @param userId - The ID of the user for whom the token is created
+     * @param size - The size of the random secret to generate
+     * @param expiresIn - Expiration time (seconds or duration string)
+     *
+     * @example
+     * const transientToken = RememberMeToken.createTransientToken(123, 32, '30d')
+     * // Store transientToken in database
      */
     static createTransientToken(userId: string | number | BigInt, size: number, expiresIn: string | number): {
         secret: Secret<string>;
@@ -28,6 +55,13 @@ export declare class RememberMeToken {
     };
     /**
      * Creates a secret opaque token and its hash.
+     *
+     * @param size - The size of the random string to generate
+     *
+     * @example
+     * const { secret, hash } = RememberMeToken.seed(32)
+     * console.log('Secret:', secret.release())
+     * console.log('Hash:', hash)
      */
     static seed(size: number): {
         secret: Secret<string>;
@@ -66,6 +100,21 @@ export declare class RememberMeToken {
      * Timestamp at which the token will expire
      */
     expiresAt: Date;
+    /**
+     * Creates a new RememberMeToken instance
+     *
+     * @param attributes - Token attributes including identifier, user ID, hash, etc.
+     *
+     * @example
+     * const token = new RememberMeToken({
+     *   identifier: 1,
+     *   tokenableId: 123,
+     *   hash: 'sha256hash',
+     *   createdAt: new Date(),
+     *   updatedAt: new Date(),
+     *   expiresAt: new Date(Date.now() + 86400000)
+     * })
+     */
     constructor(attributes: {
         identifier: string | number | BigInt;
         tokenableId: string | number | BigInt;
@@ -79,10 +128,25 @@ export declare class RememberMeToken {
      * Check if the token has been expired. Verifies
      * the "expiresAt" timestamp with the current
      * date.
+     *
+     * @example
+     * if (token.isExpired()) {
+     *   console.log('Remember me token has expired')
+     * } else {
+     *   console.log('Token is still valid')
+     * }
      */
     isExpired(): boolean;
     /**
      * Verifies the value of a token against the pre-defined hash
+     *
+     * @param secret - The secret to verify against the stored hash
+     *
+     * @example
+     * const isValid = token.verify(new Secret('user-provided-secret'))
+     * if (isValid) {
+     *   console.log('Remember me token is valid')
+     * }
      */
     verify(secret: Secret<string>): boolean;
 }

package/build/modules/session_guard/token_providers/db.d.ts

@@ -1,18 +1,36 @@
 import type { Secret } from '@adonisjs/core/helpers';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
-import { RememberMeToken } from '../remember_me_token.js';
-import type { RememberMeTokenDbColumns, RememberMeTokensProviderContract, DbRememberMeTokensProviderOptions } from '../types.js';
+import { RememberMeToken } from '../remember_me_token.ts';
+import type { RememberMeTokenDbColumns, RememberMeTokensProviderContract, DbRememberMeTokensProviderOptions } from '../types.ts';
 /**
  * DbRememberMeTokensProvider uses lucid database service to fetch and
  * persist tokens for a given user.
  *
  * The user must be an instance of the associated user model.
+ *
+ * @template TokenableModel - The Lucid model that can have remember me tokens
+ *
+ * @example
+ * const provider = new DbRememberMeTokensProvider({
+ *   tokenableModel: () => import('#models/user'),
+ *   table: 'remember_me_tokens',
+ *   tokenSecretLength: 32
+ * })
  */
 export declare class DbRememberMeTokensProvider<TokenableModel extends LucidModel> implements RememberMeTokensProviderContract<TokenableModel> {
     #private;
     protected options: DbRememberMeTokensProviderOptions<TokenableModel>;
     /**
      * Create tokens provider instance for a given Lucid model
+     *
+     * @param model - The tokenable model factory function
+     * @param options - Optional configuration options
+     *
+     * @example
+     * const provider = DbRememberMeTokensProvider.forModel(
+     *   () => import('#models/user'),
+     *   { table: 'user_remember_tokens' }
+     * )
      */
     static forModel<TokenableModel extends LucidModel>(model: DbRememberMeTokensProviderOptions<TokenableModel>['tokenableModel'], options?: Omit<DbRememberMeTokensProviderOptions<TokenableModel>, 'tokenableModel'>): DbRememberMeTokensProvider<TokenableModel>;
     /**
@@ -24,29 +42,85 @@ export declare class DbRememberMeTokensProvider<TokenableModel extends LucidMode
      * secure random string.
      */
     protected tokenSecretLength: number;
+    /**
+     * Creates a new DbRememberMeTokensProvider instance
+     *
+     * @param options - Configuration options for the provider
+     *
+     * @example
+     * const provider = new DbRememberMeTokensProvider({
+     *   tokenableModel: () => import('#models/user'),
+     *   table: 'remember_me_tokens',
+     *   tokenSecretLength: 40
+     * })
+     */
     constructor(options: DbRememberMeTokensProviderOptions<TokenableModel>);
     /**
      * Maps a database row to an instance token instance
+     *
+     * @param dbRow - The database row containing token data
+     *
+     * @example
+     * const token = provider.dbRowToRememberMeToken({
+     *   id: 1,
+     *   tokenable_id: 123,
+     *   hash: 'sha256hash',
+     *   // ... other columns
+     * })
      */
     protected dbRowToRememberMeToken(dbRow: RememberMeTokenDbColumns): RememberMeToken;
     /**
      * Returns a query client instance from the parent model
+     *
+     * @example
+     * const db = await provider.getDb()
+     * const tokens = await db.from('remember_me_tokens').select('*')
      */
     protected getDb(): Promise<import("@adonisjs/lucid/types/database").QueryClientContract>;
     /**
      * Create a token for a user
+     *
+     * @param user - The user instance to create a token for
+     * @param expiresIn - Token expiration time
+     *
+     * @example
+     * const token = await provider.create(user, '30d')
+     * console.log('Remember token:', token.value.release())
      */
     create(user: InstanceType<TokenableModel>, expiresIn: string | number): Promise<RememberMeToken>;
     /**
      * Find a token for a user by the token id
+     *
+     * @param user - The user instance that owns the token
+     * @param identifier - The token identifier to search for
+     *
+     * @example
+     * const token = await provider.find(user, 123)
+     * if (token) {
+     *   console.log('Found token with id:', token.identifier)
+     * }
      */
     find(user: InstanceType<TokenableModel>, identifier: string | number | BigInt): Promise<RememberMeToken | null>;
     /**
      * Delete a token by its id
+     *
+     * @param user - The user instance that owns the token
+     * @param identifier - The token identifier to delete
+     *
+     * @example
+     * const deletedCount = await provider.delete(user, 123)
+     * console.log('Deleted tokens:', deletedCount)
      */
     delete(user: InstanceType<TokenableModel>, identifier: string | number | BigInt): Promise<number>;
     /**
      * Returns all the tokens a given user
+     *
+     * @param user - The user instance to get tokens for
+     *
+     * @example
+     * const tokens = await provider.all(user)
+     * console.log('User has', tokens.length, 'remember tokens')
+     * tokens.forEach(token => console.log(token.identifier))
      */
     all(user: InstanceType<TokenableModel>): Promise<RememberMeToken[]>;
     /**
@@ -55,6 +129,14 @@ export declare class DbRememberMeTokensProvider<TokenableModel extends LucidMode
      *
      * Returns null when unable to verify the token or find it
      * inside the storage
+     *
+     * @param tokenValue - The token value to verify
+     *
+     * @example
+     * const token = await provider.verify(new Secret('rmt_abc123.def456'))
+     * if (token && !token.isExpired()) {
+     *   console.log('Valid remember token for user:', token.tokenableId)
+     * }
      */
     verify(tokenValue: Secret<string>): Promise<RememberMeToken | null>;
     /**
@@ -64,6 +146,14 @@ export declare class DbRememberMeTokensProvider<TokenableModel extends LucidMode
      * Ideally, the recycle should update the existing token, but we
      * skip that for now and come back to it later and handle race
      * conditions as well.
+     *
+     * @param user - The user that owns the token
+     * @param identifier - The token identifier to recycle
+     * @param expiresIn - New expiration time
+     *
+     * @example
+     * const newToken = await provider.recycle(user, 123, '30d')
+     * console.log('Recycled token:', newToken.value.release())
      */
     recycle(user: InstanceType<TokenableModel>, identifier: string | number | BigInt, expiresIn: string | number): Promise<RememberMeToken>;
 }

package/build/modules/session_guard/types.d.ts

@@ -2,8 +2,8 @@ import type { Secret } from '@adonisjs/core/helpers';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { Exception } from '@adonisjs/core/exceptions';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
-import { PROVIDER_REAL_USER } from '../../src/symbols.js';
-import type { RememberMeToken } from './remember_me_token.js';
+import { type PROVIDER_REAL_USER } from '../../src/symbols.ts';
+import type { RememberMeToken } from './remember_me_token.ts';
 /**
  * Options accepted by the tokens provider that uses lucid
  * database service to fetch and persist tokens.

package/build/modules/session_guard/user_providers/lucid.d.ts

@@ -1,10 +1,17 @@
-import { Secret } from '@adonisjs/core/helpers';
-import { RememberMeToken } from '../remember_me_token.js';
-import { PROVIDER_REAL_USER } from '../../../src/symbols.js';
-import type { SessionGuardUser, LucidAuthenticatable, SessionLucidUserProviderOptions, SessionUserProviderContract } from '../types.js';
+import { type Secret } from '@adonisjs/core/helpers';
+import { type RememberMeToken } from '../remember_me_token.ts';
+import { PROVIDER_REAL_USER } from '../../../src/symbols.ts';
+import type { SessionGuardUser, LucidAuthenticatable, SessionLucidUserProviderOptions, SessionUserProviderContract } from '../types.ts';
 /**
  * Uses a lucid model to verify access tokens and find a user during
  * authentication
+ *
+ * @template UserModel - The Lucid model representing the user
+ *
+ * @example
+ * const userProvider = new SessionLucidUserProvider({
+ *   model: () => import('#models/user')
+ * })
  */
 export declare class SessionLucidUserProvider<UserModel extends LucidAuthenticatable> implements SessionUserProviderContract<InstanceType<UserModel>> {
     /**
@@ -16,6 +23,16 @@ export declare class SessionLucidUserProvider<UserModel extends LucidAuthenticat
      * Reference to the lazily imported model
      */
     protected model?: UserModel;
+    /**
+     * Creates a new SessionLucidUserProvider instance
+     *
+     * @param options - Configuration options for the user provider
+     *
+     * @example
+     * const provider = new SessionLucidUserProvider({
+     *   model: () => import('#models/user')
+     * })
+     */
     constructor(
     /**
      * Lucid provider options
@@ -24,34 +41,90 @@ export declare class SessionLucidUserProvider<UserModel extends LucidAuthenticat
     /**
      * Imports the model from the provider, returns and caches it
      * for further operations.
+     *
+     * @example
+     * const UserModel = await provider.getModel()
+     * const user = await UserModel.find(1)
      */
     protected getModel(): Promise<UserModel>;
     /**
      * Returns the tokens provider associated with the user model
+     *
+     * @example
+     * const tokensProvider = await provider.getTokensProvider()
+     * const token = await tokensProvider.create(user, '7d')
      */
-    protected getTokensProvider(): Promise<import("../types.js").RememberMeTokensProviderContract<import("@adonisjs/lucid/types/model").LucidModel>>;
+    protected getTokensProvider(): Promise<import("../types.ts").RememberMeTokensProviderContract<import("@adonisjs/lucid/types/model").LucidModel>>;
     /**
      * Creates an adapter user for the guard
+     *
+     * @param user - The user model instance
+     *
+     * @example
+     * const guardUser = await provider.createUserForGuard(user)
+     * console.log('User ID:', guardUser.getId())
+     * console.log('Original user:', guardUser.getOriginal())
      */
     createUserForGuard(user: InstanceType<UserModel>): Promise<SessionGuardUser<InstanceType<UserModel>>>;
     /**
      * Finds a user by their primary key value
+     *
+     * @param identifier - The user identifier to search for
+     *
+     * @example
+     * const guardUser = await provider.findById(123)
+     * if (guardUser) {
+     *   const originalUser = guardUser.getOriginal()
+     *   console.log('Found user:', originalUser.email)
+     * }
      */
     findById(identifier: string | number | BigInt): Promise<SessionGuardUser<InstanceType<UserModel>> | null>;
     /**
      * Creates a remember token for a given user
+     *
+     * @param user - The user to create a token for
+     * @param expiresIn - Token expiration time
+     *
+     * @example
+     * const token = await provider.createRememberToken(user, '30d')
+     * console.log('Remember token:', token.value.release())
      */
     createRememberToken(user: InstanceType<UserModel>, expiresIn: string | number): Promise<RememberMeToken>;
     /**
      * Verify a token by its publicly shared value
+     *
+     * @param tokenValue - The token value to verify
+     *
+     * @example
+     * const token = await provider.verifyRememberToken(
+     *   new Secret('rmt_abc123.def456')
+     * )
+     * if (token && !token.isExpired()) {
+     *   console.log('Valid remember token for user:', token.tokenableId)
+     * }
      */
     verifyRememberToken(tokenValue: Secret<string>): Promise<RememberMeToken | null>;
     /**
      * Delete a token for a user by the token identifier
+     *
+     * @param user - The user that owns the token
+     * @param identifier - The token identifier to delete
+     *
+     * @example
+     * const deletedCount = await provider.deleteRemeberToken(user, 123)
+     * console.log('Deleted tokens:', deletedCount)
      */
     deleteRemeberToken(user: InstanceType<UserModel>, identifier: string | number | BigInt): Promise<number>;
     /**
      * Recycle a token for a user by the token identifier
+     *
+     * @param user - The user that owns the token
+     * @param identifier - The token identifier to recycle
+     * @param expiresIn - New expiration time
+     *
+     * @example
+     * const newToken = await provider.recycleRememberToken(user, 123, '30d')
+     * console.log('Recycled token:', newToken.value.release())
      */
     recycleRememberToken(user: InstanceType<UserModel>, identifier: string | number | BigInt, expiresIn: string | number): Promise<RememberMeToken>;
 }

package/build/providers/auth_provider.d.ts

@@ -1,12 +1,33 @@
 import type { ApplicationService } from '@adonisjs/core/types';
-import type { AuthService } from '../src/types.js';
+import type { AuthService } from '../src/types.ts';
 declare module '@adonisjs/core/types' {
     interface ContainerBindings {
         'auth.manager': AuthService;
     }
 }
+/**
+ * The AuthProvider service provider registers the auth manager
+ * with the IoC container as a singleton
+ *
+ * @example
+ * // The auth manager is automatically registered and can be injected
+ * container.use('auth.manager')
+ */
 export default class AuthProvider {
     protected app: ApplicationService;
+    /**
+     * Creates a new AuthProvider instance
+     *
+     * @param app - The application service instance
+     */
     constructor(app: ApplicationService);
+    /**
+     * Registers the auth manager as a singleton service
+     * in the IoC container
+     *
+     * @example
+     * // This method is called automatically by AdonisJS
+     * // The auth manager becomes available as 'auth.manager'
+     */
     register(): void;
 }

package/build/providers/auth_provider.js

@@ -1,17 +1,30 @@
 import {
   AuthManager
-} from "../chunk-SAW2RPCA.js";
+} from "../chunk-MSPAYMZE.js";
 import "../chunk-2VRS2VHB.js";
-import "../chunk-MUPAP5IP.js";
+import "../chunk-S5G5RTJX.js";
 import "../chunk-UXA4FHST.js";
 
 // providers/auth_provider.ts
 import { configProvider } from "@adonisjs/core";
-import { RuntimeException } from "@poppinss/utils";
+import { RuntimeException } from "@adonisjs/core/exceptions";
 var AuthProvider = class {
+  /**
+   * Creates a new AuthProvider instance
+   *
+   * @param app - The application service instance
+   */
   constructor(app) {
     this.app = app;
   }
+  /**
+   * Registers the auth manager as a singleton service
+   * in the IoC container
+   *
+   * @example
+   * // This method is called automatically by AdonisJS
+   * // The auth manager becomes available as 'auth.manager'
+   */
   register() {
     this.app.container.singleton("auth.manager", async () => {
       const authConfigProvider = this.app.config.get("auth");

package/build/services/auth.d.ts

@@ -1,3 +1,3 @@
-import { AuthService } from '../src/types.js';
+import { type AuthService } from '../src/types.ts';
 declare let auth: AuthService;
 export { auth as default };

package/build/src/auth_manager.d.ts

@@ -1,7 +1,7 @@
 import type { HttpContext } from '@adonisjs/core/http';
-import type { GuardFactory } from './types.js';
-import { Authenticator } from './authenticator.js';
-import { AuthenticatorClient } from './authenticator_client.js';
+import type { GuardFactory } from './types.ts';
+import { Authenticator } from './authenticator.ts';
+import { AuthenticatorClient } from './authenticator_client.ts';
 /**
  * Auth manager exposes the API to register and manage authentication
  * guards from the config
@@ -15,18 +15,39 @@ export declare class AuthManager<KnownGuards extends Record<string, GuardFactory
      * Name of the default guard
      */
     get defaultGuard(): keyof KnownGuards;
+    /**
+     * Creates a new AuthManager instance
+     *
+     * @param config - Configuration object containing default guard and available guards
+     *
+     * @example
+     * const manager = new AuthManager({
+     *   default: 'web',
+     *   guards: { web: sessionGuard, api: tokenGuard }
+     * })
+     */
     constructor(config: {
         default: keyof KnownGuards;
         guards: KnownGuards;
     });
     /**
      * Create an authenticator for a given HTTP request. The authenticator
-     * is used to authenticated in incoming HTTP request
+     * is used to authenticate incoming HTTP requests
+     *
+     * @param ctx - The HTTP context for the current request
+     *
+     * @example
+     * const authenticator = manager.createAuthenticator(ctx)
+     * const user = await authenticator.authenticate()
      */
     createAuthenticator(ctx: HttpContext): Authenticator<KnownGuards>;
     /**
      * Creates an instance of the authenticator client. The client is
      * used to setup authentication state during testing.
+     *
+     * @example
+     * const client = manager.createAuthenticatorClient()
+     * const guard = client.use('session')
      */
     createAuthenticatorClient(): AuthenticatorClient<KnownGuards>;
 }

package/build/src/authenticator.d.ts

@@ -1,5 +1,5 @@
 import type { HttpContext } from '@adonisjs/core/http';
-import type { GuardFactory } from './types.js';
+import type { GuardFactory } from './types.ts';
 /**
  * Authenticator is used to authenticate incoming HTTP requests
  * using one or more known guards.
@@ -36,13 +36,30 @@ export declare class Authenticator<KnownGuards extends Record<string, GuardFacto
      * used.
      */
     get authenticationAttempted(): boolean;
+    /**
+     * Creates a new Authenticator instance
+     *
+     * @param ctx - The HTTP context for the current request
+     * @param config - Configuration object containing default guard and available guards
+     *
+     * @example
+     * const authenticator = new Authenticator(ctx, {
+     *   default: 'web',
+     *   guards: { web: sessionGuard }
+     * })
+     */
     constructor(ctx: HttpContext, config: {
         default: keyof KnownGuards;
         guards: KnownGuards;
     });
     /**
-     * Returns an instance of the logged-in user or throws an
-     * exception
+     * Returns an instance of the logged-in user or throws an exception
+     *
+     * @throws {RuntimeException} When authentication has not been attempted
+     *
+     * @example
+     * const user = auth.getUserOrFail()
+     * console.log(user.id)
      */
     getUserOrFail(): {
         [K in keyof KnownGuards]: ReturnType<ReturnType<KnownGuards[K]>['getUserOrFail']>;
@@ -50,18 +67,36 @@ export declare class Authenticator<KnownGuards extends Record<string, GuardFacto
     /**
      * Returns an instance of a known guard. Guards instances are
      * cached during the lifecycle of an HTTP request.
+     *
+     * @param guard - Optional guard name. Uses default guard if not provided
+     *
+     * @example
+     * const sessionGuard = auth.use('session')
+     * const defaultGuard = auth.use()
      */
     use<Guard extends keyof KnownGuards>(guard?: Guard): ReturnType<KnownGuards[Guard]>;
     /**
      * Authenticate current request using the default guard. Calling this
      * method multiple times triggers multiple authentication with the
      * guard.
+     *
+     * @throws {E_UNAUTHORIZED_ACCESS} When authentication fails
+     *
+     * @example
+     * const user = await auth.authenticate()
+     * console.log('Authenticated user:', user.email)
      */
     authenticate(): Promise<{ [K in keyof KnownGuards]: ReturnType<ReturnType<KnownGuards[K]>["getUserOrFail"]>; }[keyof KnownGuards]>;
     /**
      * Silently attempt to authenticate the request using the default
      * guard. Calling this method multiple times triggers multiple
      * authentication with the guard.
+     *
+     * @example
+     * const isAuthenticated = await auth.check()
+     * if (isAuthenticated) {
+     *   console.log('User is authenticated')
+     * }
      */
     check(): Promise<boolean>;
     /**
@@ -72,6 +107,15 @@ export declare class Authenticator<KnownGuards extends Record<string, GuardFacto
      * guards is able to authenticate the request successfully.
      *
      * Otherwise, "E_UNAUTHORIZED_ACCESS" will be raised.
+     *
+     * @param guards - Array of guard names to try for authentication
+     * @param options - Options object with optional loginRoute for redirects
+     *
+     * @throws {E_UNAUTHORIZED_ACCESS} When none of the guards can authenticate
+     *
+     * @example
+     * const user = await auth.authenticateUsing(['session', 'api'])
+     * const userWithRedirect = await auth.authenticateUsing(['web'], { loginRoute: '/login' })
      */
     authenticateUsing(guards?: (keyof KnownGuards)[], options?: {
         loginRoute?: string;
@@ -82,6 +126,14 @@ export declare class Authenticator<KnownGuards extends Record<string, GuardFacto
      * Silently attempt to authenticate the request using all of the mentioned guards
      * or the default guard. Calling this method multiple times triggers multiple
      * authentication with the guard.
+     *
+     * @param guards - Array of guard names to check. Defaults to default guard
+     *
+     * @example
+     * const isAuthenticated = await auth.checkUsing(['session', 'api'])
+     * if (isAuthenticated) {
+     *   const user = auth.user
+     * }
      */
     checkUsing(guards?: (keyof KnownGuards)[]): Promise<boolean>;
 }

package/build/src/authenticator_client.d.ts

@@ -1,4 +1,4 @@
-import type { GuardFactory } from './types.js';
+import type { GuardFactory } from './types.ts';
 /**
  * Authenticator client is used to create guard instances for testing.
  * It passes a fake HTTPContext to the guards, so make sure to not
@@ -11,6 +11,17 @@ export declare class AuthenticatorClient<KnownGuards extends Record<string, Guar
      * Name of the default guard
      */
     get defaultGuard(): keyof KnownGuards;
+    /**
+     * Creates a new AuthenticatorClient instance for testing
+     *
+     * @param config - Configuration object containing default guard and available guards
+     *
+     * @example
+     * const client = new AuthenticatorClient({
+     *   default: 'web',
+     *   guards: { web: sessionGuard }
+     * })
+     */
     constructor(config: {
         default: keyof KnownGuards;
         guards: KnownGuards;
@@ -18,6 +29,12 @@ export declare class AuthenticatorClient<KnownGuards extends Record<string, Guar
     /**
      * Returns an instance of a known guard. Guards instances are
      * cached during the lifecycle of an HTTP request.
+     *
+     * @param guard - Optional guard name. Uses default guard if not provided
+     *
+     * @example
+     * const sessionGuard = client.use('session')
+     * const defaultGuard = client.use()
      */
     use<Guard extends keyof KnownGuards>(guard?: Guard): ReturnType<KnownGuards[Guard]>;
 }