Server SDK API

HumanPass

new HumanPass(options: HumanPassClientOptions)

Client options

type HumanPassClientOptions = {
  baseUrl: string;
  secret: string;
  timeoutMs?: number;
  fetch?: typeof fetch;
};

Option	Required	Description
baseUrl	Yes	HumanPass service origin, normally https://humanpass.valgix.com.
secret	Yes	Site secret key. Never browser-visible.
timeoutMs	No	Request timeout; default 5000, minimum 100.
fetch	No	Standards-compatible custom fetch implementation.

verify()

humanpass.verify(input: VerifyInput): Promise<SiteverifyResult>

type VerifyInput = {
  response: string;
  remoteIp?: string;
  idempotencyKey?: string;
  expectedAction?: string;
  expectedHostname?: string;
  signal?: AbortSignal;
};

The SDK validates expected action and hostname locally after a successful service response. expectedHostname must be a hostname without scheme, path, or port.

Success

type SiteverifySuccess = {
  success: true;
  challenge_ts: string;
  hostname: string;
  action: string;
  sitekey: string;
  environment: "live" | "test";
  verification_id: string;
};

Failure

type SiteverifyFailure = {
  success: false;
  error_codes: SiteverifyErrorCode[];
  request_id?: string;
};

Exported errors

• HumanPassError — base SDK error.
• HumanPassConfigurationError — invalid base URL, secret format, timeout, or expected hostname.
• HumanPassTransportError — request could not reach a valid HumanPass response.
• HumanPassApiError — HumanPass returned a non-contract API response; includes status, optional code, and optional requestId.

Exported constants

HUMANPASS_API_VERSION // "v1"
SITEVERIFY_ERROR_CODES

The package exports the corresponding TypeScript request, result, error-code, environment, and fetch types.