@adonisjs/ally 5.1.1 → 6.0.0-next.0

package/build/src/drivers/github.js

@@ -1,11 +1,15 @@
 import {
   Oauth2Driver
-} from "../../chunk-GWAQFMNS.js";
-import "../../chunk-N72DEJC2.js";
-import "../../chunk-PZ5AY32C.js";
+} from "../../chunk-WM3V3APX.js";
+import "../../chunk-KSJ4CFTC.js";
+import "../../chunk-MLKGABMK.js";
 
 // src/drivers/github.ts
 var GithubDriver = class extends Oauth2Driver {
+  /**
+   * @param ctx - The HTTP context
+   * @param config - Configuration for the GitHub driver
+   */
   constructor(ctx, config) {
     super(ctx, config);
     this.config = config;
@@ -41,7 +45,10 @@ var GithubDriver = class extends Oauth2Driver {
    */
   scopesSeparator = " ";
   /**
-   * Configuring the redirect request with defaults
+   * Configures the redirect request with default scopes and GitHub-specific
+   * parameters like allow_signup and login.
+   *
+   * @param request - The redirect request to configure
    */
   configureRedirectRequest(request) {
     request.scopes(this.config.scopes || ["user"]);
@@ -53,7 +60,10 @@ var GithubDriver = class extends Oauth2Driver {
     }
   }
   /**
-   * Configuring the access token API request to send extra fields
+   * Configures the access token request with GitHub-specific requirements.
+   * GitHub doesn't accept the grant_type field that is set by default.
+   *
+   * @param request - The API request to configure
    */
   configureAccessTokenRequest(request) {
     if (!this.isStateless) {
@@ -62,7 +72,11 @@ var GithubDriver = class extends Oauth2Driver {
     request.clearField("grant_type");
   }
   /**
-   * Returns the HTTP request with the authorization header set
+   * Creates an authenticated HTTP request with the proper authorization
+   * header for GitHub API calls.
+   *
+   * @param url - The API endpoint URL
+   * @param token - The access token
    */
   getAuthenticatedRequest(url, token) {
     const request = this.httpClient(url);
@@ -72,8 +86,12 @@ var GithubDriver = class extends Oauth2Driver {
     return request;
   }
   /**
-   * Fetches the user info from the Github API
-   * https://docs.github.com/en/rest/reference/users#get-the-authenticated-user
+   * Fetches the authenticated user's profile information from the GitHub API.
+   *
+   * @param token - The access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @see https://docs.github.com/en/rest/reference/users#get-the-authenticated-user
    */
   async getUserInfo(token, callback) {
     const request = this.getAuthenticatedRequest(this.config.userInfoUrl || this.userInfoUrl, token);
@@ -93,8 +111,14 @@ var GithubDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Fetches the user email from the Github API.
-   * https://docs.github.com/en/rest/reference/users#list-email-addresses-for-the-authenticated-user
+   * Fetches the user's email addresses from the GitHub API. This is needed
+   * when the user's email is not included in the basic profile response.
+   * Returns the primary verified email, or the first available email.
+   *
+   * @param token - The access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @see https://docs.github.com/en/rest/reference/users#list-email-addresses-for-the-authenticated-user
    */
   async getUserEmail(token, callback) {
     const request = this.getAuthenticatedRequest(
@@ -120,7 +144,8 @@ var GithubDriver = class extends Oauth2Driver {
     }
   }
   /**
-   * Find if the current error code is for access denied
+   * Check if the error from the callback indicates that the user
+   * denied authorization.
    */
   accessDenied() {
     const error = this.getError();
@@ -130,7 +155,16 @@ var GithubDriver = class extends Oauth2Driver {
     return error === "access_denied";
   }
   /**
-   * Returns details for the authorized user
+   * Get the authenticated user's profile and email information using
+   * the authorization code from the callback request.
+   *
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('github').user()
+   * console.log(user.name, user.email)
+   * ```
    */
   async user(callback) {
     const token = await this.accessToken(callback);
@@ -149,7 +183,16 @@ var GithubDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Finds the user by the access token
+   * Get the user's profile and email information using an existing
+   * access token.
+   *
+   * @param token - The GitHub access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('github').userFromToken(accessToken)
+   * ```
    */
   async userFromToken(token, callback) {
     const user = await this.getUserInfo(token, callback);
@@ -170,4 +213,3 @@ var GithubDriver = class extends Oauth2Driver {
 export {
   GithubDriver
 };
-//# sourceMappingURL=github.js.map

package/build/src/drivers/google.d.ts

@@ -1,9 +1,39 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { HttpClient } from '@poppinss/oauth-client';
-import type { GoogleToken, GoogleScopes, GoogleDriverConfig, ApiRequestContract, RedirectRequestContract } from '../types.js';
-import { Oauth2Driver } from '../abstract_drivers/oauth2.js';
+import type { GoogleToken, GoogleScopes, GoogleDriverConfig, ApiRequestContract, RedirectRequestContract } from '../types.ts';
+import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
 /**
- * Google driver to login user via Google
+ * Google OAuth2 driver for authenticating users via Google.
+ * Supports fetching user profile information including name, email, and profile picture.
+ * Automatically prefixes scopes with the appropriate Google API URL.
+ *
+ * @example
+ * ```ts
+ * router.get('/google/redirect', ({ ally }) => {
+ *   return ally.use('google').redirect((request) => {
+ *     request.scopes(['userinfo.email', 'userinfo.profile', 'calendar.readonly'])
+ *   })
+ * })
+ *
+ * router.get('/google/callback', async ({ ally }) => {
+ *   const google = ally.use('google')
+ *
+ *   if (google.accessDenied()) {
+ *     return 'Access was denied'
+ *   }
+ *
+ *   if (google.stateMisMatch()) {
+ *     return 'State mismatch error'
+ *   }
+ *
+ *   if (google.hasError()) {
+ *     return google.getError()
+ *   }
+ *
+ *   const user = await google.user()
+ *   return user
+ * })
+ * ```
  */
 export declare class GoogleDriver extends Oauth2Driver<GoogleToken, GoogleScopes> {
     config: GoogleDriverConfig;
@@ -35,17 +65,31 @@ export declare class GoogleDriver extends Oauth2Driver<GoogleToken, GoogleScopes
      * Scopes separator
      */
     protected scopesSeparator: string;
+    /**
+     * @param ctx - The HTTP context
+     * @param config - Configuration for the Google driver
+     */
     constructor(ctx: HttpContext, config: GoogleDriverConfig);
     /**
-     * Configuring the redirect request with defaults
+     * Configures the redirect request with default scopes and Google-specific
+     * parameters like access_type, prompt, display, and hosted domain.
+     *
+     * @param request - The redirect request to configure
      */
     protected configureRedirectRequest(request: RedirectRequestContract<GoogleScopes>): void;
     /**
-     * Returns the HTTP request with the authorization header set
+     * Creates an authenticated HTTP request with the proper authorization
+     * header for Google API calls.
+     *
+     * @param url - The API endpoint URL
+     * @param token - The access token
      */
     protected getAuthenticatedRequest(url: string, token: string): HttpClient;
     /**
-     * Fetches the user info from the Google API
+     * Fetches the authenticated user's profile information from the Google API.
+     *
+     * @param token - The access token
+     * @param callback - Optional callback to customize the API request
      */
     protected getUserInfo(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         id: any;
@@ -57,15 +101,28 @@ export declare class GoogleDriver extends Oauth2Driver<GoogleToken, GoogleScopes
         original: any;
     }>;
     /**
-     * Find if the current error code is for access denied
+     * Check if the error from the callback indicates that the user
+     * denied authorization.
      */
     accessDenied(): boolean;
     /**
-     * Get access token
+     * Get the access token using the authorization code from the callback request.
+     * Returns a GoogleToken that includes the ID token.
+     *
+     * @param callback - Optional callback to customize the API request
      */
     accessToken(callback?: (request: ApiRequestContract) => void): Promise<GoogleToken>;
     /**
-     * Returns details for the authorized user
+     * Get the authenticated user's profile information using
+     * the authorization code from the callback request.
+     *
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('google').user()
+     * console.log(user.name, user.email)
+     * ```
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<{
         token: GoogleToken;
@@ -78,7 +135,16 @@ export declare class GoogleDriver extends Oauth2Driver<GoogleToken, GoogleScopes
         original: any;
     }>;
     /**
-     * Finds the user by the access token
+     * Get the user's profile information using an existing
+     * access token.
+     *
+     * @param token - The Google access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('google').userFromToken(accessToken)
+     * ```
      */
     userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         token: {
@@ -94,7 +160,10 @@ export declare class GoogleDriver extends Oauth2Driver<GoogleToken, GoogleScopes
         original: any;
     }>;
     /**
-     * Prefixes google scopes with the url
+     * Prefixes Google scopes with the appropriate API URL.
+     * Converts short scope names like 'userinfo.email' to full URLs.
+     *
+     * @param scopes - Array of scope names to prefix
      */
     buildScopes(scopes: string[]): string[];
 }

package/build/src/drivers/google.js

@@ -1,8 +1,8 @@
 import {
   Oauth2Driver
-} from "../../chunk-GWAQFMNS.js";
-import "../../chunk-N72DEJC2.js";
-import "../../chunk-PZ5AY32C.js";
+} from "../../chunk-WM3V3APX.js";
+import "../../chunk-KSJ4CFTC.js";
+import "../../chunk-MLKGABMK.js";
 
 // src/drivers/google.ts
 var SCOPE_PREFIXES = {
@@ -43,6 +43,10 @@ var SCOPE_PREFIXES = {
   ]
 };
 var GoogleDriver = class extends Oauth2Driver {
+  /**
+   * @param ctx - The HTTP context
+   * @param config - Configuration for the Google driver
+   */
   constructor(ctx, config) {
     super(ctx, config);
     this.config = config;
@@ -77,7 +81,10 @@ var GoogleDriver = class extends Oauth2Driver {
    */
   scopesSeparator = " ";
   /**
-   * Configuring the redirect request with defaults
+   * Configures the redirect request with default scopes and Google-specific
+   * parameters like access_type, prompt, display, and hosted domain.
+   *
+   * @param request - The redirect request to configure
    */
   configureRedirectRequest(request) {
     request.transformScopes((scopes) => this.buildScopes(scopes));
@@ -97,7 +104,11 @@ var GoogleDriver = class extends Oauth2Driver {
     }
   }
   /**
-   * Returns the HTTP request with the authorization header set
+   * Creates an authenticated HTTP request with the proper authorization
+   * header for Google API calls.
+   *
+   * @param url - The API endpoint URL
+   * @param token - The access token
    */
   getAuthenticatedRequest(url, token) {
     const request = this.httpClient(url);
@@ -107,7 +118,10 @@ var GoogleDriver = class extends Oauth2Driver {
     return request;
   }
   /**
-   * Fetches the user info from the Google API
+   * Fetches the authenticated user's profile information from the Google API.
+   *
+   * @param token - The access token
+   * @param callback - Optional callback to customize the API request
    */
   async getUserInfo(token, callback) {
     const request = this.getAuthenticatedRequest(this.config.userInfoUrl || this.userInfoUrl, token);
@@ -126,7 +140,8 @@ var GoogleDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Find if the current error code is for access denied
+   * Check if the error from the callback indicates that the user
+   * denied authorization.
    */
   accessDenied() {
     const error = this.getError();
@@ -136,7 +151,10 @@ var GoogleDriver = class extends Oauth2Driver {
     return error === "access_denied";
   }
   /**
-   * Get access token
+   * Get the access token using the authorization code from the callback request.
+   * Returns a GoogleToken that includes the ID token.
+   *
+   * @param callback - Optional callback to customize the API request
    */
   async accessToken(callback) {
     const token = await super.accessToken(callback);
@@ -146,7 +164,16 @@ var GoogleDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Returns details for the authorized user
+   * Get the authenticated user's profile information using
+   * the authorization code from the callback request.
+   *
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('google').user()
+   * console.log(user.name, user.email)
+   * ```
    */
   async user(callback) {
     const token = await this.accessToken(callback);
@@ -157,7 +184,16 @@ var GoogleDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Finds the user by the access token
+   * Get the user's profile information using an existing
+   * access token.
+   *
+   * @param token - The Google access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('google').userFromToken(accessToken)
+   * ```
    */
   async userFromToken(token, callback) {
     const user = await this.getUserInfo(token, callback);
@@ -167,7 +203,10 @@ var GoogleDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Prefixes google scopes with the url
+   * Prefixes Google scopes with the appropriate API URL.
+   * Converts short scope names like 'userinfo.email' to full URLs.
+   *
+   * @param scopes - Array of scope names to prefix
    */
   buildScopes(scopes) {
     return scopes.map((name) => {
@@ -181,4 +220,3 @@ var GoogleDriver = class extends Oauth2Driver {
 export {
   GoogleDriver
 };
-//# sourceMappingURL=google.js.map

package/build/src/drivers/linked_in.d.ts

@@ -1,9 +1,39 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { HttpClient } from '@poppinss/oauth-client';
-import type { LinkedInToken, LinkedInScopes, ApiRequestContract, LinkedInDriverConfig, RedirectRequestContract } from '../types.js';
-import { Oauth2Driver } from '../abstract_drivers/oauth2.js';
+import type { LinkedInToken, LinkedInScopes, ApiRequestContract, LinkedInDriverConfig, RedirectRequestContract } from '../types.ts';
+import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
 /**
- * LinkedIn driver to login user via LinkedIn
+ * LinkedIn OAuth2 driver for authenticating users via LinkedIn.
+ * Supports fetching user profile information including name, email, and profile picture.
+ * Note: This driver fetches email separately as it's not included in the basic profile.
+ *
+ * @example
+ * ```ts
+ * router.get('/linkedin/redirect', ({ ally }) => {
+ *   return ally.use('linkedin').redirect((request) => {
+ *     request.scopes(['r_emailaddress', 'r_liteprofile'])
+ *   })
+ * })
+ *
+ * router.get('/linkedin/callback', async ({ ally }) => {
+ *   const linkedin = ally.use('linkedin')
+ *
+ *   if (linkedin.accessDenied()) {
+ *     return 'Access was denied'
+ *   }
+ *
+ *   if (linkedin.stateMisMatch()) {
+ *     return 'State mismatch error'
+ *   }
+ *
+ *   if (linkedin.hasError()) {
+ *     return linkedin.getError()
+ *   }
+ *
+ *   const user = await linkedin.user()
+ *   return user
+ * })
+ * ```
  */
 export declare class LinkedInDriver extends Oauth2Driver<LinkedInToken, LinkedInScopes> {
     config: LinkedInDriverConfig;
@@ -36,17 +66,30 @@ export declare class LinkedInDriver extends Oauth2Driver<LinkedInToken, LinkedIn
      * Scopes separator
      */
     protected scopesSeparator: string;
+    /**
+     * @param ctx - The HTTP context
+     * @param config - Configuration for the LinkedIn driver
+     */
     constructor(ctx: HttpContext, config: LinkedInDriverConfig);
     /**
-     * Configuring the redirect request with defaults
+     * Configures the redirect request with default scopes.
+     *
+     * @param request - The redirect request to configure
      */
     protected configureRedirectRequest(request: RedirectRequestContract<LinkedInScopes>): void;
     /**
-     * Returns the HTTP request with the authorization header set
+     * Creates an authenticated HTTP request with the proper authorization
+     * header for LinkedIn API calls.
+     *
+     * @param url - The API endpoint URL
+     * @param token - The access token
      */
     protected getAuthenticatedRequest(url: string, token: string): HttpClient;
     /**
-     * Fetches the user info from the LinkedIn API
+     * Fetches the authenticated user's profile information from the LinkedIn API.
+     *
+     * @param token - The access token
+     * @param callback - Optional callback to customize the API request
      */
     protected getUserInfo(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         id: any;
@@ -56,15 +99,29 @@ export declare class LinkedInDriver extends Oauth2Driver<LinkedInToken, LinkedIn
         original: any;
     }>;
     /**
-     * Fetches the user email from the LinkedIn API
+     * Fetches the user's email address from the LinkedIn API.
+     * Requires the 'r_emailaddress' scope.
+     *
+     * @param token - The access token
+     * @param callback - Optional callback to customize the API request
      */
     protected getUserEmail(token: string, callback?: (request: ApiRequestContract) => void): Promise<any>;
     /**
-     * Find if the current error code is for access denied
+     * Check if the error from the callback indicates that the user
+     * denied authorization or cancelled the login.
      */
     accessDenied(): boolean;
     /**
-     * Returns details for the authorized user
+     * Get the authenticated user's profile and email information using
+     * the authorization code from the callback request.
+     *
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('linkedin').user()
+     * console.log(user.name, user.email)
+     * ```
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<{
         email: any;
@@ -77,7 +134,16 @@ export declare class LinkedInDriver extends Oauth2Driver<LinkedInToken, LinkedIn
         original: any;
     }>;
     /**
-     * Finds the user by the access token
+     * Get the user's profile and email information using an existing
+     * access token.
+     *
+     * @param token - The LinkedIn access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('linkedin').userFromToken(accessToken)
+     * ```
      */
     userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         email: any;

package/build/src/drivers/linked_in.js

@@ -1,12 +1,16 @@
 import {
   Oauth2Driver
-} from "../../chunk-GWAQFMNS.js";
-import "../../chunk-N72DEJC2.js";
-import "../../chunk-PZ5AY32C.js";
+} from "../../chunk-WM3V3APX.js";
+import "../../chunk-KSJ4CFTC.js";
+import "../../chunk-MLKGABMK.js";
 
 // src/drivers/linked_in.ts
-import { Exception } from "@poppinss/utils";
+import { Exception } from "@adonisjs/core/exceptions";
 var LinkedInDriver = class extends Oauth2Driver {
+  /**
+   * @param ctx - The HTTP context
+   * @param config - Configuration for the LinkedIn driver
+   */
   constructor(ctx, config) {
     super(ctx, config);
     this.config = config;
@@ -42,14 +46,20 @@ var LinkedInDriver = class extends Oauth2Driver {
    */
   scopesSeparator = " ";
   /**
-   * Configuring the redirect request with defaults
+   * Configures the redirect request with default scopes.
+   *
+   * @param request - The redirect request to configure
    */
   configureRedirectRequest(request) {
     request.scopes(this.config.scopes || ["r_emailaddress", "r_liteprofile"]);
     request.param("response_type", "code");
   }
   /**
-   * Returns the HTTP request with the authorization header set
+   * Creates an authenticated HTTP request with the proper authorization
+   * header for LinkedIn API calls.
+   *
+   * @param url - The API endpoint URL
+   * @param token - The access token
    */
   getAuthenticatedRequest(url, token) {
     const request = this.httpClient(url);
@@ -59,7 +69,10 @@ var LinkedInDriver = class extends Oauth2Driver {
     return request;
   }
   /**
-   * Fetches the user info from the LinkedIn API
+   * Fetches the authenticated user's profile information from the LinkedIn API.
+   *
+   * @param token - The access token
+   * @param callback - Optional callback to customize the API request
    */
   async getUserInfo(token, callback) {
     let url = this.config.userInfoUrl || this.userInfoUrl;
@@ -88,7 +101,11 @@ var LinkedInDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Fetches the user email from the LinkedIn API
+   * Fetches the user's email address from the LinkedIn API.
+   * Requires the 'r_emailaddress' scope.
+   *
+   * @param token - The access token
+   * @param callback - Optional callback to customize the API request
    */
   async getUserEmail(token, callback) {
     let url = this.config.userEmailUrl || this.userEmailUrl;
@@ -110,7 +127,8 @@ var LinkedInDriver = class extends Oauth2Driver {
     return mainEmail["handle~"]["emailAddress"];
   }
   /**
-   * Find if the current error code is for access denied
+   * Check if the error from the callback indicates that the user
+   * denied authorization or cancelled the login.
    */
   accessDenied() {
     const error = this.getError();
@@ -120,7 +138,16 @@ var LinkedInDriver = class extends Oauth2Driver {
     return error === "user_cancelled_login" || error === "user_cancelled_authorize";
   }
   /**
-   * Returns details for the authorized user
+   * Get the authenticated user's profile and email information using
+   * the authorization code from the callback request.
+   *
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('linkedin').user()
+   * console.log(user.name, user.email)
+   * ```
    */
   async user(callback) {
     const token = await this.accessToken(callback);
@@ -134,7 +161,16 @@ var LinkedInDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Finds the user by the access token
+   * Get the user's profile and email information using an existing
+   * access token.
+   *
+   * @param token - The LinkedIn access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('linkedin').userFromToken(accessToken)
+   * ```
    */
   async userFromToken(token, callback) {
     const user = await this.getUserInfo(token, callback);
@@ -150,4 +186,3 @@ var LinkedInDriver = class extends Oauth2Driver {
 export {
   LinkedInDriver
 };
-//# sourceMappingURL=linked_in.js.map