TypeScript SDK

@compresr/sdk is the official TypeScript client. It is fully typed, isomorphic (Node 20+, edge runtimes, modern browsers via a server proxy), and async by default. Every method returns a Promise or an AsyncGenerator.

1. Install

@compresr/sdk works with npm, pnpm, yarn, and bun. Ships ESM + CJS builds plus .d.ts types; no @types/... companion needed.

2. Initialize the client

Construct CompressionClient once at module scope and reuse it: the client keeps an internal connection pool. Pass apiKey; optionally timeout (ms, default 300_000, five minutes) and baseUrl (default https://api.compresr.ai). Uses the native fetch API (Node 20+, modern browsers, edge runtimes); no option to swap in a custom fetch.

The non-null assertion (!) on process.env.COMPRESR_API_KEY is fine in code you control; in serverless deployments whose env wiring you do not own, narrow with a guard. See Authentication.

Constructor options

Environment variables

3. compress

Single-request compression. Returns a Promise<CompressionResponse>; await it. Pass context, query, and compressionModelName: 'latte_v2'; the model keeps the spans that matter for the query. For many chunks against one query, see compressBatch; for token-by-token output, compressStream.

Parameters

latte_v2 accepts every parameter latte_v1 accepts, plus three latte_v2-only knobs for dynamic compression-ratio selection. See the Models reference for the canonical decision guide and the at-a-glance support matrix.

Shared parameters (both models)

latte_v2-only parameters

Response

Response field names are snake_case across every SDK; the SDK does not rename them. Matches what comes back over the wire.

4. Stream

client.compressStream(...) returns an AsyncGenerator<StreamChunk>; iterate with for await. Each chunk is { content: string; done: boolean; error?: string }. SSE framing is used for HTTP-level backpressure and forward-compat; the current backend implementation emits a single final frame carrying the full compressed output with done: true, so treat this like a POST that ends with a done: true sentinel — no time-to-first-token benefit yet. error? is reserved on the type but currently unused: server-side aborts propagate as thrown ConnectionError / CompresrError rather than as chunks with .error set. For one-shot calls stick with compress.

The generator is single-use. To consume the stream multiple ways (render to UI and persist to a log), tee it: wrap it in a function that pushes each chunk to multiple sinks before yielding.

5. Batch

client.compressBatch(...) compresses many contexts in one request. Pass contexts: string[] plus either a single queries: string (applied to every context) or a queries: string[] matching contexts in length. Cheaper than firing N concurrent compress() calls, and ideal for RAG re-ranking or bulk document processing.

The TypeScript queries param is typed string | string[]; the compiler does not enforce array length matching contexts.length, and that check is a runtime ValidationError from the SDK (raised before the request is sent). Batches are capped at 100 inputs per request. Per-item results carry the same fields as a single compress() call except target_compression_ratio (request-level only). The envelope also exposes aggregates: result.data.count, total_original_tokens, total_compressed_tokens, total_tokens_saved, average_compression_ratio.

Alternate form: inputs: BatchInput[]

The wire format is a list of { context, query } pairs. Pass inputs instead of contexts / queries when it matches your data shape more naturally (queues, streaming pipelines, per-item queries). Exactly one of inputs OR contexts is required; passing both — or neither — throws ValidationError('Pass \inputs` OR `contexts`, not both.')`.

6. Agent client

Construct CompressionClient with llm and you get an agent surface: three call-shapes (Anthropic-style messages.create, OpenAI-style chat.completions.create, native run) that auto-compress every tool output above minTokens before the LLM sees it. Behind all three sits LangChain.js 1.0's createAgent + the SDK's compresrToolMiddleware. Use it as a drop-in for new Anthropic() / new OpenAI(); for raw { context, query } calls stick with compress.

Construct with llm

Provider lives on the client; model lives at the call site. Swap providers by changing one string: same tools, same code:

The llm string accepts 'anthropic' (provider only, every call must pass model), 'anthropic:claude-haiku-4-5' (default model, overridable at call site), or 'anthropic/claude-haiku-4-5' (Vercel AI SDK convention; both separators accepted). If neither provides a model, the SDK throws CompresrError("model is required …").

Three call shapes

messages.create duck-types Anthropic.Message, chat.completions.create duck-types OpenAI.Chat.Completions.ChatCompletion, and run returns a native NormalizedResult (.text, .toolUses, .citations, .stopReason, .usage).

TypeScript facades are async by default; there are no acreate / arun variants. The Python SDK exposes acreate and arun.

Web search: WebSearchTool

Three providers ship in the box: Tavily, Brave, and AgentCore (Amazon Bedrock via MCP). All three factories are async and return a LangChain.js StructuredToolInterface; their output flows through compresrToolMiddleware automatically.

Provider reference

Tavily (WebSearchTool.tavily) — install @langchain/tavily. apiKey is passed to the underlying LangChain tool; there is no SDK-side env fallback in the factory itself (the peer package may resolve TAVILY_API_KEY on its own). Supports allowedDomains / blockedDomains natively. Throws CompresrError('missing_peer_dependency') if @langchain/tavily isn't installed.

Brave (WebSearchTool.brave) — install @langchain/community. Reads apiKey, then BRAVE_SEARCH_API_KEY, then BRAVE_API_KEY. Throws CompresrError('missing_api_key') if none of the three are set. allowedDomains / blockedDomains are not supported by Brave (Goggles-based filtering is out of scope). Throws CompresrError('missing_peer_dependency') if @langchain/community isn't installed.

AgentCore (WebSearchTool.agentcore) — install @modelcontextprotocol/sdk. Talks to an Amazon Bedrock AgentCore gateway over MCP streamable-HTTP, authenticated via a Cognito OAuth 2.0 client-credentials handshake. Bearer tokens are cached; a 401 triggers one automatic re-mint. maxResults is clamped to 1..25. gatewayUrl and cognitoTokenUrl must be https:// — the factory throws CompresrError('invalid_config') on plaintext URLs to avoid leaking credentials. allowedDomains / blockedDomains are accepted for signature parity but silently ignored — use Tavily for domain filtering.

AgentCore config resolves per field with precedence explicit option → AgentCore-namespaced env → short env. If any field is unresolved, throws CompresrError('missing_config') listing every missing field:

createWebSearchTool — discriminated-union factory

For code that picks a provider dynamically, createWebSearchTool(provider, options) is a typed overload set. Each overload returns Promise<WebSearchToolInstance>; an unknown provider string throws CompresrError('invalid_provider').

Bring your own tool

Any function wrapped with LangChain.js's tool({...}) works. The string return value is compressed before the LLM sees it.

Streaming isn't on the agent layer yet: client.messages.stream(...) / client.chat.completions.stream(...) throw a CompresrError with code === 'not_implemented'. The compression-API stream (compressStream) is unaffected.

Research: client.research

When constructed with llm, the client also exposes client.research, a multi-step search-and-summarize loop that runs a web-search tool for you, compresses each snippet before it enters the LLM's context, and returns a structured result with citations. client.research.run(question) runs the full loop (up to maxSteps); client.research.search(question) is the same loop capped at 2 steps for quick lookups.

Accessing client.research when llm was not passed throws CompresrError('missing_llm') — the facade needs a chat model to reason about search results.

ResearchResult fields: answer: string, explanation: string, confidence: number | null, text: string, citations: Citation[], trajectory: Step[], usage: ResearchUsage (input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, calls, search_calls — all numbers, snake_case), raw: unknown (the raw provider response). Each research Citation is { url: string; title?: string; snippet?: string } — distinct from the Citation on NormalizedResult (.citedText, .providerMetadata), which the run / messages / chat.completions surfaces return.

Per-call LLM knobs

Forwarded to the underlying chat model: temperature, topP, topK, maxTokens, maxOutputTokens, stop, stopSequences, presencePenalty, frequencyPenalty, seed, logprobs, topLogprobs. Anything else is silently dropped.

Compression knobs: compression: { ... }

Set at client construction. Applies to every tool-output compression the middleware fires. The model-routing keys mirror compress() — compressionModelName picks the backbone, and the compression-shaping keys forward through to the same /compress/question-specific/ endpoint.

Shared keys (accepted regardless of compressionModelName):

The middleware policy doesn't expose the dynamic* latte_v2-only knobs. If you need adaptive ratio selection on tool outputs, call client.compress(...) directly with dynamic: true instead of routing through the middleware.

7. Async

8. Errors & types

Every Compresr error inherits from CompresrError. Catch the base for a single handler; catch subclasses when recovery differs. Every subclass carries a stable code string and, where relevant, structured attributes you can branch on (e.g. err.retryAfter, err.creditsRemaining, err.availableModels) instead of parsing prose.

Network/timeout failures throw ConnectionError and TimeoutError respectively (not the base CompresrError); code that branches on err.code === 'connection_error' will match them.