@volcengine/ark-runtime 1.0.0

package/src/types/http-request-error.ts

@@ -0,0 +1,34 @@
+export type HttpRequestErrorName =
+  | "Exception"
+  | "ApiException"
+  | "NetworkError";
+
+/**
+ * HttpRequestError
+ * Standardized error class for HTTP request failures
+ */
+export class HttpRequestError extends Error {
+  public status?: number;
+  public data?: any;
+  public originalError?: any;
+  public override name: HttpRequestErrorName;
+
+  constructor(
+    name: HttpRequestErrorName = "Exception",
+    message: string,
+    status?: number,
+    data?: any,
+    originalError?: any
+  ) {
+    super(message);
+    this.name = name;
+    this.status = status;
+    this.data = data;
+    this.originalError = originalError;
+
+    // Maintain proper stack trace
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, HttpRequestError);
+    }
+  }
+}

package/src/types/images.ts

@@ -0,0 +1,102 @@
+import type { HttpHeaders } from "./common";
+
+// Constants
+export const GenerateImagesResponseFormatBase64 = "b64_json";
+export const GenerateImagesResponseFormatURL = "url";
+export const GenerateImagesSizeAdaptive = "adaptive";
+
+// Optimize prompt
+export type OptimizePromptThinking = "auto" | "enabled" | "disabled";
+export type OptimizePromptMode = "standard" | "fast";
+
+// Sequential image generation
+export type SequentialImageGeneration = "auto" | "disabled";
+
+// Image stream event types
+export const ImageGenerationStreamEventPartialSucceeded =
+  "image_generation.partial_succeeded";
+export const ImageGenerationStreamEventPartialFailed =
+  "image_generation.partial_failed";
+export const ImageGenerationStreamEventCompleted =
+  "image_generation.completed";
+
+// Output format
+export type OutputFormat = "jpeg" | "png";
+
+// Content generation tool
+export type ContentGenerationToolType = "web_search";
+
+export interface ContentGenerationTool {
+  type: ContentGenerationToolType;
+}
+
+export interface ToolUsage {
+  web_search?: number;
+}
+
+export interface OptimizePromptOptions {
+  thinking?: OptimizePromptThinking;
+  mode?: OptimizePromptMode;
+}
+
+export interface SequentialImageGenerationOptions {
+  max_images?: number;
+}
+
+export interface Image {
+  url?: string;
+  b64_json?: string;
+  size: string;
+}
+
+export interface GenerateImagesUsage {
+  generated_images: number;
+  output_tokens: number;
+  total_tokens: number;
+  tool_usage?: ToolUsage;
+}
+
+export interface GenerateImagesError {
+  code: string;
+  message: string;
+}
+
+export interface GenerateImagesRequest {
+  model: string;
+  prompt: string;
+  image?: string | string[];
+  response_format?: string;
+  seed?: number;
+  guidance_scale?: number;
+  size?: string;
+  watermark?: boolean;
+  optimize_prompt?: boolean;
+  optimize_prompt_options?: OptimizePromptOptions;
+  sequential_image_generation?: SequentialImageGeneration;
+  sequential_image_generation_options?: SequentialImageGenerationOptions;
+  tools?: ContentGenerationTool[];
+  output_format?: OutputFormat;
+}
+
+export interface ImagesResponse {
+  model: string;
+  created: number;
+  data: Image[];
+  usage?: GenerateImagesUsage;
+  error?: GenerateImagesError;
+  tools?: ContentGenerationTool[];
+  headers?: HttpHeaders;
+}
+
+export interface ImagesStreamResponse {
+  type: string;
+  model: string;
+  created: number;
+  image_index: number;
+  url?: string;
+  b64_json?: string;
+  size: string;
+  usage?: GenerateImagesUsage;
+  error?: GenerateImagesError;
+  tools?: ContentGenerationTool[];
+}

package/src/types/index.ts

@@ -0,0 +1,12 @@
+export * from "./common";
+export * from "./error";
+export * from "./chat-completion";
+export * from "./bot";
+export * from "./embeddings";
+export * from "./images";
+export * from "./tokenization";
+export * from "./context";
+export * from "./content-generation";
+export * from "./file";
+export * from "./multimodal-embedding";
+export * as responses from "./responses";

package/src/types/multimodal-embedding.ts

