@llm0ai/contracts

Shared Zod schemas, header constants, and utility types for the LLM0 gateway ecosystem.

Used by the gateway, cloud backend, and dashboard to stay in sync on request/response shapes, header names, and cost formatting — without duplicating types across repos.

Install

bun add @llm0ai/contracts
# or
npm install @llm0ai/contracts

Usage

import { ChatRequest, ChatResponse, Headers, formatUsd, LimitSpec } from "@llm0ai/contracts";

// Validate an incoming request body
const result = ChatRequest.safeParse(body);
if (!result.success) {
  return { error: result.error.flatten() };
}

// Read a response header by name
const cost = response.headers.get(Headers.COST_USD);

// Format a cost value consistently
const display = formatUsd(0.000435); // "0.000435"

What's in the package

ChatRequest / ChatResponse

Zod schemas for the OpenAI-compatible chat completions API (POST /v1/chat/completions). Also includes ChatStreamChunk for streaming responses and GatewayError for the error envelope.

import { ChatRequest, ChatResponse, ChatStreamChunk } from "@llm0ai/contracts";

Headers

Constants for every custom HTTP header the gateway sets or reads. Covers cost, token counts, rate limits, customer spend, cache status, and downgrade routing.

import { Headers } from "@llm0ai/contracts";

// Request headers
Headers.CUSTOMER_ID       // "X-Customer-ID"
Headers.CUSTOMER_TIER     // "X-Customer-Tier"
Headers.LLM0_LABEL_PREFIX // "X-LLM0-"

// Response headers
Headers.COST_USD              // "X-Cost-USD"
Headers.TOKENS_PROMPT         // "X-Tokens-Prompt"
Headers.TOKENS_COMPLETION     // "X-Tokens-Completion"
Headers.CACHE_HIT             // "X-Cache-Hit"
Headers.RATE_LIMIT_REMAINING  // "X-RateLimit-Remaining"
Headers.CUSTOMER_SPEND_TODAY  // "X-Customer-Spend-Today"
Headers.DOWNGRADED            // "X-Downgraded"
// ... and more

LimitSpec / CustomerTier / Project

Zod schemas for the customer limits and tier system.

import { LimitSpec, LimitBehavior, CustomerTier, UpsertTierPayload } from "@llm0ai/contracts";

// LimitBehavior: "block" | "downgrade" | "warn"

Utilities

import { formatUsd, parseUsd, displayUsd, extractLabels } from "@llm0ai/contracts";

formatUsd(0.000435)    // "0.000435"  — wire format (6dp)
displayUsd(1.5)        // "$1.50"     — human display (2dp)
parseUsd("0.000435")   // 0.000435   — parse wire format back to number

// Extract X-LLM0-* labels from request headers
extractLabels({ "X-LLM0-Feature": "chat", "X-LLM0-Team": "support" })
// → { feature: "chat", team: "support" }

Publishing a new version

# 1. Bump version in package.json
# 2. Build
bun run build

# 3. Publish
bun publish --access public

License

MIT