verify-hcaptcha/dist/index.d.ts

A fully typed library to verify hCaptcha.com tokens submitted by users when solving captcha challenges

/**
A fully typed library to verify hCaptcha.com tokens submitted by users when solving captcha challenges.

@remarks
Note: this is an unofficial library; we are not affiliated with hCaptcha.com.

@example
Verify a token submitted by a user:

```typescript
import { verifyHcaptchaToken } from 'verify-hcaptcha';

const result = await verifyHcaptchaToken({
    token: "USER-SUBMITTED-RESPONSE-TOKEN", // Required
    secretKey: "YOUR-SECRET-KEY",           // Required
    siteKey: "YOUR-SITE-KEY",               // Optional
    remoteIp: "USER-IP-ADDRESS",            // Optional
});

if (result.success) {
    console.log("User is human");
} else {
    console.log("User is robot");
}
```

@packageDocumentation
*/
import * as z from "zod/mini";
export type ErrorCodes = 
/** Secret key is missing. */
"missing-input-secret"
/** Secret key is invalid. */
 | "invalid-input-secret"
/** User response token is missing. */
 | "missing-input-response"
/** User response token is invalid. */
 | "invalid-input-response"
/** User response token is expired. */
 | "expired-input-response"
/** User response token was already verified once. */
 | "already-seen-response"
/** Request is invalid. */
 | "bad-request"
/** Remote user IP is missing. */
 | "missing-remoteip"
/** Remote user IP is invalid. */
 | "invalid-remoteip"
/** Must use the test site key when using a test verification token. */
 | "not-using-dummy-passcode"
/** The site key is not associated to the secret key. */
 | "sitekey-secret-mismatch"
/** Site key is invalid (Not listed on hcaptcha docs). */
 | "invalid-sitekey"
/** Must use the test secret key when using a test verification token (Not listed on hcaptcha docs). */
 | "not-using-dummy-secret";
declare const hCaptchaResponseSchema: z.ZodMiniPipe<z.ZodMiniObject<{
    success: z.ZodMiniBoolean<boolean>;
    challenge_ts: z.ZodMiniOptional<z.ZodMiniString<string>>;
    hostname: z.ZodMiniOptional<z.ZodMiniString<string>>;
    credit: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
    "error-codes": z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniType<ErrorCodes | (string & {}), unknown, z.core.$ZodTypeInternals<ErrorCodes | (string & {}), unknown>>>>;
    score: z.ZodMiniOptional<z.ZodMiniNumber<number>>;
    "score-reason": z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
}, z.core.$strip>, z.ZodMiniTransform<{
    /** True if the token is valid and meets the specified security criteria (e.g., if the site key is associated to the secret key). */
    success: boolean;
    /** UTC timestamp of the challenge in ISO 8601 format (e.g., `2021-10-02T18:12:10.149Z`). */
    challengeTimestamp: string | undefined;
    /** Hostname of the website where the challenge was solved. */
    hostname: string | undefined;
    /** True if the response will be credited. @deprecated */
    credit: boolean | undefined;
    /** Error codes. @see {@link https://docs.hcaptcha.com/#siteverify-error-codes-table} */
    errorCodes: (ErrorCodes | (string & {}))[] | undefined;
    /** Enterprise-only feature: score for malicious activity. */
    score: number | undefined;
    /** Enterprise-only feature: list of reasons for the malicious activity score. */
    scoreReasons: string[] | undefined;
}, {
    success: boolean;
    challenge_ts?: string | undefined;
    hostname?: string | undefined;
    credit?: boolean | undefined;
    "error-codes"?: (ErrorCodes | (string & {}))[] | undefined;
    score?: number | undefined;
    "score-reason"?: string[] | undefined;
}>>;
/**
`HcaptchaResponse` represents the response to the verification challenge performed by calling {@link verifyHcaptchaToken}.
@see {@link https://docs.hcaptcha.com/#verify-the-user-response-server-side}
*/
export type HcaptchaResponse = z.infer<typeof hCaptchaResponseSchema>;
/**
`verifyHcaptchaToken` verifies with the hCaptcha.com API that the response token obtained
from a user who solved a captcha challenge is valid.

@param token - required: the token obtained from the user who solved the captcha challenge
@param secretKey - required: the secret key for your account
@param siteKey - optional but recommended: the site key for the website hosting the captcha challenge
@param remoteIp - optional: the IP address of the user who solved the challenge

@returns a {@link HcaptchaResponse} with the verification result
*/
export declare function verifyHcaptchaToken({ token, secretKey, siteKey, remoteIp, }: {
    token: string;
    secretKey: string;
    siteKey?: string;
    remoteIp?: string;
}): Promise<HcaptchaResponse>;
export {};