@vunexa/lixa 0.0.1-alpha.9 → 0.1.1

package/dist/types.d.ts

@@ -1,10 +1,52 @@
-import { StateDao } from "./dao/types";
+import { SessionHandler, SessionStorage, StateHandler, StateStorage, StateData } from "./dao/types";
+import { ProviderMetadata } from "./models/session";
+import { IProvider } from "./providers/IProvider";
+export { Session, ConnectedResource } from "./models/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.
+ * 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 */
@@ -14,44 +56,173 @@ export interface ProviderConfig {
     /** Array of OAuth scopes to request */
     scopes: string[];
     /** Additional provider-specific configuration parameters */
-    extraConfig?: Record<string, any>;
-}
+    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
+ * });
+ * ```
+ *
+/**
+ * Strategy mode for multi-SSO identity account linking.
  *
  * @public
  */
-export interface LixaConfig {
-    /** Map of provider names to their configurations */
-    providers: Record<string, ProviderConfig>;
-    /** Optional custom session creation strategy */
-    sessionStrategy?: SessionStrategy;
-    /** Optional custom state storage implementation */
-    stateDao?: StateDao;
+export declare enum AccountLinkingStrategy {
+    /** Automatically merge identities matching the same verified primary email address */
+    AUTO_LINK_BY_VERIFIED_EMAIL = "AUTO_LINK_BY_VERIFIED_EMAIL",
+    /** Keep identity profiles isolated per provider (no automatic account merging) */
+    ISOLATED = "ISOLATED"
 }
 /**
- * Strategy interface for custom session creation.
+ * Supported mode values for account linking configuration.
+ *
+ * @public
+ */
+export type AccountLinkingMode = AccountLinkingStrategy | "AUTO_LINK_BY_VERIFIED_EMAIL" | "ISOLATED" | "linkByEmail" | "separate";
+/**
+ * Account linking settings for Lixa.
  *
  * @public
  */
-export interface SessionStrategy {
+export interface AccountLinkingConfig {
     /**
-     * Creates a session from OAuth token data.
+     * Account linking mode strategy:
+     * - AccountLinkingStrategy.AUTO_LINK_BY_VERIFIED_EMAIL ("AUTO_LINK_BY_VERIFIED_EMAIL" / "linkByEmail"): Auto-link accounts sharing same verified email.
+     * - AccountLinkingStrategy.ISOLATED ("ISOLATED" / "separate"): Keep provider accounts isolated (default).
      *
-     * @param userInfo - The token data received from the OAuth provider
-     * @returns A Promise that resolves to a Session object
+     * @default AccountLinkingStrategy.ISOLATED
      */
-    createSession(userInfo: any): Promise<Session>;
+    mode?: AccountLinkingMode;
+    /**
+     * Whether to require that the email address is verified by the provider before linking.
+     *
+     * @default true
+     */
+    requireVerifiedEmail?: boolean;
 }
 /**
- * Represents a user session after successful OAuth authentication.
+ * Main configuration object for Lixa.
+ * Provides type-safe provider name inference.
  *
  * @public
  */
-export interface Session {
-    /** The session token (typically the access token) */
-    token: string;
-    /** Raw token data from the OAuth provider */
-    raw: any;
+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;
+    /**
+     * Account linking configuration for multi-SSO user linking.
+     */
+    accountLinking?: AccountLinkingConfig;
+    /**
+     * 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 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,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC1C,gDAAgD;IAChD,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,mDAAmD;IACnD,QAAQ,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,WAAW,OAAO;IACtB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,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,EAAW,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC9D,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AACH,oBAAY,sBAAsB;IAChC,sFAAsF;IACtF,2BAA2B,gCAAgC;IAE3D,kFAAkF;IAClF,QAAQ,aAAa;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B,sBAAsB,GACtB,6BAA6B,GAC7B,UAAU,GACV,aAAa,GACb,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAE1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;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;IAEtB;;OAEG;IACH,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC;;;;;;;;;;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"}

package/dist/utils/user-info.d.ts

@@ -0,0 +1,82 @@
+import type { OAuthTokenResponse, ProviderMetadata } from "../models/session";
+/**
+ * User information extracted from OAuth provider
+ *
+ * @public
+ */
+export interface UserInfo {
+    email: string;
+    id?: string | undefined;
+    sub?: string | undefined;
+    given_name?: string | undefined;
+    family_name?: string | undefined;
+    name?: string | undefined;
+    picture?: string | undefined;
+    email_verified?: boolean | undefined;
+    iss?: string | undefined;
+}
+/**
+ * Decode JWT ID token to extract user information
+ *
+ * @public
+ */
+export declare function decodeIdToken(idToken: string): UserInfo;
+/**
+ * Determine OAuth provider from ID token issuer
+ *
+ * @public
+ */
+export declare function determineProviderFromIssuer(userInfo: UserInfo): string | null;
+/**
+ * Fetch user info from OAuth provider's userinfo endpoint
+ *
+ * @param accessToken - OAuth access token
+ * @param userInfoEndpoint - The provider's userinfo endpoint URL
+ * @param providerName - Provider name for error messages (optional)
+ * @returns User information from the provider
+ *
+ * @throws Error if the request fails or response is invalid
+ *
+ * @public
+ */
+export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
+/**
+ * Extract user info from OAuth token data
+ *
+ * @param tokenData - OAuth token response from provider
+ * @param providerMetadata - Provider metadata containing endpoints configuration
+ * @returns User info extracted from token or fetched from provider
+ *
+ * @remarks
+ * This function attempts to extract user information in the following order:
+ * 1. Decode ID token if present (preferred method for OIDC providers)
+ * 2. Fetch from userinfo endpoint using access token (uses providerMetadata.endpoints.userInfo)
+ *
+ * The function automatically determines the best method based on available token data.
+ * For OIDC providers (like Google), it decodes the JWT ID token.
+ * For OAuth-only providers (like GitHub), it fetches from the userinfo endpoint.
+ *
+ * @throws Error if no ID token or access token is available
+ * @throws Error if userinfo endpoint is required but not provided in providerMetadata
+ *
+ * @example
+ * With ID token (OIDC provider like Google):
+ * ```typescript
+ * const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ * console.log(`User ${userInfo.email} authenticated`);
+ * ```
+ *
+ * @example
+ * Without ID token (OAuth provider like GitHub):
+ * ```typescript
+ * const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ * // Automatically fetches from providerMetadata.endpoints.userInfo
+ * console.log(`User ${userInfo.email} authenticated`);
+ * ```
+ *
+ * @public
+ */
+export declare function extractUserInfo(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<{
+    userInfo: UserInfo;
+}>;
+//# sourceMappingURL=user-info.d.ts.map

package/dist/utils/user-info.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-info.d.ts","sourceRoot":"","sources":["../../src/utils/user-info.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE9E;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAiBvD;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAiB7E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,QAAQ,CAAC,CA4BnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,kBAAkB,EAC7B,gBAAgB,EAAE,gBAAgB,GACjC,OAAO,CAAC;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC,CAejC"}

package/docs/api/index.md

@@ -0,0 +1,32 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+<table><thead><tr><th>
+
+Package
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[@vunexa/lixa](./lixa.md)
+
+
+</td><td>
+
+A flexible, provider-agnostic OAuth 2.0 and OpenID Connect (OIDC) client library for backend applications.
+
+
+</td></tr>
+</tbody></table>
+

package/docs/api/lixa.iprovider.authorizationendpoint.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [IProvider](./lixa.iprovider.md) &gt; [authorizationEndpoint](./lixa.iprovider.authorizationendpoint.md)
+
+## IProvider.authorizationEndpoint property
+
+The OAuth authorization endpoint URL
+
+**Signature:**
+
+```typescript
+authorizationEndpoint: string;
+```

package/docs/api/lixa.iprovider.md

@@ -0,0 +1,100 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [IProvider](./lixa.iprovider.md)
+
+## IProvider interface
+
+Interface for OAuth provider implementations.
+
+**Signature:**
+
+```typescript
+interface IProvider 
+```
+
+## Remarks
+
+Implement this interface to add support for custom OAuth providers.
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+
+</th><th>
+
+Modifiers
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[authorizationEndpoint](./lixa.iprovider.authorizationendpoint.md)
+
+
+</td><td>
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The OAuth authorization endpoint URL
+
+
+</td></tr>
+<tr><td>
+
+[tokenEndpoint](./lixa.iprovider.tokenendpoint.md)
+
+
+</td><td>
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The OAuth token exchange endpoint URL
+
+
+</td></tr>
+<tr><td>
+
+[userInfoEndpoint](./lixa.iprovider.userinfoendpoint.md)
+
+
+</td><td>
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The user information endpoint URL
+
+
+</td></tr>
+</tbody></table>
+

package/docs/api/lixa.iprovider.tokenendpoint.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [IProvider](./lixa.iprovider.md) &gt; [tokenEndpoint](./lixa.iprovider.tokenendpoint.md)
+
+## IProvider.tokenEndpoint property
+
+The OAuth token exchange endpoint URL
+
+**Signature:**
+
+```typescript
+tokenEndpoint: string;
+```

package/docs/api/lixa.iprovider.userinfoendpoint.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [IProvider](./lixa.iprovider.md) &gt; [userInfoEndpoint](./lixa.iprovider.userinfoendpoint.md)
+
+## IProvider.userInfoEndpoint property
+
+The user information endpoint URL
+
+**Signature:**
+
+```typescript
+userInfoEndpoint: string;
+```

package/docs/api/lixa.lixa._constructor_.md

@@ -0,0 +1,50 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [Lixa](./lixa.lixa.md) &gt; [(constructor)](./lixa.lixa._constructor_.md)
+
+## Lixa.(constructor)
+
+Creates a new Lixa instance with the provided configuration.
+
+**Signature:**
+
+```typescript
+constructor(config: LixaConfig);
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+config
+
+
+</td><td>
+
+[LixaConfig](./lixa.lixaconfig.md)
+
+
+</td><td>
+
+The configuration object containing provider settings and optional session strategy
+
+
+</td></tr>
+</tbody></table>
+

