typescript-sdk

voyageai is the Fern-generated TypeScript client for the Voyage AI API, giving typed access to text embeddings, multimodal embeddings, contextualized (chunked) embeddings, and document reranking. It ships typed request/response models for every endpoint, automatic retries with exponential backoff, configurable timeouts, abortable requests, additional-header/query-param passthrough, pluggable logging, and access to raw response data via .withRawResponse(). The dual CJS/ESM build targets Node 18+, Vercel, Cloudflare Workers, Deno, Bun, and React Native, defaulting to node-fetch but using the runtime’s native fetch when available.

Beyond the generated base client, the package’s VoyageAIClient extends it with hand-written capabilities: local, offline embedding for the voyage-4-nano model using @huggingface/transformers and ONNX Runtime (no API key or network call required, with Matryoshka dimension truncation and re-normalization), a tokenize() method that works against both local and remote models, and a contextualizedEmbed() wrapper that supports both server-side auto-chunking and a configurable client-side chunkFn (with a built-in recursive, multilingual-aware text splitter) for RAG-style document chunking workflows.

What You Get

• Typed clients for embed, rerank, multimodalEmbed, and contextualizedEmbed, with full TypeScript interfaces for every request and response shape
• Local, offline embedding for voyage-4-nano via Transformers.js/ONNX Runtime — no API key or network call, with Matryoshka dimension truncation
• A tokenize() method that counts and inspects tokens for both local and remote models, mirroring the Python SDK’s tokenizer API
• Client-side and server-side chunking for contextualizedEmbed, including a built-in recursive, multilingual-aware default chunk splitter or a custom chunkFn
• Automatic retries with exponential backoff on 408/429/5xx, configurable timeouts, AbortSignal support, and .withRawResponse() for raw headers/body access
• Dual CJS/ESM builds supporting Node 18+, Vercel, Cloudflare Workers, Deno 1.25+, Bun 1.0+, and React Native

Common Use Cases

• Generating text embeddings for semantic search and RAG pipelines against Voyage’s hosted embedding models
• Running fully offline embedding generation with voyage-4-nano in edge or air-gapped environments where no API key is available
• Chunking long documents into overlapping segments for contextualized embeddings, either with the built-in splitter or a custom chunking function
• Reranking a candidate document set returned by a first-pass retriever before feeding results to an LLM
• Embedding mixed text/image inputs through the multimodal embedding endpoint for cross-modal retrieval

Under The Hood

Architecture The package layers hand-written code over Fern-generated code. src/core/ holds generated runtime plumbing (fetcher, schemas, auth, headers, URL/query building, logging); src/api/ holds generated request/response types and per-endpoint clients; src/Client.ts is the generated VoyageAIClient base exposing embed, rerank, multimodalEmbed, and contextualizedEmbed. src/extended/ExtendedClient.ts subclasses that generated client and overrides embed/contextualizedEmbed/adds tokenize, routing requests to either the remote API or a local ONNX pipeline depending on the requested model. This generated/extended split means regenerating the base client from Voyage’s API definition won’t clobber the hand-written local-inference and chunking logic, and swapping the core abstraction (the generated Client.ts) would require re-deriving the extension points ExtendedClient overrides.

Tech Stack Written in TypeScript targeting a dual CJS/ESM build via tsc against separate tsconfig.cjs.json/tsconfig.esm.json projects, with a post-build script renaming ESM output files. Runtime dependency is limited to node-fetch for environments without native fetch; @huggingface/transformers and onnxruntime-node are optional peer dependencies used only for local embedding. Biome handles linting and formatting, Vitest runs both unit and “wire” (mock-server) test projects, and the package is managed as a pnpm workspace (pnpm@10.20.0) targeting Node 18+ as well as Vercel, Cloudflare Workers, Deno, Bun, and React Native.

Code Quality Tests are split into tests/unit (auth, base64, fetcher, logging, schemas, URL helpers), tests/wire (Fern-generated request/response contract tests against a mock server), and tests/custom (hand-written tests for the extended client’s local-embedding and chunking behavior, including real image/video fixtures for multimodal cases). Errors are typed through a VoyageAIError/VoyageAITimeoutError hierarchy rather than thrown as plain objects, and CI is configured via .github/workflows/ci.yml. The generated portions of the codebase carry a header noting they’re auto-generated and shouldn’t be hand-edited, which keeps a clear boundary between reviewed hand-written code and regenerated code.

What Makes It Unique Most Fern-generated SDKs are thin, faithful wrappers around a REST API. This one adds a genuinely distinct capability on top: dispatching embed() calls for voyage-4-nano to a fully local ONNX Runtime pipeline (via Transformers.js) instead of the network, with Matryoshka-style dimension truncation and re-normalization to match the hosted API’s output contract, plus a tokenize() helper that works identically for local and remote models. contextualizedEmbed() also adds configurable client-side chunking (a recursive, multilingual-punctuation-aware splitter, or a caller-supplied function) layered onto the API’s own server-side auto-chunking option — a document-chunking convenience not present in the base generated client.