@@ -0,0 +1,67 @@
+import type { HttpHeaders } from "./common";
+import type { EmbeddingEncodingFormat } from "./embeddings";
+
+export type MultiModalEmbeddingInputType = "text" | "image_url" | "video_url";
+
+export type SparseEmbeddingInputType = "enabled" | "disabled";
+
+export interface MultimodalEmbeddingImageURL {
+  url: string;
+}
+
+export interface MultimodalEmbeddingVideoURL {
+  url: string;
+  fps?: number;
+}
+
+export interface MultimodalEmbeddingInput {
+  type: MultiModalEmbeddingInputType;
+  text?: string;
+  image_url?: MultimodalEmbeddingImageURL;
+  video_url?: MultimodalEmbeddingVideoURL;
+}
+
+export interface SparseEmbeddingInput {
+  type: SparseEmbeddingInputType;
+}
+
+export interface SparseEmbedding {
+  index: number;
+  value: number;
+}
+
+export interface MultiModalEmbeddingRequest {
+  input: MultimodalEmbeddingInput[];
+  model: string;
+  encoding_format?: EmbeddingEncodingFormat;
+  dimensions?: number;
+  sparse_embedding?: SparseEmbeddingInput;
+  instructions?: string;
+}
+
+export interface MultimodalEmbedding {
+  embedding: number[];
+  sparse_embedding?: SparseEmbedding[];
+  object: string;
+}
+
+export interface MultimodalEmbeddingPromptTokensDetail {
+  text_tokens: number;
+  image_tokens: number;
+}
+
+export interface MultimodalEmbeddingUsage {
+  prompt_tokens: number;
+  total_tokens: number;
+  prompt_tokens_details: MultimodalEmbeddingPromptTokensDetail;
+}
+
+export interface MultimodalEmbeddingResponse {
+  id: string;
+  model: string;
+  created: number;
+  object: string;
+  data: MultimodalEmbedding;
+  usage: MultimodalEmbeddingUsage;
+  headers?: HttpHeaders;
+}

package/src/types/responses/enums.ts

@@ -0,0 +1,163 @@
+// All enums are TS string literal unions (replacing Go protobuf int32 enums).
+// The wire format is JSON strings, so string literals are the natural TS representation.
+
+export type ResponsesServiceTier = "auto" | "default";
+export type ResponsesTruncation = "auto" | "disabled";
+export type AnnotationType = "url_citation" | "doc_citation";
+export type ResponseImageProcessType = "point" | "grounding" | "rotate" | "zoom";
+export type ResponseDoubaoAppFeatureType = "enabled" | "disabled";
+
+export type ItemType =
+  | "message"
+  | "function_call"
+  | "function_call_output"
+  | "reasoning"
+  | "item_reference"
+  | "transcription"
+  | "web_search_call"
+  | "image_process"
+  | "mcp_approval_request"
+  | "mcp_approval_response"
+  | "mcp_list_tools"
+  | "mcp_call"
+  | "knowledge_search_call"
+  | "doubao_app_call";
+
+export type DoubaoAppBlockType =
+  | "output_text"
+  | "reasoning_text"
+  | "search"
+  | "reasoning_search";
+
+export type MessageRole = "user" | "system" | "developer" | "assistant";
+
+export type ContentItemImageDetail = "auto" | "high" | "low";
+
+export type ContentItemType =
+  | "input_text"
+  | "input_image"
+  | "input_video"
+  | "output_text"
+  | "summary_text"
+  | "transcription_text"
+  | "input_audio"
+  | "input_file";
+
+export type ItemStatus =
+  | "in_progress"
+  | "completed"
+  | "incomplete"
+  | "searching"
+  | "failed";
+
+export type ResponseStatus =
+  | "in_progress"
+  | "completed"
+  | "incomplete"
+  | "failed";
+
+export type ThinkingType = "auto" | "disabled" | "enabled";
+
+export type TextType = "text" | "json_object" | "json_schema";
+
+export type ToolChoiceMode = "auto" | "none" | "required";
+
+export type ToolType =
+  | "function"
+  | "web_search_preview"
+  | "web_search"
+  | "image_process"
+  | "mcp"
+  | "knowledge_search"
+  | "doubao_app";
+
+export type UserLocationType = "approximate";
+
+export type ObjectType = "response" | "list";
+
+export type ReasoningEffort = "minimal" | "low" | "medium" | "high";
+
+export type IncludeType = "image_url";
+
+export type CacheType = "disabled" | "enabled";
+
+export type ChunkingStrategyType = "server_vad";
+
+export type ActionType = "search";
+
+export type SourceType = "toutiao" | "douyin" | "moji" | "search_engine";
+
+export type ApprovalMode = "always" | "never";
+
+export type EventType =
+  | "response.created"
+  | "response.in_progress"
+  | "response.completed"
+  | "response.failed"
+  | "response.incomplete"
+  | "response.output_item.added"
+  | "response.output_item.done"
+  | "response.content_part.added"
+  | "response.content_part.done"
+  | "response.output_text.delta"
+  | "response.output_text.done"
+  | "response.reasoning_summary_text.delta"
+  | "response.reasoning_summary_text.done"
+  | "response.reasoning_summary_part.added"
+  | "response.reasoning_summary_part.done"
+  | "response.function_call_arguments.delta"
+  | "response.function_call_arguments.done"
+  | "error"
+  | "response.transcription_part.added"
+  | "response.transcription_part.done"
+  | "response.transcription_text.delta"
+  | "response.transcription_text.done"
+  | "response.web_search_call.in_progress"
+  | "response.web_search_call.searching"
+  | "response.web_search_call.completed"
+  | "response.output_text.annotation.added"
+  | "response.image_process_call.in_progress"
+  | "response.image_process_call.progressing"
+  | "response.image_process_call.completed"
+  | "response.image_process_call.failed"
+  | "response.mcp_list_tools.in_progress"
+  | "response.mcp_list_tools.completed"
+  | "response.mcp_call.in_progress"
+  | "response.mcp_call.arguments_delta"
+  | "response.mcp_call.arguments_done"
+  | "response.mcp_call.completed"
+  | "response.mcp_call.failed"
+  | "response.mcp_approval_request"
+  | "response.knowledge_search_call.in_progress"
+  | "response.knowledge_search_call.searching"
+  | "response.knowledge_search_call.completed"
+  | "response.knowledge_search_call.failed"
+  | "response.doubao_app_call.in_progress"
+  | "response.doubao_app_call.failed"
+  | "response.doubao_app_call.completed"
+  | "response.doubao_app_call.block.added"
+  | "response.doubao_app_call.block.done"
+  | "response.doubao_app_call.reasoning_text.delta"
+  | "response.doubao_app_call.reasoning_text.done"
+  | "response.doubao_app_call.output_text.delta"
+  | "response.doubao_app_call.output_text.done"
+  | "response.doubao_app_call.search.in_progress"
+  | "response.doubao_app_call.search.searching"
+  | "response.doubao_app_call.search.completed"
+  | "response.doubao_app_call.reasoning_search.in_progress"
+  | "response.doubao_app_call.reasoning_search.searching"
+  | "response.doubao_app_call.reasoning_search.completed";
+
+// Constants for convenience (matching Go's MessageRole_user etc.)
+export const MessageRole_user: MessageRole = "user";
+export const MessageRole_system: MessageRole = "system";
+export const MessageRole_developer: MessageRole = "developer";
+export const MessageRole_assistant: MessageRole = "assistant";
+
+export const ContentItemType_input_text: ContentItemType = "input_text";
+export const ContentItemType_input_image: ContentItemType = "input_image";
+export const ContentItemType_input_video: ContentItemType = "input_video";
+export const ContentItemType_input_audio: ContentItemType = "input_audio";
+export const ContentItemType_input_file: ContentItemType = "input_file";
+export const ContentItemType_output_text: ContentItemType = "output_text";
+export const ContentItemType_summary_text: ContentItemType = "summary_text";

