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

# TypeScript SDK

> @frostwolfai/sdk: install, client options, methods, and defaults.

```bash theme={null}
npm install @frostwolfai/sdk
```

Ships ESM, CJS, and TypeScript declarations. Requires Node.js 18 or newer. No runtime dependencies.

## Client

```ts theme={null}
import { FrostWolfClient } from "@frostwolfai/sdk";

const fw = new FrostWolfClient({ apiKey: process.env.FROSTWOLF_API_KEY! });
```

### Options

<ParamField body="apiKey" type="string" required>
  Authenticates detection, telemetry, and capture. Throws `FrostWolfError` when missing or blank.
</ParamField>

<ParamField body="endpoint" type="string" default="https://api.frostwolf.app">
  Base URL of the FrostWolf API.
</ParamField>

<ParamField body="telemetry" type="boolean" default="true">
  Ship scan metrics to the console. Detection is unaffected either way.
</ParamField>

<ParamField body="flushIntervalMs" type="number" default="5000">
  How often the telemetry queue is flushed.
</ParamField>

<ParamField body="maxBatchSize" type="number" default="50">
  Flush as soon as this many events are queued.
</ParamField>

<ParamField body="maxQueueSize" type="number" default="1000">
  Drop the oldest events past this depth, so a stalled network cannot leak memory.
</ParamField>

<ParamField body="timeoutMs" type="number" default="5000">
  Abort a detection call or a background flush after this long.
</ParamField>

<ParamField body="includeEvidence" type="boolean" default="false">
  Return matched substrings and include them in telemetry. Off because evidence is your text.
</ParamField>

<ParamField body="onScanError" type={'"block" | "allow"'} default="block">
  What to do when the detection call fails. `block` fails closed.
</ParamField>

<ParamField body="capture" type="boolean | CaptureOptions" default="false">
  Capture request and response bodies for decorated calls. Off because bodies are your text.
</ParamField>

<ParamField body="fetch" type="FetchLike">
  Override the transport. Defaults to the global `fetch`.
</ParamField>

<ParamField body="onError" type="(error: Error) => void">
  Called when a detection call or background flush fails. Never throws.
</ParamField>

<ParamField body="guard" type="GuardOptions">
  Defaults applied to every guard call.
</ParamField>

### `GuardOptions`

| Option | Type | Default | Purpose |
| - | - | - | - |
| `onMatch` | `"block" \| "sanitise" \| "allow"` | `"block"` | What `wrap` and `decorate` do when a payload trips the policy. |
| `blockSeverity` | `Severity` | `"medium"` | Lowest severity that trips the policy. |
| `maxScanChars` | `number` | `100000` | Payloads longer than this are truncated server-side. |
| `replacement` | `string` | `"[REDACTED]"` | Text substituted for each redacted span. |
| `onDecision` | `(result) => void` | none | Called after every inspection. |
| `cloak` | `CloakConfig` | none | Where Cloak keeps values and how it derives tokens. |

### `CloakConfig`

| Option | Default | Purpose |
| - | - | - |
| `vault` | in-memory | Where tokenized values are kept. |
| `key` | random per process | Secret that keys tokens and hashes. |
| `semanticPass` | `"enforce"` | What the semantic pass may do on calls that use Cloak. |
| `vaultTtlMs` | `3600000` | How long a value is kept. |
| `maxVaultEntries` | `10000` | Cap on the default in-memory store. |

## Client methods

| Method | Returns | Notes |
| - | - | - |
| `init(options?)` | `Promise<InitResult>` | Authenticate the key, optionally setting capture. Never rejects. |
| `flush()` | `Promise<void>` | Send everything queued. |
| `close()` | `Promise<void>` | Flush, and stop the background timers. |

```ts theme={null}
const { authenticated, captureEnabled } = await fw.init({ capture: true });
```

`captureEnabled` is read back from the server, so a caller that asked for capture and did not get it can tell.

## `fw.guard`

| Method | Returns | Notes |
| - | - | - |
| `scan(input)` | `Promise<ScanResult>` | Never rejects. |
| `sanitise(input)` | `Promise<SanitiseResult>` | Redacts matches, returns both provider shapes. |
| `wrap(input, call, options?)` | `Promise<T \| BlockedResponse>` | Applies `onMatch`. Skips `call` when blocking. |
| `decorate(fn, options?)` | `(...args) => Promise<T \| BlockedResponse>` | Wraps a completions function. |
| `protect(input, options?)` | `Promise<ProtectResult>` | Attacks and personal data in one call. |
| `isBlocked(input)` | `Promise<boolean>` | Fast path. |
| `assertAllowed(input)` | `Promise<ScanResult>` | Rejects with `BlockedError` when blocked. |
| `validateToolCalls(calls, options?)` | `Promise<ToolValidationResult>` | Judges calls before execution. |

## `fw.guard.cloak`

| Method | Returns | Notes |
| - | - | - |
| `scan(input, options?)` | `Promise<CloakBlock>` | Find entities without changing anything. Never rejects. |
| `protect(input, options)` | `Promise<ProtectResult>` | Cloak without the attack check. |
| `restore(value, { context, onDenied? })` | `Promise<RestoreResult<T>>` | Restore a string or JSON value. |
| `forget(context)` | `Promise<number>` | Erase everything held for one identity. |

## Errors

| Error | When |
| - | - |
| `FrostWolfError` | Misuse, such as a missing key or invalid option. Has a `code`. |
| `BlockedError` | Thrown by `assertAllowed`. Carries the full result. |
| `RestoreDeniedError` | A response carried another context's token. Has `denied`, a count. |

## Defaults

| Option | Default |
| - | - |
| `endpoint` | `https://api.frostwolf.app` |
| `telemetry` | `true` |
| `capture` | `false` |
| `includeEvidence` | `false` |
| `onScanError` | `"block"` |
| `timeoutMs` | `5000` |
| `flushIntervalMs` | `5000` |
| `maxBatchSize` | `50` |
| `maxQueueSize` | `1000` |
| `onMatch` | `"block"` |
| `replacement` | `"[REDACTED]"` |
| `vaultTtlMs` | `3600000` |
| `maxVaultEntries` | `10000` |
| `semanticPass` | `"enforce"` |
| `onUnavailable` | `"block"` |
| `onDenied` | `"throw"` |
| `skipWhenBlocked` | `true` |

These values are identical in the Python SDK.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.