@adonisjs/ally 5.1.0 → 6.0.0-next.0

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

@@ -1,9 +1,38 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { HttpClient } from '@poppinss/oauth-client';
-import type { DiscordScopes, DiscordToken, ApiRequestContract, DiscordDriverConfig, RedirectRequestContract } from '../types.js';
-import { Oauth2Driver } from '../abstract_drivers/oauth2.js';
+import type { DiscordScopes, DiscordToken, ApiRequestContract, DiscordDriverConfig, RedirectRequestContract } from '../types.ts';
+import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
 /**
- * Discord driver to login user via Discord
+ * Discord OAuth2 driver for authenticating users via Discord.
+ * Supports fetching user profile information including username and email.
+ *
+ * @example
+ * ```ts
+ * router.get('/discord/redirect', ({ ally }) => {
+ *   return ally.use('discord').redirect((request) => {
+ *     request.scopes(['identify', 'email', 'guilds'])
+ *   })
+ * })
+ *
+ * router.get('/discord/callback', async ({ ally }) => {
+ *   const discord = ally.use('discord')
+ *
+ *   if (discord.accessDenied()) {
+ *     return 'Access was denied'
+ *   }
+ *
+ *   if (discord.stateMisMatch()) {
+ *     return 'State mismatch error'
+ *   }
+ *
+ *   if (discord.hasError()) {
+ *     return discord.getError()
+ *   }
+ *
+ *   const user = await discord.user()
+ *   return user
+ * })
+ * ```
  */
 export declare class DiscordDriver extends Oauth2Driver<DiscordToken, DiscordScopes> {
     config: DiscordDriverConfig;
@@ -35,22 +64,39 @@ export declare class DiscordDriver extends Oauth2Driver<DiscordToken, DiscordSco
      * Scopes separator
      */
     protected scopesSeparator: string;
+    /**
+     * @param ctx - The HTTP context
+     * @param config - Configuration for the Discord driver
+     */
     constructor(ctx: HttpContext, config: DiscordDriverConfig);
     /**
-     * Configuring the redirect request with defaults
+     * Configures the redirect request with default scopes and Discord-specific
+     * parameters like prompt, guild_id, and permissions.
+     *
+     * @param request - The redirect request to configure
      */
     protected configureRedirectRequest(request: RedirectRequestContract<DiscordScopes>): void;
     /**
-     * Configuring the access token API request to send extra fields
+     * Configures the access token request with Discord-specific requirements.
+     *
+     * @param request - The API request to configure
      */
     protected configureAccessTokenRequest(request: ApiRequestContract): void;
     /**
-     * Returns the HTTP request with the authorization header set
+     * Creates an authenticated HTTP request with the proper authorization
+     * header for Discord 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 Discord API
-     * https://discord.com/developers/docs/resources/user#get-current-user
+     * Fetches the authenticated user's profile information from the Discord API.
+     *
+     * @param token - The access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @see https://discord.com/developers/docs/resources/user#get-current-user
      */
     protected getUserInfo(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         id: any;
@@ -62,11 +108,21 @@ export declare class DiscordDriver extends Oauth2Driver<DiscordToken, DiscordSco
         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;
     /**
-     * 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('discord').user()
+     * console.log(user.name, user.email)
+     * ```
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<{
         token: DiscordToken;
@@ -79,7 +135,16 @@ export declare class DiscordDriver extends Oauth2Driver<DiscordToken, DiscordSco
         original: any;
     }>;
     /**
-     * Finds the user by the access token
+     * Get the user's profile information using an existing
+     * access token.
+     *
+     * @param token - The Discord access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('discord').userFromToken(accessToken)
+     * ```
      */
     userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         token: {

package/build/src/drivers/discord.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/discord.ts
 var DiscordDriver = class extends Oauth2Driver {
+  /**
+   * @param ctx - The HTTP context
+   * @param config - Configuration for the Discord driver
+   */
   constructor(ctx, config) {
     super(ctx, config);
     this.config = config;
@@ -40,7 +44,10 @@ var DiscordDriver = class extends Oauth2Driver {
    */
   scopesSeparator = " ";
   /**
-   * Configuring the redirect request with defaults
+   * Configures the redirect request with default scopes and Discord-specific
+   * parameters like prompt, guild_id, and permissions.
+   *
+   * @param request - The redirect request to configure
    */
   configureRedirectRequest(request) {
     request.scopes(this.config.scopes || ["identify", "email"]);
@@ -61,7 +68,9 @@ var DiscordDriver = class extends Oauth2Driver {
     }
   }
   /**
-   * Configuring the access token API request to send extra fields
+   * Configures the access token request with Discord-specific requirements.
+   *
+   * @param request - The API request to configure
    */
   configureAccessTokenRequest(request) {
     if (!this.isStateless) {
@@ -69,7 +78,11 @@ var DiscordDriver = class extends Oauth2Driver {
     }
   }
   /**
-   * Returns the HTTP request with the authorization header set
+   * Creates an authenticated HTTP request with the proper authorization
+   * header for Discord API calls.
+   *
+   * @param url - The API endpoint URL
+   * @param token - The access token
    */
   getAuthenticatedRequest(url, token) {
     const request = this.httpClient(url);
@@ -79,8 +92,12 @@ var DiscordDriver = class extends Oauth2Driver {
     return request;
   }
   /**
-   * Fetches the user info from the Discord API
-   * https://discord.com/developers/docs/resources/user#get-current-user
+   * Fetches the authenticated user's profile information from the Discord API.
+   *
+   * @param token - The access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @see https://discord.com/developers/docs/resources/user#get-current-user
    */
   async getUserInfo(token, callback) {
     const request = this.getAuthenticatedRequest(this.config.userInfoUrl || this.userInfoUrl, token);
@@ -100,7 +117,8 @@ var DiscordDriver = 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();
@@ -110,7 +128,16 @@ var DiscordDriver = class extends Oauth2Driver {
     return error === "access_denied";
   }
   /**
-   * 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('discord').user()
+   * console.log(user.name, user.email)
+   * ```
    */
   async user(callback) {
     const token = await this.accessToken(callback);
@@ -121,7 +148,16 @@ var DiscordDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Finds the user by the access token
+   * Get the user's profile information using an existing
+   * access token.
+   *
+   * @param token - The Discord access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('discord').userFromToken(accessToken)
+   * ```
    */
   async userFromToken(token, callback) {
     const user = await this.getUserInfo(token, callback);
@@ -134,4 +170,3 @@ var DiscordDriver = class extends Oauth2Driver {
 export {
   DiscordDriver
 };
-//# sourceMappingURL=discord.js.map

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

@@ -1,9 +1,38 @@
 import type { HttpClient } from '@poppinss/oauth-client';
 import type { HttpContext } from '@adonisjs/core/http';
-import type { FacebookToken, FacebookScopes, LiteralStringUnion, ApiRequestContract, FacebookDriverConfig, FacebookProfileFields, RedirectRequestContract } from '../types.js';
-import { Oauth2Driver } from '../abstract_drivers/oauth2.js';
+import type { FacebookToken, FacebookScopes, LiteralStringUnion, ApiRequestContract, FacebookDriverConfig, FacebookProfileFields, RedirectRequestContract } from '../types.ts';
+import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
 /**
- * Facebook driver to login user via Facebook
+ * Facebook OAuth2 driver for authenticating users via Facebook.
+ * Supports fetching user profile information including name, email, and profile picture.
+ *
+ * @example
+ * ```ts
+ * router.get('/facebook/redirect', ({ ally }) => {
+ *   return ally.use('facebook').redirect((request) => {
+ *     request.scopes(['email', 'public_profile'])
+ *   })
+ * })
+ *
+ * router.get('/facebook/callback', async ({ ally }) => {
+ *   const facebook = ally.use('facebook')
+ *
+ *   if (facebook.accessDenied()) {
+ *     return 'Access was denied'
+ *   }
+ *
+ *   if (facebook.stateMisMatch()) {
+ *     return 'State mismatch error'
+ *   }
+ *
+ *   if (facebook.hasError()) {
+ *     return facebook.getError()
+ *   }
+ *
+ *   const user = await facebook.user()
+ *   return user
+ * })
+ * ```
  */
 export declare class FacebookDriver extends Oauth2Driver<FacebookToken, FacebookScopes> {
     config: FacebookDriverConfig;
@@ -39,18 +68,33 @@ export declare class FacebookDriver extends Oauth2Driver<FacebookToken, Facebook
      * Scopes separator
      */
     protected scopesSeparator: string;
+    /**
+     * @param ctx - The HTTP context
+     * @param config - Configuration for the Facebook driver
+     */
     constructor(ctx: HttpContext, config: FacebookDriverConfig);
     /**
-     * Configuring the redirect request with defaults
+     * Configures the redirect request with default scopes and Facebook-specific
+     * parameters like display and auth_type.
+     *
+     * @param request - The redirect request to configure
      */
     protected configureRedirectRequest(request: RedirectRequestContract<FacebookScopes>): void;
     /**
-     * Returns the HTTP request with the authorization header set
+     * Creates an authenticated HTTP request with the proper authorization
+     * header for Facebook 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 Facebook API
-     * https://developers.facebook.com/docs/graph-api/reference/user/
+     * Fetches the authenticated user's profile information from the Facebook API.
+     *
+     * @param token - The access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @see https://developers.facebook.com/docs/graph-api/reference/user/
      */
     protected getUserInfo(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         id: any;
@@ -62,11 +106,21 @@ export declare class FacebookDriver extends Oauth2Driver<FacebookToken, Facebook
         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;
     /**
-     * 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('facebook').user()
+     * console.log(user.name, user.email)
+     * ```
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<{
         token: FacebookToken;
@@ -79,7 +133,16 @@ export declare class FacebookDriver extends Oauth2Driver<FacebookToken, Facebook
         original: any;
     }>;
     /**
-     * Finds the user by the access token
+     * Get the user's profile information using an existing
+     * access token.
+     *
+     * @param token - The Facebook access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('facebook').userFromToken(accessToken)
+     * ```
      */
     userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         token: {

package/build/src/drivers/facebook.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/facebook.ts
 var FacebookDriver = class extends Oauth2Driver {
+  /**
+   * @param ctx - The HTTP context
+   * @param config - Configuration for the Facebook driver
+   */
   constructor(ctx, config) {
     super(ctx, config);
     this.config = config;
@@ -52,7 +56,10 @@ var FacebookDriver = class extends Oauth2Driver {
    */
   scopesSeparator = " ";
   /**
-   * Configuring the redirect request with defaults
+   * Configures the redirect request with default scopes and Facebook-specific
+   * parameters like display and auth_type.
+   *
+   * @param request - The redirect request to configure
    */
   configureRedirectRequest(request) {
     request.scopes(this.config.scopes || ["email"]);
@@ -66,7 +73,11 @@ var FacebookDriver = class extends Oauth2Driver {
     }
   }
   /**
-   * Returns the HTTP request with the authorization header set
+   * Creates an authenticated HTTP request with the proper authorization
+   * header for Facebook API calls.
+   *
+   * @param url - The API endpoint URL
+   * @param token - The access token
    */
   getAuthenticatedRequest(url, token) {
     const request = this.httpClient(url);
@@ -76,8 +87,12 @@ var FacebookDriver = class extends Oauth2Driver {
     return request;
   }
   /**
-   * Fetches the user info from the Facebook API
-   * https://developers.facebook.com/docs/graph-api/reference/user/
+   * Fetches the authenticated user's profile information from the Facebook API.
+   *
+   * @param token - The access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @see https://developers.facebook.com/docs/graph-api/reference/user/
    */
   async getUserInfo(token, callback) {
     const request = this.getAuthenticatedRequest(this.config.userInfoUrl || this.userInfoUrl, token);
@@ -100,7 +115,8 @@ var FacebookDriver = 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();
@@ -110,7 +126,16 @@ var FacebookDriver = class extends Oauth2Driver {
     return error === "access_denied";
   }
   /**
-   * 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('facebook').user()
+   * console.log(user.name, user.email)
+   * ```
    */
   async user(callback) {
     const token = await this.accessToken(callback);
@@ -121,7 +146,16 @@ var FacebookDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Finds the user by the access token
+   * Get the user's profile information using an existing
+   * access token.
+   *
+   * @param token - The Facebook access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('facebook').userFromToken(accessToken)
+   * ```
    */
   async userFromToken(token, callback) {
     const user = await this.getUserInfo(token, callback);
@@ -134,4 +168,3 @@ var FacebookDriver = class extends Oauth2Driver {
 export {
   FacebookDriver
 };
-//# sourceMappingURL=facebook.js.map

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

@@ -1,9 +1,38 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { HttpClient } from '@poppinss/oauth-client';
-import type { GithubToken, GithubScopes, AllyUserContract, GithubDriverConfig, ApiRequestContract, RedirectRequestContract } from '../types.js';
-import { Oauth2Driver } from '../abstract_drivers/oauth2.js';
+import type { GithubToken, GithubScopes, AllyUserContract, GithubDriverConfig, ApiRequestContract, RedirectRequestContract } from '../types.ts';
+import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
 /**
- * Github driver to login user via Github
+ * GitHub OAuth2 driver for authenticating users via GitHub.
+ * Supports fetching user profile information and email addresses.
+ *
+ * @example
+ * ```ts
+ * router.get('/github/redirect', ({ ally }) => {
+ *   return ally.use('github').redirect((request) => {
+ *     request.scopes(['user:email', 'read:org'])
+ *   })
+ * })
+ *
+ * router.get('/github/callback', async ({ ally }) => {
+ *   const github = ally.use('github')
+ *
+ *   if (github.accessDenied()) {
+ *     return 'Access was denied'
+ *   }
+ *
+ *   if (github.stateMisMatch()) {
+ *     return 'State mismatch error'
+ *   }
+ *
+ *   if (github.hasError()) {
+ *     return github.getError()
+ *   }
+ *
+ *   const user = await github.user()
+ *   return user
+ * })
+ * ```
  */
 export declare class GithubDriver extends Oauth2Driver<GithubToken, GithubScopes> {
     config: GithubDriverConfig;
@@ -36,22 +65,40 @@ export declare class GithubDriver extends Oauth2Driver<GithubToken, GithubScopes
      * Scopes separator
      */
     protected scopesSeparator: string;
+    /**
+     * @param ctx - The HTTP context
+     * @param config - Configuration for the GitHub driver
+     */
     constructor(ctx: HttpContext, config: GithubDriverConfig);
     /**
-     * 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
      */
     protected configureRedirectRequest(request: RedirectRequestContract<GithubScopes>): void;
     /**
-     * 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
      */
     protected configureAccessTokenRequest(request: ApiRequestContract): void;
     /**
-     * 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
      */
     protected getAuthenticatedRequest(url: string, token: string): HttpClient;
     /**
-     * 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
      */
     protected getUserInfo(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         id: any;
@@ -63,16 +110,32 @@ export declare class GithubDriver extends Oauth2Driver<GithubToken, GithubScopes
         original: any;
     }>;
     /**
-     * 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
      */
     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.
      */
     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('github').user()
+     * console.log(user.name, user.email)
+     * ```
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<{
         token: GithubToken;
@@ -85,7 +148,16 @@ export declare class GithubDriver extends Oauth2Driver<GithubToken, GithubScopes
         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 GitHub access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('github').userFromToken(accessToken)
+     * ```
      */
     userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         token: {