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

# TypeScript SDK

> Install the TypeScript SDK, classify user input and tool output, and route the verdict.

## Prerequisites

Use Node.js 20 or later.

Set `SILMARIL_API_KEY` and `SILMARIL_API_URL` from your [deployment access](https://silmaril.dev/docs/start/access.md).

## Install

```sh theme={"theme":"github-light-default"}
npm install @silmaril-security/sdk@0.10.0
```

## Classify your first request

Create one client per protected system and reuse it. Label each call with the boundary it checks.

```typescript theme={"theme":"github-light-default"}
import { Firewall, HookLabel } from "@silmaril-security/sdk"

const fw = new Firewall({
  apiKey: process.env.SILMARIL_API_KEY!,
  apiUrl: process.env.SILMARIL_API_URL!,
})

const result = await fw.classify("Summarize this release note.", {
  hook: HookLabel.USER_INPUT,
})

const blocked =
  result.prediction === "MALICIOUS" || result.governance?.action === "block"

console.log(result.prediction, result.score.toFixed(4), blocked ? "block" : "allow")
```

For tool output, pass the tool name as well.

```typescript theme={"theme":"github-light-default"}
await fw.classify(toolOutput, {
  hook: HookLabel.TOOL_RESPONSE,
  toolName: "read_file",
})
```

### Expected result

A benign request logs `BENIGN`, its score, and `allow`. Direct `classify` calls return a result in every mode. To enforce Block mode, stop the event when `prediction` is `MALICIOUS` or `governance.action` is `block`, then route it with [firewall outcomes](https://silmaril.dev/docs/sdk/outcomes.md).

See [confidence scores](https://silmaril.dev/docs/guides/enforcement.md#confidence-scores) for score meaning and threshold behavior.

A per-call mode wins the client setting. Either local choice is sent with the request and preserved in `result.mode`. Without a local override, current classify responses omit `mode`, so `result.mode` remains absent. Direct calls are decision-only regardless: the caller chooses whether to enforce according to its local mode and application policy.

A rejected promise means the call did not produce a verdict. That includes `SilmarilApiError` for a non-2xx API response, and a network, timeout, or abort error. With native `fetch`, a refused redirect raises a `TypeError`. Custom `fetch` implementations can differ. Decide whether that boundary fails open or closed.

Vercel, LangChain, and LangGraph integrations that wrap this client are documented in [Framework SDKs](https://silmaril.dev/docs/integrations/frameworks.md).

## Concurrent requests

Reuse one client for concurrent calls in a JavaScript runtime when those calls are independent events or different conversations. Ordered events that share one `metadata.conversationId` wait for each `classify()` call before the next event is sent. Pass `signal` to `classify` or `classifyBatch` to cancel one request and its retry wait. Create a client in each worker thread.

```typescript theme={"theme":"github-light-default"}
// Independent events in different conversations.
const [first, second] = await Promise.all([
  fw.classify(firstInput, {
    hook: HookLabel.USER_INPUT,
    metadata: { conversationId: "conv-a" },
  }),
  fw.classify(secondInput, {
    hook: HookLabel.TOOL_RESPONSE,
    toolName: "read_file",
    metadata: { conversationId: "conv-b" },
  }),
])

await fw.classify(userInput, {
  hook: HookLabel.USER_INPUT,
  signal: request.signal,
})
```

`request.signal` is the caller's `AbortSignal`. `classifyBatch()` cancels as one request. Its items stay independent of one another.

## Batch calls and conversation history

`classifyBatch()` requires a `predictions` array with one result per input. Missing or mismatched results reject with an `Error`, including during retries.

Pass `metadata: { conversationId }` on each ordered `classify()` call. Wait for and handle its verdict or error before sending the next event. Batch calls preserve per-item metadata and treat items independently of conversation history.

See [events and conversations](https://silmaril.dev/docs/guides/events.md) for sequencing and [modes and enforcement](https://silmaril.dev/docs/guides/enforcement.md) for returned verdicts in Warn and Shadow.

## Classify in parallel

From SDK 0.10.0, `protect()` runs your call while its input is classified instead of waiting for the verdict first. It accepts the `classify()` options plus the input `text`, and resolves with your call's result.

```typescript theme={"theme":"github-light-default"}
const answer = await fw.protect((signal) => callModel(prompt, { signal }), {
  text: prompt,
  hook: HookLabel.USER_INPUT,
  metadata: { conversationId },
  output: (response) => response.text,
})
```

`callModel`, `prompt`, and `conversationId` belong to your application. Unlike direct `classify()`, `protect()` enforces the verdict.

| Effective mode | Behavior |
| - | - |
| Block | Withholds the result until the verdict arrives. A would-block decision rejects with `FirewallBlockedException`, and the `signal` passed to your call aborts when the block arrives first |
| Shadow or Warn | Resolves with your result immediately. The classification finishes in the background |

Without a local mode, `protect()` uses the Block fallback. The optional `output` function extracts text from the result. That text is classified as `llm_output` before the result is returned in Block mode, and in the background in Shadow or Warn.

Use `protect()` for calls whose effect can be discarded, such as a model call. Classify the arguments of a tool that writes with `classify()` before running it.

Classifications that share one `metadata.conversationId` are sent in the order they started, so `protect()` keeps the conversation sequence without waiting between events. Two client options bound this work: `maxConcurrent` (default 32) limits classifications in flight, and `maxQueued` (default 64) limits unjoined background classifications per conversation. A background classification retries once. Background classifications are also capped at `maxConcurrent * maxQueued` across all conversations. A failed one is logged with `console.warn` and never rejects, and one that would exceed either limit is dropped with a warning. Metadata and governance are copied when the call starts, so changing them afterwards does not change a classification already under way.

Call `await fw.flush()` to wait for background classifications, for example before a serverless handler returns.

## Shadow mode

An explicit local Shadow mode reports would-block decisions with the same thresholds while traffic continues. In Shadow mode, LangChain handlers and Deep Agents middleware classify in the background, so `onClassify` runs after the callback returns; set `failOpen: false` to keep those checks inline. Vercel middleware classifies inline in every mode. Framework adapters resolve an adapter override first, then the client setting, then an optional response mode, and finally a Block fallback. Current classify responses omit `mode`, so set Shadow or Warn locally when an adapter should observe rather than block.

```typescript theme={"theme":"github-light-default"}
const fw = new Firewall({
  apiKey: process.env.SILMARIL_API_KEY!,
  apiUrl: process.env.SILMARIL_API_URL!,
  shadowMode: true,
})

const handler = await fw.asLangChainHandler({
  onClassify: (event) => {
    if (event.blocked && event.shadowMode) {
      console.warn("would block", event.hook, event.result.score)
    }
  },
})

```

### Enforce one boundary

```typescript theme={"theme":"github-light-default"}
const enforcingHandler = await fw.asLangChainHandler({
  shadowMode: false,
})
```

Attach `enforcingHandler` to the model or graph whose callbacks should enforce.

## Errors

Blocking behavior depends on the integration. `protect()`, Vercel non-streaming generation, and LangChain callbacks throw `FirewallBlockedException` when they enforce a malicious or governance-block decision. The exception carries `score` and `threshold`.

```typescript theme={"theme":"github-light-default"}
import { FirewallBlockedException } from "@silmaril-security/sdk"

try {
  await generateText({ model, prompt: userInput })
} catch (err) {
  if (err instanceof FirewallBlockedException) {
    console.warn("blocked", err.score, err.threshold)
    return
  }
  throw err
}
```

`generateText` and `model` come from the [Vercel integration](https://silmaril.dev/docs/sdk/vercel-ai.md). With Vercel streaming, an output block surfaces as an error stream part after any text already emitted. Deep Agents replaces denied tool interactions or model content with fixed safe messages in Block mode. See [Deep Agents](https://silmaril.dev/docs/integrations/deep-agents.md). Rethrow any non-block error from non-streaming calls according to your application error policy.

### HTTP 408 handling

TypeScript retries HTTP `429` only. HTTP `408`, including the direct runtime request-body timeout before classification, is surfaced as `SilmarilApiError`. This timeout closes the connection and produces no verdict. It does not establish replay safety for model or tool operations.

## Review depth

See [review depth](https://silmaril.dev/docs/guides/review-depth.md) for minimum SDK versions and selection behavior.

The public `ReviewLevel` type is `"standard" | "deep"`. Set `review` in `Firewall` options for an explicit client default, or in `classify` and `classifyBatch` options for a per-call selection. Resolution is explicit per-call value, then explicit client default, then omission of the wire field. The SDK never invents an implicit default.

```typescript theme={"theme":"github-light-default"}
import {
  Firewall,
  ReviewCompatibilityError,
  type ReviewLevel,
} from "@silmaril-security/sdk"

const clientReview: ReviewLevel = "deep"
const fw = new Firewall({
  apiKey: process.env.SILMARIL_API_KEY!,
  apiUrl: process.env.SILMARIL_API_URL!,
  review: clientReview,
})

try {
  // This per-call selection overrides the client's deep default.
  const result = await fw.classify("Summarize this release note.", {
    review: "standard",
  })
  const batch = await fw.classifyBatch(
    ["Check the first event.", "Check the second event."],
    { review: "deep" },
  )
} catch (error) {
  if (error instanceof ReviewCompatibilityError) {
    // Deploy backend acknowledgement support before enabling review selection.
  }
  throw error
}
```

Use the exact strings `standard` and `deep`. Invalid values, including `null`, fail SDK validation. Missing or mismatched backend acknowledgement produces `ReviewCompatibilityError`. See [review depth](https://silmaril.dev/docs/guides/review-depth.md) for runtime requirements and response handling.

## Next steps

[Verify your integration](https://silmaril.dev/docs/start/verify.md), then review [modes and enforcement](https://silmaril.dev/docs/guides/enforcement.md).


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