@gkcaptcha/node

Node.js server SDK for gkCAPTCHA token verification.

Requirements

• Node.js >= 18 (or Bun / Deno)
• Zero runtime dependencies (uses native fetch)

Installation

npm install @gkcaptcha/node

Quickstart

GatekeeperClient (recommended for apps with frequent verification)

import { GatekeeperClient } from '@gkcaptcha/node'

// Create once, reuse across requests
const gatekeeper = new GatekeeperClient({
  siteKey: process.env.GKCAPTCHA_SITE_KEY!,
  secretKey: process.env.GKCAPTCHA_SECRET_KEY!,
})

// In your route handler:
const result = await gatekeeper.verifyToken(captchaToken)
if (!result.success) {
  return res.status(403).json({ error: 'CAPTCHA verification failed' })
}

createGatekeeper (reads env vars automatically)

import { createGatekeeper } from '@gkcaptcha/node'

// Reads GKCAPTCHA_SITE_KEY and GKCAPTCHA_SECRET_KEY from process.env
const gatekeeper = createGatekeeper()

const result = await gatekeeper.verifyToken(captchaToken)

verifyToken (standalone, one-shot)

import { verifyToken } from '@gkcaptcha/node'

const result = await verifyToken(captchaToken, {
  siteKey: process.env.GKCAPTCHA_SITE_KEY!,
  secretKey: process.env.GKCAPTCHA_SECRET_KEY!,
})

Response Shape

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)
}

Fail-Closed Behavior

All errors (network failure, timeout, 5xx server errors) return { success: false } — they never throw. This ensures your application stays secure when the CAPTCHA service is unreachable.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GKCAPTCHA_SITE_KEY | Yes | Site key from gatekeeper.sa dashboard | | GKCAPTCHA_SECRET_KEY | Yes | Secret key from gatekeeper.sa dashboard | | GKCAPTCHA_API_URL | No | Override API URL (default: https://gkcaptcha.gatekeeper.sa) |

Options

new GatekeeperClient({
  siteKey: '...',
  secretKey: '...',
  apiUrl: 'https://gkcaptcha.gatekeeper.sa', // default
  timeout: 5000,   // ms, default: 5000
  retries: 1,      // default: 1
  debug: false,    // logs requests (never logs secrets), default: false
})