@vunexa/lixa 0.0.1-alpha.27 → 0.0.1-alpha.29

package/README.md

@@ -558,15 +558,11 @@ import { extractUserInfo, type UserInfo } from "@vunexa/lixa";
 
 // In your session strategy
 const sessionStrategy = {
-  createSession: async (tokenData) => {
+  createSession: async (tokenData, providerMetadata) => {
     // Automatically extracts user info from ID token or fetches from API
-    const { userInfo, provider } = await extractUserInfo(
-      tokenData,
-      providerConfig.userInfoEndpoint,  // Optional: from IProvider
-      'google'  // Optional: provider name for error messages
-    );
+    const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
     
-    console.log(`User ${userInfo.email} authenticated via ${provider}`);
+    console.log(`User ${userInfo.email} authenticated`);
     
     // Create user in database
     const user = await db.users.upsert({
@@ -587,17 +583,16 @@ const sessionStrategy = {
 
 **Parameters:**
 - `tokenData` (OAuthTokenResponse) - OAuth token response from provider
-- `userInfoEndpoint` (string, optional) - Provider's userinfo endpoint URL (required if no ID token)
-- `providerName` (string, optional) - Provider name for error messages
+- `providerMetadata` (ProviderMetadata) - Provider metadata containing endpoints configuration
 
 **Returns:**
-- `{ userInfo: UserInfo, provider: string }` - User information and detected provider name
+- `{ userInfo: UserInfo }` - User information extracted from token or fetched from provider
 
 **Behavior:**
-1. If ID token present: Decodes JWT and extracts user info
-2. If only access token: Fetches from userinfo endpoint
-3. Provider detection: From ID token issuer, token data, or parameter
-4. Throws clear errors if provider cannot be determined
+1. If ID token present: Decodes JWT and extracts user info (OIDC providers like Google)
+2. If only access token: Fetches from userinfo endpoint using `providerMetadata.endpoints.userInfo` (OAuth providers like GitHub)
+3. Automatically determines the best method based on available token data
+4. Throws clear errors if neither ID token nor access token is available
 
 ### `decodeIdToken()`
 
@@ -645,6 +640,8 @@ const provider = determineProviderFromIssuer(userInfo);
 - GitHub: Detects `github` in issuer
 - Returns `null` for unknown issuers
 
+**Note:** This utility is primarily for informational purposes. The `extractUserInfo()` function no longer returns provider information as it now relies on `providerMetadata` parameter.
+
 ### `UserInfo` Type
 
 Standard user information structure across all providers:
@@ -688,11 +685,11 @@ const lixa = new Lixa({
   },
   
   sessionStrategy: {
-    createSession: async (tokenData) => {
+    createSession: async (tokenData, providerMetadata) => {
       // Extract user info - works for both Google (ID token) and GitHub (API fetch)
-      const { userInfo, provider } = await extractUserInfo(tokenData);
+      const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
       
-      console.log(`User ${userInfo.email} authenticated via ${provider}`);
+      console.log(`User ${userInfo.email} authenticated`);
       
       // Create or update user in database
       const user = await db.users.upsert({
@@ -709,7 +706,6 @@ const lixa = new Lixa({
       await db.sessions.create({
         id: sessionId,
         userId: user.id,
-        provider,
         accessToken: tokenData.access_token,
         refreshToken: tokenData.refresh_token,
         expiresAt: tokenData.expires_in 
@@ -722,7 +718,6 @@ const lixa = new Lixa({
         raw: {
           ...tokenData,
           userId: user.id,
-          provider,
         }
       };
     }
@@ -733,11 +728,11 @@ const lixa = new Lixa({
 ### Benefits of User Info Utilities
 
 ✅ **Provider-agnostic** - Works with any OAuth provider  
-✅ **Automatic detection** - Determines provider from token data  
+✅ **Automatic method selection** - Uses ID token or fetches from API based on what's available  
 ✅ **Type-safe** - Full TypeScript support with UserInfo interface  
-✅ **Flexible** - Supports both ID token and API fetching  
-✅ **Error handling** - Clear error messages when provider cannot be determined  
-✅ **Uses IProvider** - Leverages userInfoEndpoint from provider configuration  
+✅ **Flexible** - Supports both OIDC (ID token) and OAuth-only (API fetch) providers  
+✅ **Error handling** - Clear error messages when token data is invalid  
+✅ **Uses provider metadata** - Leverages userInfoEndpoint from provider configuration  
 
 ## API Reference
 

package/dist/export-types/index.d.ts

@@ -40,9 +40,10 @@ export declare class DefaultSessionStrategy implements SessionStrategy {
      * 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): Promise<Session>;
+    createSession(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<Session>;
 }
 
 /**
@@ -56,47 +57,40 @@ export declare function determineProviderFromIssuer(userInfo: UserInfo): string
  * Extract user info from OAuth token data
  *
  * @param tokenData - OAuth token response from provider
- * @param userInfoEndpoint - Optional userinfo endpoint URL (required if no ID token)
- * @param providerName - Optional provider name for error messages
- * @returns User info and detected provider name
+ * @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)
- * 2. Fetch from userinfo endpoint using access token (requires userInfoEndpoint parameter)
+ * 1. Decode ID token if present (preferred method for OIDC providers)
+ * 2. Fetch from userinfo endpoint using access token (uses providerMetadata.endpoints.userInfo)
  *
- * Provider detection:
- * - Primary: Extract from ID token issuer field
- * - Fallback: Use provider field in token data (if present)
- * - Fallback: Use providerName parameter
- * - Throws error if provider cannot be determined
+ * 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 provider cannot be determined
- * @throws Error if userInfoEndpoint is required but not provided
+ * @throws Error if userinfo endpoint is required but not provided in providerMetadata
  *
  * @example
- * With ID token (provider auto-detected):
+ * With ID token (OIDC provider like Google):
  * ```typescript
- * const { userInfo, provider } = await extractUserInfo(tokenData);
- * console.log(`User ${userInfo.email} authenticated via ${provider}`);
+ * const { userInfo } = await extractUserInfo(tokenData, providerMetadata);
+ * console.log(`User ${userInfo.email} authenticated`);
  * ```
  *
  * @example
- * Without ID token (requires userInfoEndpoint):
+ * Without ID token (OAuth provider like GitHub):
  * ```typescript
- * const { userInfo, provider } = await extractUserInfo(
- *   tokenData,
- *   'https://api.example.com/user',
- *   'custom'
- * );
+ * 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, userInfoEndpoint?: string, providerName?: string): Promise<{
+export declare function extractUserInfo(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<{
     userInfo: UserInfo;
-    provider: string;
 }>;
 
 /**
@@ -111,7 +105,7 @@ export declare function extractUserInfo(tokenData: OAuthTokenResponse, userInfoE
  *
  * @public
  */
-export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string, providerName?: string): Promise<UserInfo>;
+export declare function fetchUserInfo(accessToken: string, userInfoEndpoint: string): Promise<UserInfo>;
 
 /**
  * Interface for OAuth 2.0 and OpenID Connect provider implementations.
@@ -769,6 +763,26 @@ export declare type ProviderConfig = {
     provider: IProvider;
 });
 
+/**
+ * Provider metadata passed to session strategy.
+ * Contains provider name and endpoints for user info extraction.
+ *
+ * @public
+ */
+export declare 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;
+    };
+}
+
 /**
  * Helper type to create a configuration with only registered providers.
  * Use this with Lixa.createConfig() for type safety.
@@ -942,24 +956,27 @@ export declare interface SessionDao {
  * @example
  * Custom session strategy with database integration:
  * ```typescript
- * interface CustomSessionData extends OAuthTokenResponse {
+ * interface CustomSessionData {
  *   userId: string;
  *   email: string;
+ *   provider: string;
+ *   accessToken: string;
+ *   refreshToken?: string;
+ *   expiresAt: number;
  * }
  *
  * class DatabaseSessionStrategy implements SessionStrategy {
  *   constructor(private db: Database) {}
  *
- *   async createSession(tokenData: OAuthTokenResponse): Promise<Session<CustomSessionData>> {
- *     // Decode ID token for OIDC providers
- *     const idToken = tokenData.id_token;
- *     const payload = decodeJwt(idToken);
+ *   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: payload.email,
- *       name: payload.name,
- *       picture: payload.picture
+ *       email: userInfo.email,
+ *       name: userInfo.name,
+ *       picture: userInfo.picture
  *     });
  *
  *     // Generate session ID
@@ -979,7 +996,10 @@ export declare interface SessionDao {
  *       raw: {
  *         userId: user.id,
  *         email: user.email,
- *         ...tokenData
+ *         provider,
+ *         accessToken: tokenData.access_token,
+ *         refreshToken: tokenData.refresh_token,
+ *         expiresAt: Date.now() + (tokenData.expires_in || 3600) * 1000
  *       }
  *     };
  *   }
@@ -993,14 +1013,14 @@ export declare 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. The tokenData parameter contains the raw response from the
-     * provider's token endpoint.
+     * for tokens. You receive:
      *
-     * Common token data fields:
+     * Token Data:
      * - access_token: OAuth access token
      * - refresh_token: OAuth refresh token (optional)
      * - expires_in: Token expiration time in seconds
@@ -1008,6 +1028,28 @@ export declare interface SessionStrategy {
      * - 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
@@ -1020,8 +1062,35 @@ export declare interface SessionStrategy {
      *   };
      * }
      * ```
+     *
+     * @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): Promise<Session>;
+    createSession(tokenData: OAuthTokenResponse, providerMetadata: ProviderMetadata): Promise<Session>;
 }
 
 /**

package/dist/index.cjs

@@ -88,9 +88,10 @@ var DefaultSessionStrategy = class {
    * 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
    */
-  async createSession(tokenData) {
+  async createSession(tokenData, providerMetadata) {
     if (!tokenData.access_token || typeof tokenData.access_token !== "string") {
       throw new Error("No valid access token found in OAuth response");
     }
@@ -549,7 +550,15 @@ var Lixa = class _Lixa {
     );
     this.log("INFO", "Token", "Token exchange successful");
     this.log("INFO", "Session", "Creating user session");
-    const session = await this.sessionStrategy.createSession(tokens);
+    const providerMetadata = {
+      name: providerType,
+      endpoints: {
+        authorization: providerImpl.authorizationEndpoint,
+        token: providerImpl.tokenEndpoint,
+        userInfo: providerImpl.userInfoEndpoint
+      }
+    };
+    const session = await this.sessionStrategy.createSession(tokens, providerMetadata);
     const sessionId = (0, import_crypto.randomBytes)(32).toString("hex");
     this.log("INFO", "Session", "Storing session", { sessionId });
     await this.sesionDao.saveSession(sessionId, session, 86400);
@@ -636,7 +645,7 @@ function determineProviderFromIssuer(userInfo) {
   }
   return null;
 }
-async function fetchUserInfo(accessToken, userInfoEndpoint, providerName) {
+async function fetchUserInfo(accessToken, userInfoEndpoint) {
   const response = await fetch(userInfoEndpoint, {
     headers: {
       Authorization: `Bearer ${accessToken}`,
@@ -644,13 +653,11 @@ async function fetchUserInfo(accessToken, userInfoEndpoint, providerName) {
     }
   });
   if (!response.ok) {
-    const providerLabel = providerName ? ` from ${providerName}` : "";
-    throw new Error(`Failed to fetch user info${providerLabel}: ${response.status} ${response.statusText}`);
+    throw new Error(`Failed to fetch user info: ${response.status} ${response.statusText}`);
   }
   const data = await response.json();
   if (!data || typeof data !== "object" || !("email" in data) || typeof data.email !== "string") {
-    const providerLabel = providerName ? ` from ${providerName}` : "";
-    throw new Error(`Invalid user info response${providerLabel}: missing or invalid email`);
+    throw new Error(`Invalid user info response: missing or invalid email`);
   }
   return {
     email: data.email,
@@ -664,41 +671,17 @@ async function fetchUserInfo(accessToken, userInfoEndpoint, providerName) {
     iss: "iss" in data ? String(data.iss) : void 0
   };
 }
-async function extractUserInfo(tokenData, userInfoEndpoint, providerName) {
+async function extractUserInfo(tokenData, providerMetadata) {
   let userInfo;
-  let provider = null;
+  const userInfoEndpoint = providerMetadata.endpoints.userInfo;
   if (tokenData.id_token) {
     userInfo = decodeIdToken(tokenData.id_token);
-    provider = determineProviderFromIssuer(userInfo);
-    if (!provider && providerName) {
-      provider = providerName;
-    }
   } else if (tokenData.access_token) {
-    if ("provider" in tokenData && typeof tokenData.provider === "string") {
-      provider = tokenData.provider;
-    } else if (providerName) {
-      provider = providerName;
-    }
-    if (!provider) {
-      throw new Error(
-        "Cannot determine OAuth provider: No ID token with issuer information, no provider field in token data, and no providerName provided. Unable to fetch user info."
-      );
-    }
-    if (!userInfoEndpoint) {
-      throw new Error(
-        `Cannot fetch user info for provider '${provider}': No ID token available and no userInfoEndpoint provided. Either ensure the provider returns an ID token or provide the userInfoEndpoint parameter.`
-      );
-    }
-    userInfo = await fetchUserInfo(tokenData.access_token, userInfoEndpoint, provider);
+    userInfo = await fetchUserInfo(tokenData.access_token, userInfoEndpoint);
   } else {
     throw new Error("No ID token or access token available to fetch user info");
   }
-  if (!provider) {
-    throw new Error(
-      "Cannot determine OAuth provider: ID token issuer not recognized and no provider name provided."
-    );
-  }
-  return { userInfo, provider };
+  return { userInfo };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {