@gkcaptcha/types

Shared TypeScript types and error codes for gkCAPTCHA SDK packages.

Installation

npm install @gkcaptcha/types

Types

import type {
  VerifyTokenRequest,
  VerifyTokenResponse,
  ReasonCode,
  GkCaptchaProps,
  GkCaptchaRef,
} from '@gkcaptcha/types'

Error Codes

import { ErrorCodes, isBotRejection, isChallengeFailure, isServerError } from '@gkcaptcha/types'

// Widget error code categories
isBotRejection(ErrorCodes.BOT_CDP_DETECTED)    // true (3xx)
isChallengeFailure(ErrorCodes.CHALLENGE_FAILED) // true (4xx)
isServerError(ErrorCodes.RATE_LIMITED)          // true (5xx)

GkCaptchaProps

Key props shared by @gkcaptcha/react and @gkcaptcha/vue:

| Prop | Type | Default | Description | |------|------|---------|-------------| | siteKey | string | required | Site key from gatekeeper.sa dashboard | | onVerify | (token: string) => void | — | Called when CAPTCHA passes | | onError | (error: string) => void | — | Called on widget error | | onExpire | () => void | — | Called when token expires | | mode | 'checkbox' \| 'invisible' \| 'overlay' | 'checkbox' | Widget display mode | | theme | 'light' \| 'dark' \| 'auto' | 'auto' | Color theme | | size | 'normal' \| 'compact' | 'normal' | Widget size | | lang | string | auto | Language code (e.g., 'ar', 'en') | | disabled | boolean | false | Disable pointer events |

VerifyTokenResponse

Returned by @gkcaptcha/node and @gkcaptcha/next/server:

interface VerifyTokenResponse {
  success: boolean       // true = valid token, false = invalid or error
  score: number          // 0.0 (human) to 1.0 (bot)
  timestamp: number      // Unix timestamp of token creation
  reasonCode?: string    // Why verification failed (if success=false)
}

Version

0.1.0 — part of the gkCAPTCHA SDK suite (@gkcaptcha/*).