package/docs/api/lixa.lixa.generaterandomstate.md

@@ -0,0 +1,23 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [Lixa](./lixa.lixa.md) &gt; [generateRandomState](./lixa.lixa.generaterandomstate.md)
+
+## Lixa.generateRandomState() method
+
+Generates a cryptographically secure random state parameter for OAuth flows.
+
+**Signature:**
+
+```typescript
+static generateRandomState(): string;
+```
+**Returns:**
+
+string
+
+A 32-character hexadecimal string
+
+## Remarks
+
+The state parameter is used to prevent CSRF attacks in OAuth flows.
+

package/docs/api/lixa.lixa.getauthurl.md

@@ -0,0 +1,85 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@vunexa/lixa](./lixa.md) &gt; [Lixa](./lixa.lixa.md) &gt; [getAuthUrl](./lixa.lixa.getauthurl.md)
+
+## Lixa.getAuthUrl() method
+
+Generates the authorization URL for the specified provider.
+
+**Signature:**
+
+```typescript
+getAuthUrl(provider: string, state: string): string;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+provider
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The provider name (case-insensitive)
+
+
+</td></tr>
+<tr><td>
+
+state
+
+
+</td><td>
+
+string
+
+
+</td><td>
+
+The state parameter for CSRF protection
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+string
+
+The complete authorization URL to redirect users to
+
+## Exceptions
+
+Error when the provider is not configured
+
+## Example
+
+
+```typescript
+const state = Lixa.generateRandomState();
+const authUrl = lixa.getAuthUrl('google', state);
+res.redirect(authUrl);
+```
+