@volter/twin-xai 0.1.0

package/src/xai-types.ts

@@ -0,0 +1,111 @@
+// Shared wire-shape types for the xAI (Grok) API surface. These mirror the real vendor JSON
+// shapes (not any SDK's internal types — the twin never imports an SDK at runtime; the real
+// `@ai-sdk/xai` provider is exercised only in *.test.ts). xAI's chat surface is OpenAI-chat-
+// compatible with xAI-specific deltas (Live Search citations, reasoning_content, deferred
+// completions, the {code, error} error envelope), and those deltas are modeled here explicitly.
+
+// ── Chat Completions (OpenAI-compatible + xAI deltas) ───────────────────────────────────
+/** A chat message param as the caller sends it (content is a string OR a content-part array). */
+export type ChatMessageParam = {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content?: string | Array<Record<string, unknown>> | null;
+  name?: string;
+  tool_calls?: ChatToolCall[];
+  tool_call_id?: string;
+};
+
+/** A function tool_call inside an assistant message (faithful shape). */
+export type ChatToolCall = {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+};
+
+/** xAI reports token detail objects inside `usage` (prompt_tokens_details with text/audio/
+ *  image/cached splits; completion_tokens_details with reasoning tokens), plus the Live Search
+ *  `num_sources_used` counter. Deterministic in the twin. */
+export type ChatUsage = {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  prompt_tokens_details: { text_tokens: number; audio_tokens: number; image_tokens: number; cached_tokens: number };
+  completion_tokens_details: {
+    reasoning_tokens: number;
+    audio_tokens: number;
+    accepted_prediction_tokens: number;
+    rejected_prediction_tokens: number;
+  };
+  num_sources_used: number;
+};
+
+export type ChatChoice = {
+  index: number;
+  message: {
+    role: 'assistant';
+    content: string | null;
+    /** xAI delta: grok-3-mini exposes its chain-of-thought here (the twin's is a labeled stub);
+     *  grok-4-family reasoning models spend reasoning tokens but never expose the content. */
+    reasoning_content?: string;
+    tool_calls?: ChatToolCall[];
+    refusal?: null;
+  };
+  logprobs: null;
+  finish_reason: 'stop' | 'length' | 'tool_calls' | 'content_filter';
+};
+
+/** The unary chat.completion response envelope (faithful shape; xAI ids are UUID-formatted). */
+export type ChatCompletion = {
+  id: string;
+  object: 'chat.completion';
+  created: number;
+  model: string;
+  choices: ChatChoice[];
+  usage: ChatUsage;
+  system_fingerprint: string;
+  /** Live Search: the source URLs consulted (deterministic labeled stubs in the twin). Present
+   *  only when search ran and return_citations was not disabled. */
+  citations?: string[];
+};
+
+// ── Legacy completions (POST /v1/completions) ───────────────────────────────────────────
+export type TextCompletion = {
+  id: string;
+  object: 'text_completion';
+  created: number;
+  model: string;
+  choices: Array<{ text: string; index: number; logprobs: null; finish_reason: 'stop' | 'length' }>;
+  usage: ChatUsage;
+  system_fingerprint: string;
+};
+
+// ── Anthropic-compatible Messages (POST /v1/messages) ───────────────────────────────────
+export type MessagesContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; id: string; name: string; input: Record<string, unknown> };
+
+export type MessagesResponse = {
+  id: string;
+  type: 'message';
+  role: 'assistant';
+  model: string;
+  content: MessagesContentBlock[];
+  stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use';
+  stop_sequence: string | null;
+  usage: { input_tokens: number; output_tokens: number };
+};
+
+// ── Errors ──────────────────────────────────────────────────────────────────────────────
+/** The xAI error envelope. Unlike OpenAI's nested `{ error: {...} }`, xAI's REST layer is a
+ *  gRPC transcoding and returns TWO FLAT STRINGS: `code` (a gRPC status description, e.g.
+ *  "Client specified an invalid argument") and `error` (the human message). The real
+ *  `@ai-sdk/xai` provider parses exactly this shape. */
+export type XaiError = { code: string; error: string };
+
+// ── Streaming ───────────────────────────────────────────────────────────────────────────
+/** A single Server-Sent Event the streaming path emits (collected, never socketed in tests).
+ *  `data` is the JSON payload; `[DONE]` is signalled with `done: true` (no data object). */
+export type SseEvent = { data?: Record<string, unknown>; done?: boolean };
+
+/** A sink the streaming path writes events into (an injected collector in tests / a real
+ *  HTTP SSE writer in the server). NO real sockets or setTimeout in the handler. */
+export type SseSink = (event: SseEvent) => void;