TypeScript SDK - FrostWolf

npm install @frostwolfai/sdk

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

Client

import { FrostWolfClient } from "@frostwolfai/sdk";

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

Options

string

required

Authenticates detection, telemetry, and capture. Throws FrostWolfError when missing or blank.

string

default:"https://api.frostwolf.app"

Base URL of the FrostWolf API.

boolean

default:"true"

Ship scan metrics to the console. Detection is unaffected either way.

number

default:"5000"

How often the telemetry queue is flushed.

number

default:"50"

Flush as soon as this many events are queued.

number

default:"1000"

Drop the oldest events past this depth, so a stalled network cannot leak memory.

number

default:"5000"

Abort a detection call or a background flush after this long.

boolean

default:"false"

Return matched substrings and include them in telemetry. Off because evidence is your text.

"block" | "allow"

default:"block"

What to do when the detection call fails. block fails closed.

boolean | CaptureOptions

default:"false"

Capture request and response bodies for decorated calls. Off because bodies are your text.

FetchLike

Override the transport. Defaults to the global fetch.

(error: Error) => void

Called when a detection call or background flush fails. Never throws.

GuardOptions

Defaults applied to every guard call.

`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.

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.

​Client

​Options

​GuardOptions

​CloakConfig

​Client methods

​fw.guard

​fw.guard.cloak

​Errors

​Defaults

Client

Options

`GuardOptions`

`CloakConfig`

Client methods

`fw.guard`

`fw.guard.cloak`

Errors

Defaults