@adonisjs/ally 5.1.1 → 6.0.0-next.0

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

@@ -1,9 +1,39 @@
-import { Oauth2Driver } from '../abstract_drivers/oauth2.js';
 import type { HttpContext } from '@adonisjs/core/http';
-import type { ApiRequestContract, LinkedInOpenidConnectAccessToken, LinkedInOpenidConnectDriverConfig, LinkedInOpenidConnectScopes, RedirectRequestContract } from '@adonisjs/ally/types';
 import type { HttpClient } from '@poppinss/oauth-client';
+import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
+import type { ApiRequestContract, LinkedInOpenidConnectAccessToken, LinkedInOpenidConnectDriverConfig, LinkedInOpenidConnectScopes, RedirectRequestContract } from '../types.ts';
 /**
- * LinkedIn openid connect driver to login user via LinkedIn using openid connect requirements
+ * LinkedIn OpenID Connect OAuth2 driver for authenticating users via LinkedIn.
+ * This driver uses the OpenID Connect protocol for authentication.
+ * Supports fetching user profile information including name, email, and profile picture.
+ *
+ * @example
+ * ```ts
+ * router.get('/linkedin/redirect', ({ ally }) => {
+ *   return ally.use('linkedinOpenidConnect').redirect((request) => {
+ *     request.scopes(['openid', 'profile', 'email'])
+ *   })
+ * })
+ *
+ * router.get('/linkedin/callback', async ({ ally }) => {
+ *   const linkedin = ally.use('linkedinOpenidConnect')
+ *
+ *   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 LinkedInOpenidConnectDriver extends Oauth2Driver<LinkedInOpenidConnectAccessToken, LinkedInOpenidConnectScopes> {
     config: LinkedInOpenidConnectDriverConfig;
@@ -35,17 +65,31 @@ export declare class LinkedInOpenidConnectDriver extends Oauth2Driver<LinkedInOp
      * Scopes separator
      */
     protected scopesSeparator: string;
+    /**
+     * @param ctx - The HTTP context
+     * @param config - Configuration for the LinkedIn OpenID Connect driver
+     */
     constructor(ctx: HttpContext, config: LinkedInOpenidConnectDriverConfig);
     /**
-     * Configuring the redirect request with defaults
+     * Configures the redirect request with default scopes for OpenID Connect.
+     *
+     * @param request - The redirect request to configure
      */
     protected configureRedirectRequest(request: RedirectRequestContract<LinkedInOpenidConnectScopes>): 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
+     * using the OpenID Connect userinfo endpoint.
+     *
+     * @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,11 +101,21 @@ export declare class LinkedInOpenidConnectDriver extends Oauth2Driver<LinkedInOp
         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 or cancelled the login.
      */
     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('linkedinOpenidConnect').user()
