bc-api-client/dist/auth.d.ts

A client for the BigCommerce management API and app authentication

import { Logger } from './core';
/**
 * Configuration options for BigCommerce authentication
 */
type Config = {
    /** The OAuth client ID from BigCommerce */
    clientId: string;
    /** The OAuth client secret from BigCommerce */
    secret: string;
    /** The redirect URI registered with BigCommerce */
    redirectUri: string;
    /** Optional array of scopes to validate during auth callback */
    scopes?: string[];
    /** Optional logger instance */
    logger?: Logger;
};
/**
 * Query parameters received from BigCommerce auth callback
 */
type AuthQuery = {
    /** The authorization code from BigCommerce */
    code: string;
    /** The granted OAuth scopes */
    scope: string;
    /** The store context */
    context: string;
};
/**
 * User information returned from BigCommerce
 */
export type User = {
    /** The user's ID */
    id: number;
    /** The user's username */
    username: string;
    /** The user's email address */
    email: string;
};
/**
 * Response from BigCommerce token endpoint
 */
export type TokenResponse = {
    /** The OAuth access token */
    access_token: string;
    /** The granted OAuth scopes */
    scope: string;
    /** Information about the authenticated user */
    user: User;
    /** Information about the store owner */
    owner: User;
    /** The store context */
    context: string;
    /** The BigCommerce account UUID */
    account_uuid: string;
};
/**
 * JWT claims from BigCommerce
 */
export type Claims = {
    /** JWT audience */
    aud: string;
    /** JWT issuer */
    iss: string;
    /** JWT issued at timestamp */
    iat: number;
    /** JWT not before timestamp */
    nbf: number;
    /** JWT expiration timestamp */
    exp: number;
    /** JWT unique identifier */
    jti: string;
    /** JWT subject */
    sub: string;
    /** Information about the authenticated user */
    user: {
        id: number;
        email: string;
        locale: string;
    };
    /** Information about the store owner */
    owner: {
        id: number;
        email: string;
    };
    /** The store URL */
    url: string;
    /** The channel ID (if applicable) */
    channel_id: number | null;
};
/**
 * Handles authentication with BigCommerce OAuth
 */
export declare class BigCommerceAuth {
    private readonly config;
    /**
     * Creates a new BigCommerceAuth instance for handling OAuth authentication
     * @param config - Configuration options for BigCommerce authentication
     * @param config.clientId - The OAuth client ID from BigCommerce
     * @param config.secret - The OAuth client secret from BigCommerce
     * @param config.redirectUri - The redirect URI registered with BigCommerce
     * @param config.scopes - Optional array of scopes to validate during auth callback
     * @param config.logger - Optional logger instance for debugging and error tracking
     * @throws {Error} If the redirect URI is invalid
     */
    constructor(config: Config);
    /**
     * Requests an access token from BigCommerce
     * @param data - Either a query string, URLSearchParams, or AuthQuery object containing auth callback data
     * @returns Promise resolving to the token response
     */
    requestToken(data: string | AuthQuery | URLSearchParams): Promise<TokenResponse>;
    /**
     * Verifies a JWT payload from BigCommerce
     * @param jwtPayload - The JWT string to verify
     * @param storeHash - The store hash for the BigCommerce store
     * @returns Promise resolving to the verified JWT claims
     * @throws {Error} If the JWT is invalid
     */
    verify(jwtPayload: string, storeHash: string): Promise<Claims>;
    /**
     * Parses and validates a query string from BigCommerce auth callback
     * @param queryString - The query string to parse
     * @returns The parsed auth query parameters
     * @throws {Error} If required parameters are missing or scopes are invalid
     */
    private parseQueryString;
    /**
     * Validates that the granted scopes match the expected scopes
     * @param scopes - Space-separated list of granted scopes
     * @throws {Error} If the scopes don't match the expected scopes
     */
    private validateScopes;
}
export {};