@vunexa/lixa 0.0.1-alpha.3 → 0.0.1-alpha.33

package/dist/models/session.d.ts

@@ -0,0 +1,273 @@
+/**
+ * OAuth 2.0 token response structure.
+ * Based on RFC 6749 Section 5.1 and OpenID Connect Core 1.0 Section 3.1.3.3
+ *
+ * @remarks
+ * This interface represents the standard OAuth 2.0 token response with
+ * optional OpenID Connect extensions. All OAuth providers should return
+ * at minimum the required fields (access_token, token_type).
+ *
+ * @public
+ */
+export interface OAuthTokenResponse {
+    /**
+     * OAuth 2.0 access token (required).
+     * Used to access protected resources on behalf of the user.
+     */
+    access_token: string;
+    /**
+     * Token type (required).
+     * Typically "Bearer" for OAuth 2.0.
+     */
+    token_type: string;
+    /**
+     * Token expiration time in seconds (optional).
+     * Time until the access token expires.
+     */
+    expires_in?: number;
+    /**
+     * OAuth 2.0 refresh token (optional).
+     * Used to obtain new access tokens without re-authentication.
+     */
+    refresh_token?: string;
+    /**
+     * Granted OAuth scopes (optional).
+     * Space-separated list of scopes that were granted.
+     */
+    scope?: string;
+    /**
+     * OpenID Connect ID token (optional).
+     * JWT containing user identity claims (only present for OIDC providers).
+     */
+    id_token?: string;
+    /**
+     * Additional provider-specific fields.
+     * Some providers may include extra fields like user_id, account_id, etc.
+     */
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Represents a user session after successful OAuth authentication.
+ *
+ * @remarks
+ * The Session object is returned by SessionStrategy.createSession() and contains
+ * the session identifier and any additional data needed for your application.
+ *
+ * The structure is intentionally flexible to support various session management
+ * approaches (JWT tokens, session IDs, etc.).
+ *
+ * @public
+ */
+export interface Session<TRaw = OAuthTokenResponse> {
+    /**
+     * The session token or identifier.
+     * This could be an access token, a session ID, a JWT, or any other identifier
+     * that your application uses to track authenticated users.
+     */
+    token: string;
+    /**
+     * Raw session data.
+     * Contains the complete OAuth token response and any additional data
+     * your SessionStrategy adds (user info, database IDs, etc.).
+     *
+     * Typical OAuth token data includes:
+     * - access_token: OAuth access token
+     * - refresh_token: OAuth refresh token (if requested)
+     * - expires_in: Token expiration time in seconds
+     * - token_type: Token type (usually "Bearer")
+     * - id_token: OpenID Connect ID token (if using OIDC)
+     * - scope: Granted scopes
+     */
+    raw: TRaw;
+}
+/**
+ * Provider metadata passed to session strategy.
+ * Contains provider name and endpoints for user info extraction.
+ *
+ * @public
+ */
+export interface ProviderMetadata {
+    /** The provider name (e.g., 'google', 'github') */
+    name: string;
+    /** Provider endpoints */
+    endpoints: {
+        /** Authorization endpoint URL */
+        authorization: string;
+        /** Token endpoint URL */
+        token: string;
+        /** UserInfo endpoint URL */
+        userInfo: string;
+    };
+}
+/**
+ * Strategy interface for custom session creation.
+ *
+ * @remarks
+ * Implement this interface to customize how OAuth tokens are converted into
+ * application sessions. This is where you typically:
+ * - Decode ID tokens (for OpenID Connect)
+ * - Look up or create users in your database
+ * - Generate session identifiers
+ * - Store session data
+ * - Add custom claims or metadata
+ *
+ * The default implementation (DefaultSessionStrategy) simply extracts the
+ * access token and returns it as the session token.
+ *
+ * @example
+ * Custom session strategy with database integration:
+ * ```typescript
+ * interface CustomSessionData {
+ *   userId: string;
+ *   email: string;
+ *   provider: string;
+ *   accessToken: string;
+ *   refreshToken?: string;
+ *   expiresAt: number;
+ * }
+ *
+ * class DatabaseSessionStrategy implements SessionStrategy {
+ *   constructor(private db: Database) {}
+ *
+ *   async createSession(oauthContext: OAuthContext): Promise<Session<CustomSessionData>> {
+ *     // User info is already extracted by Lixa!
+ *     const { userInfo, provider, tokenData } = oauthContext;
+ *
+ *     // Create or update user in database
+ *     const user = await this.db.users.upsert({
+ *       email: userInfo.email,
+ *       name: userInfo.name,
+ *       picture: userInfo.picture
+ *     });
+ *
+ *     // Generate session ID
+ *     const sessionId = generateSecureId();
+ *
+ *     // Store session with tokens
+ *     await this.db.sessions.create({
+ *       id: sessionId,
+ *       userId: user.id,
+ *       accessToken: tokenData.access_token,
+ *       refreshToken: tokenData.refresh_token,
+ *       expiresAt: new Date(Date.now() + (tokenData.expires_in || 3600) * 1000)
+ *     });
+ *
+ *     return {
+ *       token: sessionId,
+ *       raw: {
+ *         userId: user.id,
+ *         email: user.email,
+ *         provider,
+ *         accessToken: tokenData.access_token,
+ *         refreshToken: tokenData.refresh_token,
+ *         expiresAt: Date.now() + (tokenData.expires_in || 3600) * 1000
+ *       }
+ *     };
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export interface SessionStrategy {
+    /**
+     * Creates a session from OAuth token data.
+     *
+     * @param tokenData - The token data received from the OAuth provider's token endpoint
+     * @param providerMetadata - Provider metadata including name and endpoints
+     * @returns A Promise that resolves to a Session object
+     *
+     * @remarks
+     * This method is called after successfully exchanging the authorization code
+     * for tokens. You receive:
+     *
+     * Token Data:
+     * - access_token: OAuth access token
+     * - refresh_token: OAuth refresh token (optional)
+     * - expires_in: Token expiration time in seconds
+     * - token_type: Token type (usually "Bearer")
+     * - id_token: OpenID Connect ID token (for OIDC providers)
+     * - scope: Granted scopes
+     *
+     * Provider Metadata:
+     * - name: The provider name (e.g., 'google', 'github')
+     * - endpoints: Provider endpoints (authorization, token, userInfo)
+     *
+     * The providerMetadata.endpoints.userInfo can be used with extractUserInfo():
+     * ```typescript
+     * import { extractUserInfo } from '@vunexa/lixa';
+     *
+     * const { userInfo } = await extractUserInfo(
+     *   tokenData,
+     *   providerMetadata.endpoints.userInfo,
+     *   providerMetadata.name
+     * );
+     * ```
+     *
+     * Your session strategy should:
+     * 1. Extract user info (using extractUserInfo or decode ID token)
+     * 2. Create or lookup users in your database
+     * 3. Generate session identifiers
+     * 4. Store session data as needed
+     * 5. Return a Session object with token and raw data
+     *
+     * @throws \{Error\} If session creation fails (e.g., database error, invalid token)
+     *
+     * @example
+     * Simple implementation:
+     * ```typescript
+     * async createSession(tokenData: OAuthTokenResponse): Promise<Session> {
+     *   return {
+     *     token: tokenData.access_token,
+     *     raw: tokenData
+     *   };
+     * }
+     * ```
+     *
+     * @example
+     * Database integration with user info extraction:
+     * ```typescript
+     * async createSession(
+     *   tokenData: OAuthTokenResponse,
+     *   providerMetadata: ProviderMetadata
+     * ): Promise<Session> {
+     *   // Extract user info from token or userinfo endpoint
+     *   const { userInfo } = await extractUserInfo(
+     *     tokenData,
+     *     providerMetadata.endpoints.userInfo,
+     *     providerMetadata.name
+     *   );
+     *
+     *   // Create or update user in database
+     *   const user = await db.users.upsert({
+     *     email: userInfo.email,
+     *     name: userInfo.name
+     *   });
+     *
+     *   return {
+     *     token: generateSessionId(),
+     *     raw: { userId: user.id, provider: providerMetadata.name, ...tokenData }
+     *   };
+     * }
+     * ```
+     */
+    createSession(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<Session>;
+}
+/**
+ * Default session strategy that works with any OAuth provider.
+ * Extracts common token information and creates a standardized session.
+ *
+ * @public
+ */
+export declare class DefaultSessionStrategy implements SessionStrategy {
+    /**
+     * Creates a session from OAuth token data.
+     * Handles common OAuth token formats and extracts the access token.
+     *
+     * @param tokenData - The token data received from the OAuth provider
+     * @param providerMetadata - Provider metadata (not used in default implementation)
+     * @returns A Promise that resolves to a Session object
+     */
+    createSession(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<Session>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/models/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/models/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACtD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,OAAO,CAAC,IAAI,GAAG,kBAAkB;IAChD;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;;;;;;OAYG;IACH,GAAG,EAAE,IAAI,CAAC;CACX;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IAEb,yBAAyB;IACzB,SAAS,EAAE;QACT,iCAAiC;QACjC,aAAa,EAAE,MAAM,CAAC;QACtB,yBAAyB;QACzB,KAAK,EAAE,MAAM,CAAC;QACd,4BAA4B;QAC5B,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgFG;IACH,aAAa,CAAC,SAAS,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpG;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,YAAW,eAAe;IAC5D;;;;;;;OAOG;IACG,aAAa,CAAC,SAAS,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAUzG"}

package/dist/providers/IProvider.d.ts

@@ -1,6 +1,134 @@
+/**
+ * Interface for OAuth 2.0 and OpenID Connect provider implementations.
+ *
+ * @remarks
+ * Implement this interface to add support for custom OAuth providers.
+ * Each provider defines the three core endpoints required for the OAuth 2.0
+ * authorization code flow with PKCE.
+ *
+ * Built-in providers (Google, GitHub) are available in the \@vunexa/lixa-providers package.
+ *
+ * All implementations must comply with:
+ * - RFC 6749 (OAuth 2.0)
+ * - RFC 7636 (PKCE)
+ * - OpenID Connect Core 1.0 (for OIDC providers)
+ *
+ * @example
+ * Custom provider implementation:
+ * ```typescript
+ * import { IProvider } from '@vunexa/lixa';
+ *
+ * class CustomProvider implements IProvider {
+ *   authorizationEndpoint = 'https://auth.example.com/oauth/authorize';
+ *   tokenEndpoint = 'https://auth.example.com/oauth/token';
+ *   userInfoEndpoint = 'https://api.example.com/user';
+ * }
+ *
+ * // Use in configuration
+ * const lixa = new Lixa({
+ *   providers: {
+ *     custom: {
+ *       provider: new CustomProvider(),
+ *       clientId: 'your-client-id',
+ *       clientSecret: 'your-client-secret',
+ *       redirectUri: 'https://app.com/callback',
+ *       scopes: ['read:user']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Object literal provider:
+ * ```typescript
+ * const customProvider: IProvider = {
+ *   authorizationEndpoint: 'https://auth.example.com/oauth/authorize',
+ *   tokenEndpoint: 'https://auth.example.com/oauth/token',
+ *   userInfoEndpoint: 'https://api.example.com/user'
+ * };
+ * ```
+ *
+ * @public
+ */
 interface IProvider {
+    /**
+     * The OAuth 2.0 authorization endpoint URL.
+     *
+     * @remarks
+     * This is the URL where users are redirected to authenticate and authorize your application.
+     * The endpoint must support the OAuth 2.0 authorization code flow with PKCE.
+     *
+     * Standard query parameters sent to this endpoint:
+     * - client_id: Your application's client ID
+     * - redirect_uri: Where to redirect after authorization
+     * - response_type: Always "code" for authorization code flow
+     * - scope: Space-separated list of requested scopes
+     * - state: Random string for CSRF protection
+     * - code_challenge: PKCE code challenge (SHA-256 hash)
+     * - code_challenge_method: Always "S256" for SHA-256
+     *
+     * @example
+     * ```typescript
+     * authorizationEndpoint = 'https://accounts.google.com/o/oauth2/v2/auth'
+     * ```
+     */
     authorizationEndpoint: string;
+    /**
+     * The OAuth 2.0 token endpoint URL.
+     *
+     * @remarks
+     * This is the URL where authorization codes are exchanged for access tokens.
+     * The endpoint must support the OAuth 2.0 token exchange with PKCE.
+     *
+     * Standard parameters sent to this endpoint (POST request):
+     * - grant_type: Always "authorization_code"
+     * - code: The authorization code from the callback
+     * - redirect_uri: Must match the authorization request
+     * - client_id: Your application's client ID
+     * - client_secret: Your application's client secret
+     * - code_verifier: PKCE code verifier (original random string)
+     *
+     * Expected response:
+     * - access_token: OAuth access token
+     * - token_type: Token type (usually "Bearer")
+     * - expires_in: Token expiration time in seconds
+     * - refresh_token: Refresh token (optional)
+     * - id_token: OpenID Connect ID token (for OIDC providers)
+     * - scope: Granted scopes
+     *
+     * @example
+     * ```typescript
+     * tokenEndpoint = 'https://oauth2.googleapis.com/token'
+     * ```
+     */
     tokenEndpoint: string;
+    /**
+     * The user information endpoint URL.
+     *
+     * @remarks
+     * This is the URL where user profile information can be retrieved using the access token.
+     * For OpenID Connect providers, this is the UserInfo endpoint.
+     *
+     * The endpoint is called with the access token in the Authorization header:
+     * ```
+     * Authorization: Bearer <access_token>
+     * ```
+     *
+     * Common response fields:
+     * - sub: Subject identifier (user ID)
+     * - email: User's email address
+     * - name: User's full name
+     * - picture: User's profile picture URL
+     * - email_verified: Whether email is verified
+     *
+     * Note: This endpoint is not called automatically by Lixa. Your SessionStrategy
+     * can call it if needed to fetch user profile information.
+     *
+     * @example
+     * ```typescript
+     * userInfoEndpoint = 'https://www.googleapis.com/oauth2/v2/userinfo'
+     * ```
+     */
     userInfoEndpoint: string;
 }
 export { IProvider };

package/dist/providers/IProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"IProvider.d.ts","sourceRoot":"","sources":["../../src/providers/IProvider.ts"],"names":[],"mappings":"AAEA,UAAU,SAAS;IACjB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"IProvider.d.ts","sourceRoot":"","sources":["../../src/providers/IProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,UAAU,SAAS;IACjB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,qBAAqB,EAAE,MAAM,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,aAAa,EAAE,MAAM,CAAC;IAEtB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/providers/index.d.ts

@@ -1,4 +1,2 @@
 export { IProvider } from "./IProvider";
-export { GithubProvider } from "./github";
-export { GoogleProvider } from "./google";
 //# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -1,31 +1,182 @@
+import { SessionHandler, SessionStorage, StateHandler, StateStorage, StateData } from "./dao/types";
+import { Session, ProviderMetadata } from "./models/session";
+import { IProvider } from "./providers/IProvider";
+export { Session };
+export { ProviderMetadata };
+export { OAuthTokenResponse } from "./models/session";
+export { IProvider };
+export { StateHandler };
+export { StateStorage };
+export { SessionHandler };
+export { SessionStorage };
+export { StateData };
 /**
+ * Configuration for an OAuth provider instance.
+ *
+ * @remarks
+ * For built-in providers (google, github), just provide credentials.
+ * For custom providers, include the provider implementation.
+ *
+ * The provider field uses a discriminated union to ensure type safety:
+ * - When omitted or undefined: assumes a built-in provider
+ * - When provided: must be a valid IProvider implementation
+ *
+ * @example
+ * Built-in provider configuration:
+ * ```typescript
+ * {
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'https://app.com/callback',
+ *   scopes: ['openid', 'email']
+ * }
+ * ```
+ *
+ * @example
+ * Custom provider configuration:
+ * ```typescript
+ * {
+ *   provider: new CustomProvider(),
+ *   clientId: 'your-client-id',
+ *   clientSecret: 'your-client-secret',
+ *   redirectUri: 'https://app.com/callback',
+ *   scopes: ['read:user']
+ * }
+ * ```
+ *
  * @public
  */
-export interface ProviderConfig {
+export type ProviderConfig = {
+    /** The OAuth client ID provided by the provider */
     clientId: string;
+    /** The OAuth client secret provided by the provider */
     clientSecret: string;
+    /** The redirect URI registered with the provider */
     redirectUri: string;
+    /** Array of OAuth scopes to request */
     scopes: string[];
-    extraConfig?: Record<string, any>;
-}
-/**
- * @public
- */
-export interface LixaConfig {
-    providers: Record<string, ProviderConfig>;
-    sessionStrategy?: SessionStrategy;
-}
+    /** Additional provider-specific configuration parameters */
+    extraConfig?: Record<string, string>;
+} & ({
+    provider?: never;
+} | {
+    provider: IProvider;
+});
 /**
+ * Main configuration object for Lixa.
+ * Provides type-safe provider name inference.
+ *
+ * @remarks
+ * The generic type parameter TProviders enables TypeScript to infer provider names
+ * from the configuration object, providing autocomplete and type checking for
+ * provider names in methods like getAuthUrl() and handleCallback().
+ *
+ * @typeParam TProviders - The provider configuration map type, defaults to a generic record
+ *
+ * @example
+ * Basic configuration with built-in providers:
+ * ```typescript
+ * import { Lixa } from '@vunexa/lixa';
+ * import { GoogleProvider } from '@vunexa/lixa-providers';
+ *
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       provider: new GoogleProvider(),
+ *       clientId: process.env.GOOGLE_CLIENT_ID!,
+ *       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *       redirectUri: 'https://app.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * Configuration with custom session and state handlers:
+ * ```typescript
+ * const lixa = new Lixa({
+ *   providers: {
+ *     google: {
+ *       provider: new GoogleProvider(),
+ *       clientId: process.env.GOOGLE_CLIENT_ID!,
+ *       clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+ *       redirectUri: 'https://app.com/auth/google/callback',
+ *       scopes: ['openid', 'email', 'profile']
+ *     }
+ *   },
+ *   stateHandler: {
+ *     storage: {
+ *       saveState: async (state, data, ttl) => await redis.setex(state, ttl, JSON.stringify(data)),
+ *       getState: async (state) => JSON.parse(await redis.get(state) || 'null'),
+ *       deleteState: async (state) => await redis.del(state)
+ *     }
+ *   },
+ *   sessionHandler: {
+ *     GenerateSession: async (tokenData, providerMetadata) => {
+ *       const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ *       const user = await db.users.upsert({ email: userInfo.email });
+ *       return { token: tokenData.access_token, raw: { ...tokenData, userId: user.id } };
+ *     },
+ *     storage: {
+ *       saveSession: async (id, session, ttl) => await db.sessions.create({ id, session, ttl }),
+ *       getSession: async (id) => await db.sessions.findOne({ id }),
+ *       deleteSession: async (id) => await db.sessions.delete({ id })
+ *     }
+ *   },
+ *   debug: true
+ * });
+ * ```
+ *
  * @public
  */
-export interface SessionStrategy {
-    createSession(userInfo: any): Promise<Session>;
+export interface LixaConfig<TProviders extends Record<string, ProviderConfig> = Record<string, ProviderConfig>> {
+    /**
+     * Map of provider names to their configurations.
+     * Provider names will be available for autocomplete in getAuthUrl() and handleCallback().
+     */
+    providers: TProviders;
+    /**
+     * Optional custom state handler.
+     * Handles state generation and storage during OAuth authorization flow.
+     *
+     * - GenerateState: Customizes how state parameters and PKCE verifiers are generated
+     * - storage: Provides persistent state storage (save/get/delete operations)
+     *
+     * Defaults to in-memory cache if not provided (not suitable for production).
+     *
+     * @see {@link StateHandler}
+     */
+    stateHandler?: StateHandler;
+    /**
+     * Optional custom session handler.
+     * Handles session generation and storage after authentication.
+     *
+     * - GenerateSession: Customizes how OAuth tokens are converted into session data
+     * - storage: Provides persistent session storage (save/get/delete operations)
+     *
+     * Defaults to in-memory cache if not provided (not suitable for production).
+     *
+     * @see {@link SessionHandler}
+     */
+    sessionHandler?: SessionHandler;
+    /**
+     * Enable debug logging.
+     * When enabled, outputs structured logs for initialization, auth flow, and errors.
+     * Format: [Lixa] [timestamp] [level] [context] message
+     */
+    debug?: boolean;
 }
 /**
+ * Helper type to create a configuration with only registered providers.
+ * Use this with Lixa.createConfig() for type safety.
+ *
+ * @deprecated This type is maintained for backward compatibility.
+ * The new inline provider configuration pattern makes this unnecessary.
+ *
  * @public
  */
-export interface Session {
-    token: string;
-    raw: any;
-}
+export type SafeLixaConfig<TProviders extends Record<string, ProviderConfig>> = LixaConfig<TProviders> & {
+    providers: TProviders;
+};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,GAAG,CAAC;CACV"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EAAE,OAAO,EAAE,CAAC;AACnB,OAAO,EAAE,gBAAgB,EAAE,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,CAAC;AACrB,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,OAAO,EAAE,YAAY,EAAE,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IAEjB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IAErB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IAEpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC,GAAG,CACA;IAAE,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GACpB;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAC1B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,MAAM,WAAW,UAAU,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC;IAC5G;;;OAGG;IACH,SAAS,EAAE,UAAU,CAAC;IAItB;;;;;;;;;;OAUG;IACH,YAAY,CAAC,EAAE,YAAY,CAAC;IAE5B;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAEhC;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,CAAC,UAAU,SAAS,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG;IACvG,SAAS,EAAE,UAAU,CAAC;CACvB,CAAC"}