@elkpi/oxa
Pure, in-process TypeScript protocol conversion for OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages. The package does not make network requests, choose providers, retry calls, or manage authentication.
Install
npm install @elkpi/oxa
oxa is ESM-only, supports Node.js 20 and later and Web runtimes, and has no runtime dependencies.
Convert through the IR
Each protocol face converts only to or from the face-neutral intermediate representation. To convert between providers, compose two operations:
import { anthropic, chatcompletions, type Loss } from "@elkpi/oxa";
const decoded = chatcompletions.decodeRequest(chatCompletionsRequest);
const encoded = anthropic.encodeRequest(decoded.value);
const losses: Loss[] = [...decoded.losses, ...encoded.losses];
const anthropicRequest = encoded.value;
Structural or lifecycle errors throw OxaError. Semantic gaps are returned
as ordered Loss[] values; they are never silently discarded.
Streaming
The face classes expose incremental Feed, Flush, Losses, and
Apply operations. Async-iterable adapters are available under the stream
namespace:
import { stream } from "@elkpi/oxa";
const decoded = stream.decodeChatCompletions(nativeChunks);
for await (const event of decoded) {
// Forward each IR event without buffering the complete stream.
}
const losses = decoded.losses();
Tool-call argument fragments and Anthropic input_json_delta.partial_json
remain opaque raw JSON text. Their spelling and fragment order are preserved.
Public entry points
The root exports common errors, losses, model mapping, and namespaces for every completed module. Equivalent focused ESM entry points are also available:
@elkpi/oxa/error@elkpi/oxa/loss@elkpi/oxa/modelmap@elkpi/oxa/json@elkpi/oxa/ir@elkpi/oxa/sse@elkpi/oxa/stream@elkpi/oxa/openai/chatcompletions@elkpi/oxa/openai/responses@elkpi/oxa/anthropic/messages
The package includes declarations for the root and every public subpath.
Development and release verification
From this directory:
npm install
npm run release:check
release:check validates vectors and their manifest, generated declarations,
formatting, type safety, Node and Web behavior, tarball contents, a clean
installed consumer, and the Go reference implementation. It only verifies
release readiness and never publishes.
Contract
Conversion behavior is defined by the repository's golden vectors, structural shapes by its JSON schemas, and semantics by its specifications, in that order:
vectors/spec/schema/spec/*.md
The TypeScript implementation uses the shared 185-vector golden suite, with Node gates for each face, streaming, and Responses cross-protocol requests, including Spec 2.0 M7/M9 reasoning and usage behavior plus Spec 2.1 structured output format mapping.
Apache-2.0. See LICENSE and NOTICE.
原始 JSON 入口
各 face 导出 decodeRequestJSON(raw, options) 和 decodeResponseJSON(raw, options)；
stream decoder 支持 feedJSON(raw)。raw 入口使用 parseJson 保留原始数字 token、
对象键序和工具参数文本；对象接口也执行相同字段审计。不要用原生 JSON.parse
预先丢掉大整数精度。该能力自 v2.1.1 起已发布，当前 v2.2.0 源码保留支持。