package/src/types/responses/helpers.ts

@@ -0,0 +1,67 @@
+import type { Event, EventType } from "./types";
+
+/**
+ * Get the event type string from an Event object.
+ * Matches Go's `(*Event).GetEventType()`.
+ */
+export function getEventType(event: Event | null | undefined): EventType | "" {
+  if (!event) return "";
+  return event.type ?? "";
+}
+
+/**
+ * Check if an event is a "delta" event (streaming partial content).
+ * Matches Go's `(*Event).IsDelta()`.
+ */
+export function isDelta(event: Event): boolean {
+  const t = event.type;
+  return (
+    t === "response.output_text.delta" ||
+    t === "response.reasoning_summary_text.delta" ||
+    t === "response.function_call_arguments.delta" ||
+    t === "response.transcription_text.delta" ||
+    t === "response.output_text.annotation.added" ||
+    t === "response.web_search_call.in_progress" ||
+    t === "response.web_search_call.searching" ||
+    t === "response.web_search_call.completed" ||
+    t === "response.image_process_call.in_progress" ||
+    t === "response.image_process_call.completed" ||
+    t === "response.mcp_list_tools.completed" ||
+    t === "response.mcp_call.in_progress" ||
+    t === "response.mcp_call.arguments_delta" ||
+    t === "response.mcp_call.arguments_done" ||
+    t === "response.mcp_call.completed" ||
+    t === "response.mcp_call.failed" ||
+    t === "response.knowledge_search_call.in_progress" ||
+    t === "response.knowledge_search_call.searching" ||
+    t === "response.knowledge_search_call.completed" ||
+    t === "response.knowledge_search_call.failed"
+  );
+}
+
+/**
+ * Check if an event is a "delta done" event (end of streaming partial).
+ * Matches Go's `(*Event).IsDeltaDone()`.
+ */
+export function isDeltaDone(event: Event): boolean {
+  const t = event.type;
+  return (
+    t === "response.output_text.done" ||
+    t === "response.reasoning_summary_text.done" ||
+    t === "response.function_call_arguments.done" ||
+    t === "response.transcription_text.done"
+  );
+}
+
+/**
+ * Check if the response generation is complete (success, fail, or incomplete).
+ * Matches Go's `(*Event).IsResponseDone()`.
+ */
+export function isResponseDone(event: Event): boolean {
+  const t = event.type;
+  return (
+    t === "response.completed" ||
+    t === "response.failed" ||
+    t === "response.incomplete"
+  );
+}

package/src/types/responses/index.ts

@@ -0,0 +1,3 @@
+export * from "./enums";
+export * from "./types";
+export * from "./helpers";