clark-platform-client-js 0.1.0

package/types/index.d.ts

@@ -0,0 +1,293 @@
+// Hand-written declaration file for editor/TS-consumer support.
+// The shipped runtime is plain JavaScript (src/*.js) with JSDoc type hints —
+// this file is not generated by a build step and is not required to consume
+// the package from JavaScript; it exists purely for editors/TS projects that
+// want IntelliSense and type-checking against clark-platform-client-js.
+
+export type MemoryScope = "user" | "conversation";
+export type ResponseStatus = "in_progress" | "completed" | "failed";
+export type ReasoningEffort = "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export interface ClarkErrorEnvelope {
+  message: string;
+  type:
+    | "invalid_request_error"
+    | "authentication_error"
+    | "permission_error"
+    | "not_found_error"
+    | "upstream_error"
+    | "server_error"
+    | string;
+  param?: string | null;
+  code?: string;
+}
+
+export declare class ClarkApiError extends Error {
+  status: number | null;
+  type: string;
+  param: string | null;
+  code: string;
+  cause?: unknown;
+  response?: Response;
+  static fromResponse(response: Response): Promise<ClarkApiError>;
+  static fromNetworkError(cause: unknown): ClarkApiError;
+}
+
+export declare const DEFAULT_BASE_URL: string;
+export declare const DEFAULT_TIMEOUT_MS: number;
+
+export interface PublicUsageCost {
+  amount: string | null;
+  currency: string;
+  type: "estimated" | "unavailable" | string;
+}
+
+export interface PublicUsage {
+  input_tokens: number;
+  input_tokens_details: { cached_tokens: number };
+  output_tokens: number;
+  output_tokens_details: { reasoning_tokens: number };
+  total_tokens: number;
+  artifact_bytes?: number;
+  cost: PublicUsageCost;
+}
+
+export interface PublicArtifact {
+  id: string;
+  name: string;
+  kind: string;
+  role: string;
+  mime_type: string;
+  size_bytes: number;
+  summary?: string;
+  download_url: string;
+}
+
+export interface PublicResponseMetadata {
+  response_id: string;
+  conversation_id: string;
+  run_id: string;
+  status: ResponseStatus;
+  artifacts: PublicArtifact[];
+}
+
+export interface ClarkModelPricing {
+  currency: string;
+  unit: string;
+  input: number;
+  output: number;
+  cache_write?: number;
+  cache_read?: number;
+}
+
+export interface ClarkModelCapabilities {
+  public_input_modalities: string[];
+  model_input_modalities: string[];
+  output_modalities: string[];
+  features: string[];
+  public_file_upload: boolean;
+}
+
+export interface ClarkModelDetail {
+  tier_id: string;
+  label: string;
+  description: string;
+  context_window_tokens: number;
+  max_output_tokens: number;
+  pricing: ClarkModelPricing;
+  capabilities: ClarkModelCapabilities;
+  model_options?: ClarkModelEntry[];
+}
+
+export interface ClarkModelEntry {
+  id: string;
+  object: "model";
+  owned_by: string;
+  clark: ClarkModelDetail;
+}
+
+export interface ClarkModelList {
+  object: "list";
+  data: ClarkModelEntry[];
+}
+
+export type ResponseInputRole = "user" | "assistant" | string;
+
+export interface ResponseInputTextPart {
+  type: "text" | "input_text";
+  text: string;
+}
+
+export interface ResponseInputItem {
+  role?: ResponseInputRole;
+  content: string | ResponseInputTextPart[];
+}
+
+export interface CreateResponseParams {
+  model: string;
+  tierModelId?: string;
+  input: string | ResponseInputItem[];
+  conversationId?: string;
+  memoryScope?: MemoryScope;
+  previousResponseId?: string;
+  background?: boolean;
+  metadata?: Record<string, unknown>;
+  signal?: AbortSignal;
+}
+
+export interface ResponseObject {
+  id: string;
+  object: "response";
+  status: ResponseStatus;
+  created_at: number;
+  model: string;
+  previous_response_id: string | null;
+  background: boolean;
+  output: Array<Record<string, unknown>>;
+  artifacts: PublicArtifact[];
+  usage?: PublicUsage;
+  metadata?: Record<string, unknown>;
+  clark: PublicResponseMetadata;
+  error: { type: string; message: string } | null;
+}
+
+export interface ResponseStreamEvent {
+  type: string;
+  sequence_number: number;
+  [key: string]: unknown;
+}
+
+export interface ListResponseEventsOptions {
+  afterSeq?: number;
+  limit?: number;
+  types?: string[] | string;
+  signal?: AbortSignal;
+}
+
+export interface ResponseEventList {
+  object: "list";
+  data: Array<Record<string, unknown>>;
+  next_after_seq: number;
+}
+
+export declare class Responses {
+  create(params: CreateResponseParams): Promise<ResponseObject>;
+  stream(params: CreateResponseParams): AsyncGenerator<ResponseStreamEvent, void, unknown>;
+  get(responseId: string, options?: { signal?: AbortSignal }): Promise<ResponseObject>;
+  listEvents(responseId: string, options?: ListResponseEventsOptions): Promise<ResponseEventList>;
+}
+
+export declare class Models {
+  list(options?: { signal?: AbortSignal }): Promise<ClarkModelList>;
+}
+
+export interface ChatMessageTextPart {
+  type: "text";
+  text: string;
+}
+
+export interface ChatMessage {
+  role: "system" | "user" | "assistant" | "tool" | string;
+  content?: string | ChatMessageTextPart[] | null;
+  name?: string;
+  tool_call_id?: string;
+  tool_calls?: Array<Record<string, unknown>>;
+}
+
+export interface CreateChatCompletionParams {
+  model: string;
+  tierModelId?: string;
+  messages: ChatMessage[];
+  conversationId?: string;
+  memoryScope?: MemoryScope;
+  previousResponseId?: string;
+  streamOptions?: { include_usage?: boolean };
+  metadata?: Record<string, unknown>;
+  temperature?: number;
+  topP?: number;
+  maxTokens?: number;
+  stop?: string | string[];
+  signal?: AbortSignal;
+}
+
+export interface CreatePassthroughChatCompletionParams extends CreateChatCompletionParams {
+  tools?: Array<Record<string, unknown>>;
+  toolChoice?: string | Record<string, unknown>;
+  parallelToolCalls?: boolean;
+  reasoningEffort?: ReasoningEffort;
+}
+
+export interface ChatCompletionChoice {
+  index: number;
+  message: { role: "assistant"; content: string };
+  finish_reason: "stop" | "error" | "timeout" | string;
+}
+
+export interface ChatCompletionObject {
+  id: string;
+  object: "chat.completion";
+  created: number;
+  model: string;
+  choices: ChatCompletionChoice[];
+  usage?: PublicUsage;
+  clark?: PublicResponseMetadata;
+}
+
+export interface ChatCompletionChunk {
+  id: string;
+  object: "chat.completion.chunk";
+  created: number;
+  model: string;
+  choices: Array<{ index: number; delta: Record<string, unknown>; finish_reason: string | null }>;
+  usage?: PublicUsage | null;
+  clark?: PublicResponseMetadata | null;
+}
+
+export declare class ChatCompletions {
+  create(params: CreateChatCompletionParams): Promise<ChatCompletionObject>;
+  stream(params: CreateChatCompletionParams): AsyncGenerator<ChatCompletionChunk, void, unknown>;
+  createPassthrough(params: CreatePassthroughChatCompletionParams): Promise<Record<string, unknown>>;
+  streamPassthrough(
+    params: CreatePassthroughChatCompletionParams
+  ): AsyncGenerator<Record<string, unknown>, void, unknown>;
+}
+
+export interface MemoryListParams {
+  q?: string;
+  tags?: string;
+  conversationId?: string;
+  signal?: AbortSignal;
+}
+
+export interface MemoryList {
+  object: "list";
+  data: Array<Record<string, unknown>>;
+}
+
+export declare class Memories {
+  list(params?: MemoryListParams): Promise<MemoryList>;
+}
+
+export declare class Artifacts {
+  download(
+    conversationId: string,
+    artifactName: string,
+    options?: { headers?: Record<string, string>; signal?: AbortSignal }
+  ): Promise<Response>;
+}
+
+export interface ClarkClientOptions {
+  apiKey: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetchFn?: typeof fetch;
+}
+
+export declare class ClarkClient {
+  constructor(options: ClarkClientOptions);
+  models: Models;
+  responses: Responses;
+  chat: { completions: ChatCompletions };
+  memories: Memories;
+  artifacts: Artifacts;
+}