verify-hcaptcha/dist/index.d.ts

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

import { z } from 'zod';

/**
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",
    secretKey: "YOUR-SECRET-KEY",
    siteKey: "YOUR-SITE-KEY",
});

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

@packageDocumentation
*/

declare const hCaptchaResponseSchema: z.ZodEffects<z.ZodObject<{
    success: z.ZodBoolean;
    challenge_ts: z.ZodOptional<z.ZodString>;
    hostname: z.ZodOptional<z.ZodString>;
    credit: z.ZodOptional<z.ZodBoolean>;
    "error-codes": z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodLiteral<"missing-input-secret">, z.ZodLiteral<"invalid-input-secret">, z.ZodLiteral<"missing-input-response">, z.ZodLiteral<"invalid-input-response">, z.ZodLiteral<"invalid-sitekey">, z.ZodLiteral<"missing-remoteip">, z.ZodLiteral<"invalid-remoteip">, z.ZodLiteral<"bad-request">, z.ZodLiteral<"invalid-or-already-seen-response">, z.ZodLiteral<"not-using-dummy-passcode">, z.ZodLiteral<"not-using-dummy-secret">, z.ZodLiteral<"sitekey-secret-mismatch">]>, "many">>;
    score: z.ZodOptional<z.ZodNumber>;
    "score-reason": z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
}, "strip", z.ZodTypeAny, {
    success: boolean;
    challenge_ts?: string | undefined;
    hostname?: string | undefined;
    credit?: boolean | undefined;
    "error-codes"?: ("missing-input-secret" | "invalid-input-secret" | "missing-input-response" | "invalid-input-response" | "invalid-sitekey" | "missing-remoteip" | "invalid-remoteip" | "bad-request" | "invalid-or-already-seen-response" | "not-using-dummy-passcode" | "not-using-dummy-secret" | "sitekey-secret-mismatch")[] | undefined;
    score?: number | undefined;
    "score-reason"?: string[] | undefined;
}, {
    success: boolean;
    challenge_ts?: string | undefined;
    hostname?: string | undefined;
    credit?: boolean | undefined;
    "error-codes"?: ("missing-input-secret" | "invalid-input-secret" | "missing-input-response" | "invalid-input-response" | "invalid-sitekey" | "missing-remoteip" | "invalid-remoteip" | "bad-request" | "invalid-or-already-seen-response" | "not-using-dummy-passcode" | "not-using-dummy-secret" | "sitekey-secret-mismatch")[] | undefined;
    score?: number | undefined;
    "score-reason"?: string[] | undefined;
}>, {
    /** 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: ("missing-input-secret" | "invalid-input-secret" | "missing-input-response" | "invalid-input-response" | "invalid-sitekey" | "missing-remoteip" | "invalid-remoteip" | "bad-request" | "invalid-or-already-seen-response" | "not-using-dummy-passcode" | "not-using-dummy-secret" | "sitekey-secret-mismatch")[] | 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"?: ("missing-input-secret" | "invalid-input-secret" | "missing-input-response" | "invalid-input-response" | "invalid-sitekey" | "missing-remoteip" | "invalid-remoteip" | "bad-request" | "invalid-or-already-seen-response" | "not-using-dummy-passcode" | "not-using-dummy-secret" | "sitekey-secret-mismatch")[] | 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}
*/
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
*/
declare function verifyHcaptchaToken({ token, secretKey, siteKey, remoteIp, }: {
    token: string;
    secretKey: string;
    siteKey?: string;
    remoteIp?: string;
}): Promise<HcaptchaResponse>;

export { type HcaptchaResponse, verifyHcaptchaToken };