@google-cloud/recaptcha-edge/dist/index.d.ts

A reCAPTCHA Enterprise Typescript library for Edge Compute Platforms.

/**
 * Copyright 2024 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/**
 * @fileoverview reCAPTCHA Enterprise TypeScript Library.
 */
export { InitError, NetworkError, ParseError, RecaptchaError } from "./error";
export { AllowAction, BlockAction, InjectJsAction, RedirectAction, SetHeaderAction, SubstituteAction, Action, } from "./action";
export { Assessment, Event, FirewallPolicy, UserInfo } from "./assessment";
import { Assessment, Event, FirewallPolicy } from "./assessment";
import { EdgeRequest, EdgeRequestInit, EdgeResponse, EdgeResponseInit } from "./request";
import * as testing_ from "./testing";
export declare const testing: typeof testing_;
export { callCreateAssessment, addTokenAndSiteKeyToEvent } from "./createAssessment";
export { FetchApiRequest, FetchApiResponse } from "./fetchApi";
export { EdgeRequest, EdgeRequestInit, EdgeResponse, EdgeResponseInit } from "./request";
export { applyActions, applyPreRequestActions, applyPostResponseActions, fetchActions, evaluatePolicyAssessment, localPolicyAssessment, policyConditionMatch, policyPathMatch, pathMatch, processRequest, callListFirewallPolicies, } from "./policy";
/** @type {string} */
export declare const CHALLENGE_PAGE_URL = "https://www.google.com/recaptcha/challengepage";
/** Type definition for ListFirewallPoliciesResponse */
export interface ListFirewallPoliciesResponse {
    firewallPolicies: FirewallPolicy[];
}
/**
 * reCAPTCHA Enterprise configuration.
 */
export interface RecaptchaConfig {
    projectNumber: number;
    apiKey: string;
    actionSiteKey?: string;
    expressSiteKey?: string;
    sessionSiteKey?: string;
    challengePageSiteKey?: string;
    enterpriseSiteKey?: string;
    sessionJsInjectPath?: string;
    recaptchaEndpoint?: string;
    debug?: boolean;
    unsafe_debug_dump_logs?: boolean;
    strict_cookie?: boolean;
    credentialPath?: string;
    accountId?: string;
    username?: string;
    challengePageUrl?: string;
}
export declare class DebugTrace {
    exception_count?: number;
    list_firewall_policies_status?: "ok" | "err";
    create_assessment_status?: "ok" | "err";
    _list_firewall_policies_headers?: Map<string, string>;
    _create_assessment_headers?: Map<string, string>;
    policy_count?: number;
    policy_match?: boolean;
    inject_js_match?: boolean;
    site_key_used?: "action" | "session" | "challenge" | "express" | "none" | "enterprise";
    site_keys_present?: string;
    version?: string;
    empty_config?: string;
    performance_counters: Array<[string, number]>;
    constructor(context: RecaptchaContext);
    /**
     * Creates a Header value from an object, used for debug data.
     * @param data an Object with string,number,boolean values.
     * @returns a string in the format k1=v1;k2=v2
     */
    formatAsHeaderValue(): string;
}
export type LogLevel = "debug" | "info" | "warning" | "error";
/**
 * reCAPTCHA Enterprise context.
 * This context provides an abstraction layer per-WAF, and a subclass
 * should be created for each platform.
 */
export declare abstract class RecaptchaContext {
    config: RecaptchaConfig;
    exceptions: any[];
    log_messages: Array<[LogLevel, string[]]>;
    debug_trace: DebugTrace;
    readonly environment: [string, string];
    abstract readonly sessionPageCookie: string;
    abstract readonly challengePageCookie: string;
    constructor(config: RecaptchaConfig);
    abstract createResponse(body: string, options?: EdgeResponseInit): EdgeResponse;
    encodeString(st: string): Uint8Array;
    abstract fetch(req: EdgeRequest): Promise<EdgeResponse>;
    /**
     * Fetch from the customer's origin.
     * Parameters and outputs are the same as the 'fetch' function.
     */
    fetch_origin(req: EdgeRequest): Promise<EdgeResponse>;
    /**
     * Call fetch for ListFirewallPolicies.
     * Parameters and outputs are the same as the 'fetch' function.
     */
    abstract fetch_list_firewall_policies(options: EdgeRequestInit): Promise<ListFirewallPoliciesResponse>;
    /**
     * Call fetch for CreateAssessment
     * Parameters and outputs are the same as the 'fetch' function.
     */
    abstract fetch_create_assessment(options: EdgeRequestInit): Promise<Assessment>;
    /**
     * Call fetch for getting the ChallengePage
     */
    abstract fetch_challenge_page(options: EdgeRequestInit): Promise<EdgeResponse>;
    /**
     * Log performance debug information.
     *
     * This should be implemnented on a per-WAF basis. The default implementation
     * does nothing. This method should conditionally log performance only if the
     * config.debug flag is set to true.
     */
    log_performance_debug(event: string): void;
    /**
     * Log an exception.
     *
     * The default behavior is to store the exception in a list.
     * While debugging, this list can be checked after processing the request.
     * WAF-specific implementations may override this behavior to provide more
     * useful logging.
     */
    logException(e: any): void;
    /**
     * Log a message.
     *
     * The default behavior is to store the message in a list.
     * While debugging, this list can be checked after processing the request.
     * WAF-specific implementations may override this behavior to provide more
     * useful logging.
     */
    log(level: LogLevel, msg: string): void;
    toAssessment(response: EdgeResponse): Promise<Assessment>;
    toListFirewallPoliciesResponse(response: EdgeResponse): Promise<ListFirewallPoliciesResponse>;
    get assessmentUrl(): string;
    get listFirewallPoliciesUrl(): string;
    abstract buildEvent(req: EdgeRequest): Promise<Event>;
    abstract injectRecaptchaJs(resp: EdgeResponse): Promise<EdgeResponse>;
}