# TypeScript SDK

JavaScript and TypeScript SDK for the Highflame guardrails service. The TypeScript package gives you two main ways to integrate Shield:

* `Shield` wrappers for the fastest path around prompts, tools, and model outputs
* the `Highflame` client when you want full request and response control

## Read This Section in Order

1. [Getting Started](/api-reference/sdk/shield/typescript-sdk/getting-started.md): install `@highflame/sdk`, authenticate, and wire up your first guarded function
2. [Shield Wrappers](/api-reference/sdk/shield/typescript-sdk/shield-wrappers.md): choose the right wrapper and configure it correctly
3. [Low-Level Client](/api-reference/sdk/shield/typescript-sdk/client-api.md): use `client.guard.*`, `client.detect.*`, `client.detectors.*`, and `client.debug.*`
4. [Advanced Topics](/api-reference/sdk/shield/typescript-sdk/advanced-topics.md): debugging, optimization, streaming, context objects, sessions, and runtime options

## Choosing the Right API

| I want to...                                             | Use                                                              |
| -------------------------------------------------------- | ---------------------------------------------------------------- |
| Guard a prompt before my LLM runs                        | `shield.prompt(fn)`                                              |
| Guard a tool call before it executes                     | `shield.tool(fn)`                                                |
| Guard a tool's return value before it's used             | `shield.toolResponse(fn)`                                        |
| Guard the LLM's output before returning to the caller    | `shield.modelResponse(fn)`                                       |
| Guard a file read or write                               | `shield.wrap({ contentType: "file", action: "write_file" })(fn)` |
| Evaluate with full control and inspect the full response | `client.guard.evaluate()`                                        |
| Evaluate a prompt with minimal code                      | `client.guard.evaluatePrompt()`                                  |
| Evaluate a tool call with minimal code                   | `client.guard.evaluateToolCall()`                                |
| Run detectors without Cedar policy evaluation            | `client.detect.run()`                                            |
| Observe traffic without blocking                         | pass `mode: "monitor"`                                           |
| Understand why a decision was made                       | pass `explain: true`                                             |
| See per-detector breakdowns                              | pass `debug: true`                                               |
| Only run detectors referenced by active policies         | pass `optimize: true`                                            |

{% hint style="warning" %}
**`BlockedError` is only thrown by `Shield` wrappers.** Direct `client.guard.evaluate()` calls always resolve, even when the decision is deny.
{% endhint %}

{% hint style="warning" %}
**Create one `Highflame` client per process, not per request.** The client maintains an internal token cache.
{% endhint %}

## Framework Support

The TypeScript SDK ships first-class framework integrations for LangGraph, CrewAI, AWS Strands, and Azure AI Foundry — matching the Python SDK. Import them from their subpaths:

```typescript
import { HighflameMiddleware } from "@highflame/sdk/integrations/langgraph";
import { HighflameCrewHooks } from "@highflame/sdk/integrations/crewai";
import { HighflameStrandsHooks } from "@highflame/sdk/integrations/strands";
import { HighflameFoundryMiddleware } from "@highflame/sdk/integrations/foundry";
```

See the [Framework Integrations](/api-reference/sdk/shield/integrations.md) reference for full usage. For custom integrations or call sites not covered by a framework adapter, integrate Shield at your model and tool boundaries with `Shield` wrappers or direct `client.guard.*` calls.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/api-reference/sdk/shield/typescript-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.