TypeScript SDK

Prerequisites

Use Node.js 20 or later. Set SILMARIL_API_KEY and SILMARIL_API_URL from your deployment access.

Install

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.

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.

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

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.

// 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 for sequencing and modes and enforcement 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.

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.

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

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.

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

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 for runtime requirements and response handling.

Next steps

Verify your integration, then review modes and enforcement.

Start

Integrations

Guides

Operate

Deployment

SDK reference

Architecture

Prerequisites

Install

Classify your first request

Expected result

Concurrent requests

Batch calls and conversation history

Classify in parallel

Shadow mode

Enforce one boundary

Errors

HTTP 408 handling

Review depth

Next steps

​Prerequisites

​Install

​Classify your first request

​Expected result

​Concurrent requests

​Batch calls and conversation history

​Classify in parallel

​Shadow mode

​Enforce one boundary

​Errors

​HTTP 408 handling

​Review depth

​Next steps

Prerequisites

Install

Classify your first request

Expected result

Concurrent requests

Batch calls and conversation history

Classify in parallel

Shadow mode

Enforce one boundary

Errors

HTTP 408 handling

Review depth

Next steps