TypeScript SDK Quickstart
Install and use the CoreValue TypeScript SDK to wrap LLM calls with FinOps metadata in minutes.
TypeScript SDK Quickstart
Get started with @cova/gateway — the thin header helper that surfaces per-call FinOps metadata from CoreValue Gateway.
Tier: The SDK is free and open source. Gateway access available on all tiers.
Install
npm install @cova/gatewaybuildHeaders
Build Cova-* request headers for user tracking, properties, and fallback chains.
import { buildHeaders } from "@cova/gateway";
const headers = buildHeaders({
userId: "user_123",
promptId: "prompt_abc",
properties: { feature: "search", team: "growth" },
fallbacks: ["gpt-4o", "claude-3-5-sonnet", "llama-3.3-70b"],
});Validation: userId and promptId must match [a-zA-Z0-9_\-:.] (max 256 chars).
Property names must match [a-zA-Z0-9_] (max 64 chars). Values max 256 chars.
Fallbacks max 5 models. Invalid input throws.
wrap (Non-Streaming)
Parse Cova-* response headers into typed CovaResponse.
import OpenAI from "openai";
import { wrap, buildHeaders } from "@cova/gateway";
const client = new OpenAI({
apiKey: "sk-cova-...",
baseURL: "https://gateway.corevalue.dev/v1",
});
const response = await client.chat.completions.create({
model: "gpt-4o",
messages: [{ role: "user", content: "Hello" }],
extraHeaders: buildHeaders({ userId: "user_123" }),
});
const covaResponse = wrap(response, response.headers);
console.log(covaResponse.gateway.requestId);
console.log(covaResponse.gateway.provider);
console.log(covaResponse.gateway.model);
console.log(covaResponse.gateway.status);
console.log(covaResponse.gateway.requestCost);
console.log(covaResponse.gateway.estimatedCost);
console.log(covaResponse.gateway.creditsRemaining);
console.log(covaResponse.gateway.gatewayMode);fetchNative (Native Format)
Call a native-format endpoint (Anthropic, Google) and extract FinOps metadata.
import { fetchNative, buildHeaders } from "@cova/gateway";
const { response, gateway } = await fetchNative(
"https://gateway.corevalue.dev/v1/messages",
{
method: "POST",
headers: {
"Authorization": "Bearer sk-cova-...",
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "claude-3-5-sonnet",
messages: [{ role: "user", content: "Hello" }],
max_tokens: 1024,
}),
cova: { userId: "user_123" },
}
);
console.log(gateway.requestId);
console.log(gateway.provider);
console.log(gateway.requestCost);
console.log(gateway.creditsRemaining);CovaGatewayMeta Fields
| Field | Type | Source |
|---|---|---|
requestId | string | Cova-Id header |
provider | string | Cova-Provider header |
model | string | Cova-Model header |
status | "success" | "error" | Cova-Status header |
requestCost | number? | Cova-Request-Cost |
estimatedCost | number? | Cova-Request-Cost-Estimate |
creditsRemaining | number? | Cova-Credits-Remaining |
gatewayMode | "passthrough" | "translated"? | Cova-Gateway-Mode |
translationWarning | string? | Cova-Translation-Warning |
See stream-chat.mdx for streaming, fetch-native.mdx for native format, and per-call-finops-metadata.mdx for metadata details.