@adonisjs/ally/build/src/drivers/github.d.ts

Social authentication provider for AdonisJS

import type { HttpContext } from '@adonisjs/core/http';
import type { HttpClient } from '@poppinss/oauth-client';
import type { GithubToken, GithubScopes, AllyUserContract, GithubDriverConfig, ApiRequestContract, RedirectRequestContract } from '../types.ts';
import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
/**
 * 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;
    /**
     * GitHub token endpoint URL.
     */
    protected accessTokenUrl: string;
    /**
     * GitHub authorization endpoint URL.
     */
    protected authorizeUrl: string;
    /**
     * GitHub profile endpoint URL.
     */
    protected userInfoUrl: string;
    /**
     * GitHub email endpoint URL.
     */
    protected userEmailUrl: string;
    /**
     * The param name for the authorization code
     */
    protected codeParamName: string;
    /**
     * The param name for the error
     */
    protected errorParamName: string;
    /**
     * Cookie name for storing the "gh_oauth_state"
     */
    protected stateCookieName: string;
    /**
     * Parameter name to be used for sending and receiving the state
     * from Github
     */
    protected stateParamName: string;
    /**
     * Parameter name for defining the scopes
     */
    protected scopeParamName: string;
    /**
     * Scopes separator
     */
    protected scopesSeparator: string;
    /**
     * @param ctx - The HTTP context
     * @param config - Configuration for the GitHub driver
     */
    constructor(ctx: HttpContext, config: GithubDriverConfig);
    /**
     * 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;
    /**
     * 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;
    /**
     * 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 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;
        nickName: any;
        email: any;
        emailVerificationState: AllyUserContract<any>["emailVerificationState"];
        name: any;
        avatarUrl: any;
        original: any;
    }>;
    /**
     * 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>;
    /**
     * Check if the error from the callback indicates that the user
     * denied authorization.
     */
    accessDenied(): boolean;
    /**
     * 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;
        id: any;
        nickName: any;
        email: any;
        emailVerificationState: AllyUserContract<any>["emailVerificationState"];
        name: any;
        avatarUrl: any;
        original: any;
    }>;
    /**
     * 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: {
            token: string;
            type: "bearer";
        };
        id: any;
        nickName: any;
        email: any;
        emailVerificationState: AllyUserContract<any>["emailVerificationState"];
        name: any;
        avatarUrl: any;
        original: any;
    }>;
}