+     * console.log(user.name, user.email)
+     * ```
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<{
         token: {
@@ -79,7 +133,16 @@ export declare class LinkedInOpenidConnectDriver extends Oauth2Driver<LinkedInOp
         original: any;
     }>;
     /**
-     * Finds the user by the access token
+     * Get the user's profile 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('linkedinOpenidConnect').userFromToken(accessToken)
+     * ```
      */
     userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         token: {

package/build/src/drivers/linked_in_openid_connect.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/linked_in_openid_connect.ts
 var LinkedInOpenidConnectDriver = class extends Oauth2Driver {
+  /**
+   * @param ctx - The HTTP context
+   * @param config - Configuration for the LinkedIn OpenID Connect driver
+   */
   constructor(ctx, config) {
     super(ctx, config);
     this.config = config;
@@ -40,14 +44,20 @@ var LinkedInOpenidConnectDriver = class extends Oauth2Driver {
    */
   scopesSeparator = " ";
   /**
-   * Configuring the redirect request with defaults
+   * Configures the redirect request with default scopes for OpenID Connect.
+   *
+   * @param request - The redirect request to configure
    */
   configureRedirectRequest(request) {
     request.scopes(this.config.scopes || ["openid", "profile", "email"]);
     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);
@@ -57,7 +67,11 @@ var LinkedInOpenidConnectDriver = class extends Oauth2Driver {
     return request;
   }
   /**
-   * Fetches the user info from the LinkedIn API
+   * Fetches the authenticated user's profile information from the LinkedIn API
+   * using the OpenID Connect userinfo endpoint.
+   *
+   * @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;
@@ -78,7 +92,8 @@ var LinkedInOpenidConnectDriver = 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 or cancelled the login.
    */
   accessDenied() {
     const error = this.getError();
@@ -88,7 +103,16 @@ var LinkedInOpenidConnectDriver = class extends Oauth2Driver {
     return error === "user_cancelled_login" || error === "user_cancelled_authorize";
   }
   /**
-   * 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('linkedinOpenidConnect').user()
+   * console.log(user.name, user.email)
+   * ```
    */
   async user(callback) {
     const accessToken = await this.accessToken(callback);
@@ -99,7 +123,16 @@ var LinkedInOpenidConnectDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Finds the user by the access token
+   * Get the user's profile 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('linkedinOpenidConnect').userFromToken(accessToken)
+   * ```
    */
   async userFromToken(token, callback) {
     const user = await this.getUserInfo(token, callback);
@@ -112,4 +145,3 @@ var LinkedInOpenidConnectDriver = class extends Oauth2Driver {
 export {
   LinkedInOpenidConnectDriver
 };
-//# sourceMappingURL=linked_in_openid_connect.js.map

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

@@ -1,9 +1,38 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { HttpClient } from '@poppinss/oauth-client';
-import type { SpotifyScopes, SpotifyToken, ApiRequestContract, SpotifyDriverConfig, RedirectRequestContract } from '../types.js';
-import { Oauth2Driver } from '../abstract_drivers/oauth2.js';
+import type { SpotifyScopes, SpotifyToken, ApiRequestContract, SpotifyDriverConfig, RedirectRequestContract } from '../types.ts';
+import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
 /**
- * Spotify driver to login user via Spotify
+ * Spotify OAuth2 driver for authenticating users via Spotify.
+ * Supports fetching user profile information including display name, email, and profile images.
+ *
+ * @example
+ * ```ts
+ * router.get('/spotify/redirect', ({ ally }) => {
+ *   return ally.use('spotify').redirect((request) => {
+ *     request.scopes(['user-read-email', 'user-read-private'])
+ *   })
+ * })
+ *
+ * router.get('/spotify/callback', async ({ ally }) => {
+ *   const spotify = ally.use('spotify')
+ *
+ *   if (spotify.accessDenied()) {
+ *     return 'Access was denied'
+ *   }
+ *
+ *   if (spotify.stateMisMatch()) {
+ *     return 'State mismatch error'
+ *   }
+ *
+ *   if (spotify.hasError()) {
+ *     return spotify.getError()
+ *   }
+ *
+ *   const user = await spotify.user()
+ *   return user
+ * })
+ * ```
  */
 export declare class SpotifyDriver extends Oauth2Driver<SpotifyToken, SpotifyScopes> {
     config: SpotifyDriverConfig;
@@ -35,18 +64,33 @@ export declare class SpotifyDriver extends Oauth2Driver<SpotifyToken, SpotifySco
      * Scopes separator
      */
     protected scopesSeparator: string;
+    /**
+     * @param ctx - The HTTP context
+     * @param config - Configuration for the Spotify driver
+     */
     constructor(ctx: HttpContext, config: SpotifyDriverConfig);
     /**
-     * Configuring the redirect request with defaults
+     * Configures the redirect request with default scopes and Spotify-specific
+     * parameters like show_dialog.
+     *
+     * @param request - The redirect request to configure
      */
     protected configureRedirectRequest(request: RedirectRequestContract<SpotifyScopes>): void;
     /**
-     * Returns the HTTP request with the authorization header set
+     * Creates an authenticated HTTP request with the proper authorization
+     * header for Spotify 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 Spotify API
-     * https://discord.com/developers/docs/resources/user#get-current-user
+     * Fetches the authenticated user's profile information from the Spotify API.
+     *
+     * @param token - The access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @see https://developer.spotify.com/documentation/web-api/reference/get-current-users-profile
      */
     protected getUserInfo(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         id: any;
@@ -58,11 +102,21 @@ export declare class SpotifyDriver extends Oauth2Driver<SpotifyToken, SpotifySco
         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('spotify').user()
+     * console.log(user.name, user.email)
+     * ```
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<{
         token: SpotifyToken;
@@ -75,7 +129,16 @@ export declare class SpotifyDriver extends Oauth2Driver<SpotifyToken, SpotifySco
         original: any;
     }>;
     /**
-     * Finds the user by the access token
+     * Get the user's profile information using an existing
+     * access token.
+     *
+     * @param token - The Spotify access token
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('spotify').userFromToken(accessToken)
+     * ```
      */
     userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
         token: {

package/build/src/drivers/spotify.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/spotify.ts
 var SpotifyDriver = class extends Oauth2Driver {
+  /**
+   * @param ctx - The HTTP context
+   * @param config - Configuration for the Spotify driver
+   */
   constructor(ctx, config) {
     super(ctx, config);
     this.config = config;
@@ -40,7 +44,10 @@ var SpotifyDriver = class extends Oauth2Driver {
    */
   scopesSeparator = " ";
   /**
-   * Configuring the redirect request with defaults
+   * Configures the redirect request with default scopes and Spotify-specific
+   * parameters like show_dialog.
+   *
+   * @param request - The redirect request to configure
    */
   configureRedirectRequest(request) {
     request.scopes(this.config.scopes || ["user-read-email"]);
@@ -51,7 +58,11 @@ var SpotifyDriver = class extends Oauth2Driver {
     }
   }
   /**
-   * Returns the HTTP request with the authorization header set
+   * Creates an authenticated HTTP request with the proper authorization
+   * header for Spotify API calls.
+   *
+   * @param url - The API endpoint URL
+   * @param token - The access token
    */
   getAuthenticatedRequest(url, token) {
     const request = this.httpClient(url);
@@ -61,8 +72,12 @@ var SpotifyDriver = class extends Oauth2Driver {
     return request;
   }
   /**
-   * Fetches the user info from the Spotify API
-   * https://discord.com/developers/docs/resources/user#get-current-user
+   * Fetches the authenticated user's profile information from the Spotify API.
+   *
+   * @param token - The access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @see https://developer.spotify.com/documentation/web-api/reference/get-current-users-profile
    */
   async getUserInfo(token, callback) {
     const request = this.getAuthenticatedRequest(this.userInfoUrl, token);
@@ -81,7 +96,8 @@ var SpotifyDriver = 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();
@@ -91,7 +107,16 @@ var SpotifyDriver = 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('spotify').user()
+   * console.log(user.name, user.email)
+   * ```
    */
   async user(callback) {
     const token = await this.accessToken(callback);
@@ -102,7 +127,16 @@ var SpotifyDriver = class extends Oauth2Driver {
     };
   }
   /**
-   * Finds the user by the access token
+   * Get the user's profile information using an existing
+   * access token.
+   *
+   * @param token - The Spotify access token
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('spotify').userFromToken(accessToken)
+   * ```
    */
   async userFromToken(token, callback) {
     const user = await this.getUserInfo(token, callback);
@@ -115,4 +149,3 @@ var SpotifyDriver = class extends Oauth2Driver {
 export {
   SpotifyDriver
 };
-//# sourceMappingURL=spotify.js.map

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

@@ -1,8 +1,36 @@
 import type { HttpContext } from '@adonisjs/core/http';
-import { TwitterToken, AllyUserContract, ApiRequestContract, TwitterDriverConfig } from '../types.js';
-import { Oauth1Driver } from '../abstract_drivers/oauth1.js';
+import { type TwitterToken, type AllyUserContract, type ApiRequestContract, type TwitterDriverConfig } from '../types.ts';
+import { Oauth1Driver } from '../abstract_drivers/oauth1.ts';
 /**
- * Twitter driver to login user via twitter
+ * Twitter OAuth1 driver for authenticating users via Twitter.
+ * Supports fetching user profile information including username, name, and email.
+ * Uses OAuth 1.0a protocol.
+ *
+ * @example
+ * ```ts
+ * router.get('/twitter/redirect', ({ ally }) => {
+ *   return ally.use('twitter').redirect()
+ * })
+ *
+ * router.get('/twitter/callback', async ({ ally }) => {
+ *   const twitter = ally.use('twitter')
+ *
+ *   if (twitter.accessDenied()) {
+ *     return 'Access was denied'
+ *   }
+ *
+ *   if (twitter.stateMisMatch()) {
+ *     return 'State mismatch error'
+ *   }
+ *
+ *   if (twitter.hasError()) {
+ *     return twitter.getError()
+ *   }
+ *
+ *   const user = await twitter.user()
+ *   return user
+ * })
+ * ```
  */
 export declare class TwitterDriver extends Oauth1Driver<TwitterToken, string> {
     protected ctx: HttpContext;
@@ -38,9 +66,19 @@ export declare class TwitterDriver extends Oauth1Driver<TwitterToken, string> {
      */
     protected scopeParamName: string;
     protected scopesSeparator: string;
+    /**
+     * @param ctx - The HTTP context
+     * @param config - Configuration for the Twitter driver
+     */
     constructor(ctx: HttpContext, config: TwitterDriverConfig);
     /**
-     * Returns user info
+     * Fetches the authenticated user's profile information from the Twitter API.
+     *
+     * @param token - The OAuth token
+     * @param secret - The OAuth token secret
+     * @param callback - Optional callback to customize the API request
+     *
+     * @see https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials
      */
     protected getUserInfo(token: string, secret: string, callback?: (request: ApiRequestContract) => void): Promise<{
         id: any;
@@ -52,7 +90,16 @@ export declare class TwitterDriver extends Oauth1Driver<TwitterToken, string> {
         original: any;
     }>;
     /**
-     * Returns details for the authorized user
+     * Get the authenticated user's profile information using
+     * the OAuth verifier from the callback request.
+     *
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('twitter').user()
+     * console.log(user.name, user.email)
+     * ```
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<{
         token: TwitterToken;
@@ -65,15 +112,25 @@ export declare class TwitterDriver extends Oauth1Driver<TwitterToken, string> {
         original: any;
     }>;
     /**
-     * Finds the user info from the "oauth_token" and "oauth_token_secret"
-     * access from the access token.
+     * Get the user's profile information using an existing OAuth token
+     * and token secret.
+     *
+     * @param token - The OAuth token
+     * @param secret - The OAuth token secret
+     * @param callback - Optional callback to customize the API request
+     *
+     * @example
+     * ```ts
+     * const user = await ally.use('twitter').userFromTokenAndSecret(token, secret)
+     * ```
      */
     userFromTokenAndSecret(token: string, secret: string, callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<{
         token: string;
         secret: string;
     }>>;
     /**
-     * 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;
 }

package/build/src/drivers/twitter.js

@@ -1,11 +1,15 @@
 import {
   Oauth1Driver
-} from "../../chunk-VHORNQLN.js";
-import "../../chunk-N72DEJC2.js";
-import "../../chunk-PZ5AY32C.js";
+} from "../../chunk-KWRXS6EG.js";
+import "../../chunk-KSJ4CFTC.js";
+import "../../chunk-MLKGABMK.js";
 
 // src/drivers/twitter.ts
 var TwitterDriver = class extends Oauth1Driver {
+  /**
+   * @param ctx - The HTTP context
+   * @param config - Configuration for the Twitter driver
+   */
   constructor(ctx, config) {
     super(ctx, config);
     this.ctx = ctx;
@@ -44,7 +48,13 @@ var TwitterDriver = class extends Oauth1Driver {
   scopeParamName = "";
   scopesSeparator = " ";
   /**
-   * Returns user info
+   * Fetches the authenticated user's profile information from the Twitter API.
+   *
+   * @param token - The OAuth token
+   * @param secret - The OAuth token secret
+   * @param callback - Optional callback to customize the API request
+   *
+   * @see https://developer.twitter.com/en/docs/twitter-api/v1/accounts-and-users/manage-account-settings/api-reference/get-account-verify_credentials
    */
   async getUserInfo(token, secret, callback) {
     const requestToken = { token, secret };
@@ -67,7 +77,16 @@ var TwitterDriver = class extends Oauth1Driver {
     };
   }
   /**
-   * Returns details for the authorized user
+   * Get the authenticated user's profile information using
+   * the OAuth verifier from the callback request.
+   *
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('twitter').user()
+   * console.log(user.name, user.email)
+   * ```
    */
   async user(callback) {
     const token = await this.accessToken();
@@ -78,8 +97,17 @@ var TwitterDriver = class extends Oauth1Driver {
     };
   }
   /**
-   * Finds the user info from the "oauth_token" and "oauth_token_secret"
-   * access from the access token.
+   * Get the user's profile information using an existing OAuth token
+   * and token secret.
+   *
+   * @param token - The OAuth token
+   * @param secret - The OAuth token secret
+   * @param callback - Optional callback to customize the API request
+   *
+   * @example
+   * ```ts
+   * const user = await ally.use('twitter').userFromTokenAndSecret(token, secret)
+   * ```
    */
   async userFromTokenAndSecret(token, secret, callback) {
     const userInfo = await this.getUserInfo(token, secret, callback);
@@ -89,7 +117,8 @@ var TwitterDriver = class extends Oauth1Driver {
     };
   }
   /**
-   * Find if the current error code is for access denied
+   * Check if the error from the callback indicates that the user
+   * denied authorization.
    */
   accessDenied() {
     return this.ctx.request.input("denied");
@@ -98,4 +127,3 @@ var TwitterDriver = class extends Oauth1Driver {
 export {
   TwitterDriver
 };
-//# sourceMappingURL=twitter.js.map

package/build/src/errors.d.ts

@@ -1,2 +1,10 @@
-export declare const E_OAUTH_MISSING_CODE: new (args: [string], options?: ErrorOptions) => import("@poppinss/utils").Exception;
-export declare const E_OAUTH_STATE_MISMATCH: new (args?: any, options?: ErrorOptions) => import("@poppinss/utils").Exception;
+/**
+ * Error thrown when the OAuth redirect is missing the required
+ * authorization code or token parameter.
+ */
+export declare const E_OAUTH_MISSING_CODE: new (args: [string], options?: ErrorOptions) => import("@adonisjs/core/exceptions").Exception;
+/**
+ * Error thrown when the OAuth state parameter does not match
+ * the expected value, indicating a potential CSRF attack.
+ */
+export declare const E_OAUTH_STATE_MISMATCH: new (args?: any, options?: ErrorOptions) => import("@adonisjs/core/exceptions").Exception;