@putin007/att-captcha-sdk-core

@putin007/att-captcha-sdk-core is the headless orchestration layer. It owns verification session state, provider orchestration, backend calls, and event emission.

Public API

Core

• initAttCapchaSdk(options)
• FrontendSdk
• MemoryStateManager
• SessionStorageStateManager
• LocalStorageStateManager

The React and Vue demo apps in this repo consume backend endpoints from the delivery config exported by the SDK itself, instead of hardcoded 127.0.0.1:9001 values or direct client-side env reads.

Integrations

• createGoCaptchaPuzzleAdapter(options)
• createGoCaptchaDirectBackendAdapter(options)
• createJsonGatewayAdapter(options)
• createUnifiedGatewayAdapter(options)
• createPowProvider(options)
• createReCaptchaAdapter(options)

Example: current repo backend

import {
  GO_CAPTCHA_CHALLENGE_TYPES,
  initAttCapchaSdk,
  createGoCaptchaDirectBackendAdapter,
  createGoCaptchaPuzzleAdapter,
} from '@putin007/att-captcha-sdk-core'

const sdk = initAttCapchaSdk({
  config: {
    mode: 'puzzle',
  },
  puzzleAdapter: createGoCaptchaPuzzleAdapter({
    type: 'click',
    challengeEndpoint: '/api/go-captcha-data/click-basic',
    config: {
      type: GO_CAPTCHA_CHALLENGE_TYPES.CLICK_BASIC,
    },
  }),
  stateManager: new SessionStorageStateManager('demo.click-basic'),
  backendAdapter: createGoCaptchaDirectBackendAdapter({
    verifyEndpoint: '/api/go-captcha-check-data/click-basic',
    includeArtifacts: true,
  }),
})

await sdk.loadPuzzle()
await sdk.verify({
  puzzleInput: [
    { x: 18, y: 42 },
    { x: 102, y: 60 },
  ],
})

Example: unified gateway

import {
  GO_CAPTCHA_CHALLENGE_TYPES,
  SessionStorageStateManager,
  initAttCapchaSdk,
  createGoCaptchaPuzzleAdapter,
  createPowProvider,
  createReCaptchaAdapter,
  createUnifiedGatewayAdapter,
} from '@putin007/att-captcha-sdk-core'

const sdk = initAttCapchaSdk({
  config: {
    mode: 'puzzle',
  },
  powProvider: createPowProvider({
    loadChallenge: async () => ({
      salt: 'pow-salt',
      difficulty: 18,
    }),
  }),
  reCaptchaAdapter: createReCaptchaAdapter({
    siteKey: 'your-site-key',
    mode: 'v3',
    action: 'captcha_verify',
  }),
  puzzleAdapter: createGoCaptchaPuzzleAdapter({
    type: 'slide',
    challengeEndpoint: '/api/go-captcha-data/slide-basic',
    config: {
      type: GO_CAPTCHA_CHALLENGE_TYPES.SLIDE_BASIC,
    },
  }),
  stateManager: new SessionStorageStateManager('demo.gateway.slide-basic'),
  backendAdapter: createUnifiedGatewayAdapter({
    endpoint: '/api/captcha/verify',
  }),
})

GoCaptcha variant config

createGoCaptchaPuzzleAdapter() supports config.type so the frontend can tell the backend which captcha variant should be returned.

initAttCapchaSdk() supports config.mode with puzzle, pow, and recaptcha. For backward compatibility, the SDK also accepts the legacy alias recapcha and normalizes it to the internal recaptcha mode. Only the active provider path for that instance is auto-run when config.mode is set.

Supported values:

• click_basic
• click_shape
• slide_basic
• slide_region
• rotate_basic
• random

Example:

const sdk = initAttCapchaSdk({
  config: {
    mode: 'puzzle',
  },
  puzzleAdapter: createGoCaptchaPuzzleAdapter({
    type: 'random',
    challengeEndpoint: '/api/go-captcha-data',
    config: {
      type: GO_CAPTCHA_CHALLENGE_TYPES.RANDOM,
    },
  }),
  backendAdapter: createUnifiedGatewayAdapter({
    endpoint: '/api/captcha/verify',
  }),
})

When config.type is random, the backend should return the actual captcha type in the challenge payload via captcha_type, captchaType, challenge_type, challengeType, or type so the SDK can render and submit the correct widget.

Unified gateway contract

type UnifiedCaptchaGatewayRequest = {
  schemaVersion: 'att.captcha-gateway.v1'
  session: {
    id: string
  }
  artifacts: {
    pow?: PowProof
    recaptcha?: ReCaptchaAssertion
    puzzle?: PuzzleSubmission
  }
  metadata?: Record<string, unknown>
}

type UnifiedCaptchaGatewayResponse = {
  schemaVersion: 'att.captcha-gateway.v1'
  success: boolean
  token?: string
  message?: string
  errorCode?: string
  nextAction?: 'retry' | 'refresh-puzzle' | 'refresh-session'
  metadata?: Record<string, unknown>
}