> ## Documentation Index
> Fetch the complete documentation index at: https://captcha.ribaunt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

> Complete TypeScript type reference for Ribaunt: ChallengeToken, ChallengeSolution, ReplayStore, VerifySolutionOptions, VerifyWarning, and more.

Ribaunt ships TypeScript types for all its public APIs. Import types from `ribaunt` for use in your server-side code.

## `ChallengeToken`

A signed JWT challenge token. This is the string value returned in the array from `createChallenge()` and the value you pass back to `verifySolution()`.

```ts theme={null}
type ChallengeToken = string; // A signed JWT challenge token
```

## `ChallengeSolution`

The proof-of-work solution produced by the browser solver (or by `solveChallenge()` in tests). The `nonce` is the value that, when hashed with the challenge string, produces a SHA-256 digest beginning with the required number of leading zero hex digits.

```ts theme={null}
interface ChallengeSolution {
  nonce: string; // The nonce that satisfies the PoW condition
  hash: string;  // The SHA-256 hash (hex) produced by nonce
}
```

## `ChallengeOptions`

The options object accepted by `createChallenge()`.

```ts theme={null}
interface ChallengeOptions {
  difficulty?: number | 'auto';
  amount?: number;
  ttlSeconds?: number;
  context?: string;
  workload?: Pick<Workload, 'difficulty' | 'amount'>;

  // Only used when difficulty === 'auto':
  targetDurationMs?: number;   // default 750
  riskScore?: number;          // 0–100, default 50
  calibration?: ClientCalibration;
  minDifficulty?: number;      // default 3
  maxDifficulty?: number;      // default 6
  minAmount?: number;          // default 1
  maxAmount?: number;          // default 8
}
```

## `ClientCalibration`

Reported benchmark from the client used as a raise-only signal in `"auto"` mode.

```ts theme={null}
interface ClientCalibration {
  iterations: number;
  durationMs: number;
}
```

## `Workload` and `AdaptiveWorkloadOptions`

`selectWorkload()` returns a `Workload` object and accepts an optional adaptive configuration.

```ts theme={null}
interface AdaptiveWorkloadOptions extends WorkloadBounds {
  riskScore?: number;
  targetDurationMs?: number;
  calibration?: ClientCalibration;
}

interface Workload {
  difficulty: number;
  amount: number;
  estimatedAttempts: number;
}
```

## `ReplayStore`

The interface you implement to provide distributed replay prevention when `replayPrevention` is set to `'remote'`. You pass your implementation to `verifySolution()` via `options.replayStore`.

```ts theme={null}
interface ReplayStore {
  consume(jti: string, expiresAt: number): Promise<boolean>;
  consumeMany?(jtis: string[], expiresAt: number): Promise<boolean>;
}
```

`jti` is the JWT token ID uniquely identifying the challenge. `expiresAt` is a Unix timestamp in seconds indicating when the token expires. Return `true` to allow the submission (first use) and `false` to reject it (replay detected). Your implementation must be atomic — use a primitive such as Redis `SET NX EXAT` to avoid race conditions.

## `LocalReplayStore`

The built-in, process-local implementation of `ReplayStore` exported from `ribaunt`. It stores consumed token IDs in memory and automatically evicts entries once their TTL has passed. Use this when `replayPrevention` is `'local'` (the default) — it is used automatically in that mode. You can also instantiate it directly when you need a dedicated per-handler store.

```ts theme={null}
class LocalReplayStore implements ReplayStore {
  async consume(jti: string, expiresAt: number): Promise<boolean>;
  async consumeMany(jtis: string[], expiresAt: number): Promise<boolean>;
}
```

```ts theme={null}
import { LocalReplayStore } from 'ribaunt';

const store = new LocalReplayStore();

const result = await verifySolution(tokens, solutions, {
  replayPrevention: 'remote',
  replayStore: store,
});
```

`LocalReplayStore` is not suitable for multi-process or serverless deployments. For those environments, implement your own `ReplayStore` backed by a distributed atomic store such as Redis `SET NX EXAT`.

## `ReplayPreventionMode`

Controls how `verifySolution()` prevents a token from being submitted more than once.

```ts theme={null}
type ReplayPreventionMode = 'disabled' | 'local' | 'remote';
```

* **`'local'`** (default) — replay checks are process-local. Suitable for single-process deployments.
* **`'remote'`** — replay checks use your `ReplayStore`. Use this for serverless or horizontally scaled deployments.
* **`'disabled'`** — no replay checks. Tokens can be reused until they expire. Only use this if another layer handles replay prevention.

## `VerifySolutionOptions`

Optional configuration passed as the third argument to `verifySolution()`.

```ts theme={null}
interface VerifySolutionOptions {
  replayPrevention?: ReplayPreventionMode; // default: 'local'
  replayStore?: ReplayStore;               // required when replayPrevention is 'remote'
  context?: string;                        // optional challenge scope
  debug?: boolean;                         // default: true in development
  onWarning?: (warning: VerifyWarning) => void;
}
```

## `VerifySolutionResult`

The structured result returned by `verifySolution()`.

```ts theme={null}
type VerifySolutionResult =
  | { valid: true }
  | { valid: false; reason: VerifyFailureReason; message: string };
```

## `VerifyWarning`

The structured warning object passed to the `onWarning` callback when `verifySolution()` encounters a problem. This allows you to capture telemetry without enabling console output.

```ts theme={null}
interface VerifyWarning {
  reason: VerifyWarningReason;
  message: string;
  error?: unknown;
}
```

## `VerifyFailureReason` and `VerifyWarningReason`

A string union describing the category of verification failure. You can use this to route warnings to different monitoring channels or metrics.

```ts theme={null}
type VerifyFailureReason =
  | 'invalid-token'
  | 'expired-token'
  | 'invalid-solution'
  | 'context-mismatch'
  | 'replay-detected'
  | 'configuration-error';

type VerifyWarningReason = VerifyFailureReason;
```

## `SolveChallengeOptions`

Optional guardrails passed to `solveChallenge()` to prevent it from running indefinitely during tests.

```ts theme={null}
interface SolveChallengeOptions {
  maxIterations?: number; // hard cap on nonce attempts
  maxDurationMs?: number; // default: 30000 ms
}
```

## `WidgetState`

Imported from `ribaunt/widget`. Represents the current state of the CAPTCHA widget in the browser.

```ts theme={null}
type WidgetState = 'initial' | 'fetching' | 'solving' | 'verifying' | 'done' | 'error';
```

## `WidgetErrorCode`

Machine-readable error classification emitted on the widget's `error` event `detail.code`.

```ts theme={null}
type WidgetErrorCode =
  | 'timeout'
  | 'aborted'
  | 'challenge-fetch-failed'
  | 'invalid-challenge'
  | 'solve-failed'
  | 'verification-failed'
  | 'worker-unavailable'
  | 'unknown';
```

## `RibauntWidgetHandle`

Imported from `ribaunt/widget-react`. This is the imperative handle exposed via a React `ref` attached to the `<RibauntWidget>` component. Use it to programmatically control the widget from your application code.

```ts theme={null}
interface RibauntWidgetHandle {
  reset(): void;
  getState(): WidgetState | '';
  startVerification(): void;
}
```