@volter/twin-moonshot 0.1.0

package/src/moonshot-types.ts

@@ -0,0 +1,225 @@
+// Shared wire-shape types for the Moonshot (Kimi) API surface, transcribed from Moonshot's own
+// OpenAPI 3.1.0 document (https://platform.kimi.ai/docs/openapi.json, read 2026-09-16) — the
+// first-party artifact, not an SDK's internal types (no official Moonshot SDK exists; clients
+// are the standard `openai` / `anthropic` SDKs pointed at Moonshot's base URLs, so THIS document
+// is the only generated contract).
+//
+// MOONSHOT IS NOT OPENAI, and the differences below are load-bearing:
+//   • THREE inference protocols share one host: OpenAI-compatible `/v1/chat/completions` +
+//     `/v1/responses`, and an Anthropic-compatible `/anthropic/v1/messages` whose envelope,
+//     content blocks and SSE event grammar are Anthropic's, not OpenAI's;
+//   • chat responses carry `reasoning_content` (thinking mode) — not Groq's `reasoning`, not
+//     OpenAI's `refusal`;
+//   • `usage` carries `cached_tokens` (Moonshot's automatic context caching);
+//   • the error envelope is `{ error: { message, type, code? } }` (ErrorResponse schema);
+//   • the Messages surface answers `{ type:'error', error:{type,message}, request_id? }`
+//     (MessagesErrorResponse schema) — a DIFFERENT envelope on the same host.
+
+// ── Chat Completions (/v1/chat/completions) ─────────────────────────────────────────────
+/** A chat message param as the caller sends it (Message schema). Content is a string OR a
+ *  content-part array (text / image_url / video_url — Moonshot's multimodal form). */
+export type MoonshotMessageParam = {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content?: string | Array<Record<string, unknown>> | null;
+  name?: string;
+  /** Partial Mode: set `partial: true` on the last ASSISTANT message to continue it. */
+  partial?: boolean;
+  tool_calls?: MoonshotToolCall[];
+  tool_call_id?: string;
+  /** kimi-k3's dynamic tool loading message: role 'system' with `tools` and NO content. */
+  tools?: unknown[];
+};
+
+/** A function tool_call (faithful shape). */
+export type MoonshotToolCall = {
+  id: string;
+  type: 'function';
+  function: { name: string; arguments: string };
+};
+
+/** The chat `usage` object: token counts plus Moonshot's automatic context-cache split. */
+export type MoonshotUsage = {
+  prompt_tokens: number;
+  completion_tokens: number;
+  total_tokens: number;
+  /** Tokens served from the automatic context cache (>256 prompt tokens to hit). */
+  cached_tokens?: number;
+};
+
+/** The assistant message Moonshot returns. `reasoning_content` is present when thinking mode
+ *  is enabled (kimi-k3 always; kimi-k2.6/k2.7-code when `thinking.type` is 'enabled'). */
+export type MoonshotAssistantMessage = {
+  role: 'assistant';
+  content: string | null;
+  tool_calls?: MoonshotToolCall[];
+  reasoning_content?: string | null;
+};
+
+export type MoonshotChoice = {
+  index: number;
+  message: MoonshotAssistantMessage;
+  logprobs?: unknown;
+  finish_reason: 'stop' | 'length' | 'tool_calls';
+};
+
+/** The unary chat.completion response envelope (faithful shape). */
+export type MoonshotChatCompletion = {
+  id: string;
+  object: 'chat.completion';
+  created: number;
+  model: string;
+  choices: MoonshotChoice[];
+  usage: MoonshotUsage;
+};
+
+/** A streaming chat chunk (ChatCompletionChunk schema). */
+export type MoonshotChatChunk = {
+  id: string;
+  object: 'chat.completion.chunk';
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    delta: {
+      role?: string;
+      content?: string;
+      reasoning_content?: string;
+      tool_calls?: Array<{ index?: number; id?: string; type?: 'function'; function?: { name?: string; arguments?: string } }>;
+    };
+    finish_reason: 'stop' | 'length' | 'tool_calls' | null;
+    usage: MoonshotUsage | null;
+  }>;
+  /** The FINAL chunk carries the whole usage object (stream_options.include_usage / Moonshot's
+   *  documented final-chunk usage); ordinary chunks carry null. */
+  usage?: MoonshotUsage | null;
+};
+
+// ── Models ──────────────────────────────────────────────────────────────────────────────
+/** The served model object (OpenAI-shaped; Moonshot's /v1/models rows). */
+export type MoonshotModelObject = {
+  id: string;
+  object: 'model';
+  created: number;
+  owned_by: string;
+};
+
+// ── Files ───────────────────────────────────────────────────────────────────────────────
+/** File purposes — a CLOSED documented set (FileObject schema). */
+export const FILE_PURPOSES = ['file-extract', 'image', 'video', 'batch'] as const;
+export type MoonshotFilePurpose = (typeof FILE_PURPOSES)[number];
+
+export type MoonshotFile = {
+  id: string;
+  object: 'file';
+  bytes: number;
+  created_at: number;
+  filename: string;
+  purpose: MoonshotFilePurpose;
+  status: string;
+  status_details?: string;
+};
+
+// ── Batches ─────────────────────────────────────────────────────────────────────────────
+export type MoonshotBatchCounts = { completed: number; failed: number; total: number };
+
+export type MoonshotBatch = {
+  id: string;
+  object: 'batch';
+  endpoint: string;
+  input_file_id: string;
+  completion_window: string;
+  status: 'validating' | 'failed' | 'in_progress' | 'finalizing' | 'completed' | 'expired' | 'cancelling' | 'cancelled';
+  output_file_id: string | null;
+  error_file_id: string | null;
+  created_at: number;
+  in_progress_at: number | null;
+  expires_at: number | null;
+  finalizing_at: number | null;
+  completed_at: number | null;
+  failed_at: number | null;
+  cancelling_at: number | null;
+  cancelled_at: number | null;
+  request_counts: MoonshotBatchCounts;
+  metadata: Record<string, string> | null;
+};
+
+// ── Errors ──────────────────────────────────────────────────────────────────────────────
+/**
+ * Moonshot's OpenAI-surface error envelope (ErrorResponse schema): `error.message` REQUIRED,
+ * `type` and `code` optional. The `type` values are Moonshot's documented error-code page
+ * (platform.kimi.ai/docs/api/errors, read 2026-09-16) — see moonshot-twin.ts for the mapping.
+ */
+export type MoonshotError = {
+  error: {
+    message: string;
+    type?: string;
+    code?: string;
+  };
+};
+
+// ── Anthropic-compatible Messages (/anthropic/v1/messages) ──────────────────────────────
+/** A Messages content block the RESPONSE emits, ordered thinking → text → tool_use. */
+export type MoonshotMessagesBlock =
+  | { type: 'thinking'; thinking: string; signature?: string }
+  | { type: 'text'; text: string }
+  | { type: 'tool_use'; id: string; name: string; input: Record<string, unknown> };
+
+export type MoonshotMessagesResponse = {
+  id: string;
+  type: 'message';
+  role: 'assistant';
+  model: string;
+  content: MoonshotMessagesBlock[];
+  stop_reason: 'end_turn' | 'max_tokens' | 'stop_sequence' | 'tool_use' | 'refusal' | null;
+  stop_sequence: string | null;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+};
+
+/** A Messages SSE event. `data` is the JSON payload; there is no [DONE] sentinel — the stream
+ *  ends after `message_stop` (Anthropic's grammar, which this surface follows). */
+export type MessagesSseEvent = { event?: string; data?: Record<string, unknown>; done?: boolean };
+
+// ── Responses (/v1/responses) ───────────────────────────────────────────────────────────
+/** An output item, ordered web_search_call → reasoning → message → tool calls. */
+export type MoonshotResponsesOutputItem =
+  | { type: 'reasoning'; id: string; summary: Array<{ type: 'summary_text'; text: string }>; status?: 'completed' }
+  | { type: 'message'; id: string; role: 'assistant'; status: 'completed'; content: Array<{ type: 'output_text'; text: string; annotations: unknown[] }> }
+  | { type: 'function_call'; id: string; call_id: string; name: string; arguments: string; status?: 'completed' }
+  | { type: 'custom_tool_call'; id: string; call_id: string; name: string; input: string }
+  | { type: 'web_search_call'; id: string; status: 'completed' };
+
+export type MoonshotResponsesUsage = {
+  input_tokens: number;
+  input_tokens_details?: { cached_tokens: number; cache_write_tokens: number };
+  output_tokens: number;
+  output_tokens_details?: { reasoning_tokens: number };
+  total_tokens: number;
+};
+
+export type MoonshotResponsesResponse = {
+  id: string;
+  object: 'response';
+  created_at: number;
+  completed_at: number | null;
+  status: 'in_progress' | 'completed' | 'incomplete' | 'failed';
+  model: string;
+  output: MoonshotResponsesOutputItem[];
+  usage: MoonshotResponsesUsage | null;
+  incomplete_details: { reason: 'max_output_tokens' | 'content_filter' } | null;
+  error: { code: string; message: string } | null;
+  store: false;
+};
+
+// ── Streaming ───────────────────────────────────────────────────────────────────────────
+/** A single Server-Sent Event the OpenAI-compatible streaming paths emit. `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;