Node.js SDK

Zero-dependency server SDK for token verification. Works in Node 18+, Bun, and Deno.

Installation

terminal

npm install @gkcaptcha/node

GatekeeperClient

Recommended for apps with frequent verification — create once, reuse across requests. / موصى به للتطبيقات التي تتحقق بشكل متكرر — أنشئ مرة واحدة واستخدمه عبر الطلبات.

server.ts

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

Factory function that reads environment variables automatically. / دالة مصنع تقرأ متغيرات البيئة تلقائيًا.

server.ts

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 verification without creating a client instance. / تحقق بمرة واحدة بدون إنشاء نسخة من العميل.

handler.ts

import { verifyToken } from '@gkcaptcha/node'

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

Response Shape

types.ts

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.

جميع الأخطاء (فشل الشبكة، انتهاء المهلة، أخطاء 5xx) تُرجع { success: false } — ولا تُلقي استثناءات أبدًا. هذا يضمن أمان تطبيقك عندما تكون خدمة CAPTCHA غير متاحة.

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) / تجاوز رابط API

Options

config.ts

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