@hanzo/ai 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,486 @@
+type TokenProvider = string | (() => string | Promise<string>);
+interface ClientConfig {
+    /** Defaults to https://api.hanzo.ai (the Hanzo gateway). */
+    baseUrl?: string;
+    /** Static IAM access token (from @hanzo/iam). */
+    token?: string;
+    /** Lazy token source — preferred when tokens rotate/refresh. */
+    getToken?: () => string | Promise<string>;
+    /** Custom fetch (e.g. for tests or non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+    /** Extra headers sent on every request. */
+    headers?: Record<string, string>;
+}
+/** Joins the base URL with a `/v1/...` path. Never adds an `/api/` prefix. */
+declare function joinUrl(baseUrl: string, path: string): string;
+interface RequestOptions {
+    method?: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    /** When true, the request is sent without an Authorization header. */
+    anonymous?: boolean;
+    signal?: AbortSignal;
+    /** Force a streaming (raw Response) result; skips body parsing. */
+    stream?: boolean;
+    headers?: Record<string, string>;
+}
+/**
+ * Transport shared by every resource. Owns base-URL joining, lazy bearer-token
+ * injection, JSON encoding, and error normalization. Knows nothing about any
+ * specific endpoint.
+ */
+declare class HttpClient {
+    readonly baseUrl: string;
+    private readonly token?;
+    private readonly getToken?;
+    private readonly fetchImpl;
+    private readonly extraHeaders;
+    constructor(config: ClientConfig);
+    private resolveToken;
+    private buildHeaders;
+    /** Issues a request and returns the raw Response (used for streaming). */
+    raw(opts: RequestOptions): Promise<Response>;
+    /** Issues a request and parses a JSON body (no envelope unwrapping). */
+    json<T>(opts: RequestOptions): Promise<T>;
+    /**
+     * Issues a request to a Casdoor/Casibase CRUD endpoint and unwraps the
+     * { status, msg, data } envelope, throwing on status "error".
+     */
+    enveloped<T>(opts: RequestOptions): Promise<T>;
+}
+
+type Role = "system" | "user" | "assistant" | "tool";
+/** Casdoor/Casibase response envelope used by all CRUD endpoints. */
+interface Envelope<T = unknown> {
+    status: "ok" | "error";
+    msg: string;
+    data: T;
+    data2?: unknown;
+}
+interface ChatCompletionContentPartText {
+    type: "text";
+    text: string;
+}
+interface ChatCompletionContentPartImage {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+}
+type ChatCompletionContentPart = ChatCompletionContentPartText | ChatCompletionContentPartImage;
+interface ChatCompletionMessage {
+    role: Role;
+    content?: string | ChatCompletionContentPart[];
+    name?: string;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
+}
+interface FunctionDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+interface Tool {
+    type: "function";
+    function: FunctionDefinition;
+}
+type ToolChoice = "none" | "auto" | "required" | {
+    type: "function";
+    function: {
+        name: string;
+    };
+};
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+interface ChatCompletionCreateParams {
+    model: string;
+    messages: ChatCompletionMessage[];
+    stream?: boolean;
+    temperature?: number;
+    top_p?: number;
+    n?: number;
+    stop?: string | string[];
+    max_tokens?: number;
+    presence_penalty?: number;
+    frequency_penalty?: number;
+    user?: string;
+    tools?: Tool[];
+    tool_choice?: ToolChoice;
+    response_format?: {
+        type: "text" | "json_object";
+    };
+    seed?: number;
+    /** Any extra provider-specific fields are forwarded verbatim. */
+    [key: string]: unknown;
+}
+interface CompletionUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatCompletionChoice {
+    index: number;
+    message: ChatCompletionMessage;
+    finish_reason: string | null;
+}
+interface ChatCompletion {
+    id: string;
+    object: "chat.completion";
+    created: number;
+    model: string;
+    choices: ChatCompletionChoice[];
+    usage?: CompletionUsage;
+}
+interface ChatCompletionChunkDelta {
+    role?: Role;
+    content?: string;
+    tool_calls?: Array<Partial<ToolCall> & {
+        index: number;
+    }>;
+}
+interface ChatCompletionChunkChoice {
+    index: number;
+    delta: ChatCompletionChunkDelta;
+    finish_reason: string | null;
+}
+interface ChatCompletionChunk {
+    id: string;
+    object: "chat.completion.chunk";
+    created: number;
+    model: string;
+    choices: ChatCompletionChunkChoice[];
+}
+interface AnthropicTextBlock {
+    type: "text";
+    text: string;
+}
+interface AnthropicImageBlock {
+    type: "image";
+    source: {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+}
+type AnthropicContentBlock = AnthropicTextBlock | AnthropicImageBlock;
+interface AnthropicMessage {
+    role: "user" | "assistant";
+    content: string | AnthropicContentBlock[];
+}
+interface MessageCreateParams {
+    model: string;
+    messages: AnthropicMessage[];
+    max_tokens: number;
+    system?: string | AnthropicTextBlock[];
+    stream?: boolean;
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    stop_sequences?: string[];
+    metadata?: {
+        user_id?: string;
+    };
+    [key: string]: unknown;
+}
+interface AnthropicUsage {
+    input_tokens: number;
+    output_tokens: number;
+}
+interface AnthropicMessageResponse {
+    id: string;
+    type: "message";
+    role: "assistant";
+    model: string;
+    content: AnthropicContentBlock[];
+    stop_reason: string | null;
+    stop_sequence: string | null;
+    usage: AnthropicUsage;
+}
+/** One decoded SSE event from the Anthropic streaming response. */
+interface AnthropicStreamEvent {
+    type: string;
+    [key: string]: unknown;
+}
+interface Model {
+    id: string;
+    object: "model";
+    created?: number;
+    owned_by?: string;
+    [key: string]: unknown;
+}
+interface ModelList {
+    object: "list";
+    data: Model[];
+}
+interface Chat$1 {
+    owner: string;
+    name: string;
+    createdTime?: string;
+    updatedTime?: string;
+    organization?: string;
+    displayName?: string;
+    store?: string;
+    modelProvider?: string;
+    category?: string;
+    /** "AI" for assistant threads. */
+    type?: string;
+    user?: string;
+    user1?: string;
+    user2?: string;
+    users?: string[];
+    messageCount?: number;
+    tokenCount?: number;
+    price?: number;
+    currency?: string;
+    isHidden?: boolean;
+    isDeleted?: boolean;
+    needTitle?: boolean;
+}
+interface VectorScore {
+    vector: string;
+    score: number;
+}
+interface Suggestion {
+    text: string;
+    isHit: boolean;
+}
+interface Message {
+    owner: string;
+    name: string;
+    createdTime?: string;
+    organization?: string;
+    store?: string;
+    user?: string;
+    /** Name of the parent Chat. */
+    chat?: string;
+    replyTo?: string;
+    /** "AI" for assistant messages, otherwise the username. */
+    author?: string;
+    text?: string;
+    reasonText?: string;
+    errorText?: string;
+    fileName?: string;
+    comment?: string;
+    tokenCount?: number;
+    textTokenCount?: number;
+    price?: number;
+    currency?: string;
+    isHidden?: boolean;
+    isDeleted?: boolean;
+    isRegenerated?: boolean;
+    webSearchEnabled?: boolean;
+    modelProvider?: string;
+    embeddingProvider?: string;
+    vectorScores?: VectorScore[];
+    likeUsers?: string[];
+    dislikeUsers?: string[];
+    suggestions?: Suggestion[];
+    toolCalls?: ToolCall[];
+    transactionId?: string;
+}
+/** A subset of the IAM user returned by /v1/get-account. */
+interface Account {
+    owner: string;
+    name: string;
+    displayName?: string;
+    email?: string;
+    avatar?: string;
+    type?: string;
+    isAdmin?: boolean;
+    [key: string]: unknown;
+}
+
+/** Current account (/v1/get-account) — resolves the signed-in IAM user. */
+declare class AccountResource {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Returns the account for the current token's identity. */
+    get(options?: {
+        signal?: AbortSignal;
+    }): Promise<Account>;
+}
+
+declare class Completions {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Non-streaming completion. */
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<ChatCompletion>;
+    /** Streaming completion — yields OpenAI `chat.completion.chunk`s. */
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<AsyncGenerator<ChatCompletionChunk, void, unknown>>;
+}
+declare class Chat {
+    readonly completions: Completions;
+    constructor(http: HttpClient);
+}
+
+/**
+ * Messages within chat threads. Backed by object.Message on the backend; a
+ * message belongs to a Chat via its `chat` field. These are the durable,
+ * cross-surface conversation records (distinct from a single completion call).
+ */
+declare class ChatMessages {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists messages, optionally scoped to a single chat thread by name. */
+    list(params?: {
+        chat?: string;
+        user?: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<Message[]>;
+    /** Fetches a single message by id ("owner/name"). */
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Message>;
+    /** Appends a message to a thread. */
+    append(message: Message, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /** Updates a message in place; `id` is "owner/name". */
+    update(id: string, message: Message, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /** Deletes a message. */
+    delete(message: Message, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+/**
+ * Portable chat threads — the cross-surface conversation store shared by
+ * hanzo.chat, hanzo.app, the desktop app, and hanzo-dev. A Chat is a thread
+ * keyed by "owner/name"; its turns are ChatMessages.
+ */
+declare class Chats {
+    private readonly http;
+    readonly messages: ChatMessages;
+    constructor(http: HttpClient);
+    /** Lists chat threads for a user, optionally filtered by store. */
+    list(params?: {
+        user?: string;
+        store?: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<Chat$1[]>;
+    /** Fetches a single chat thread by id ("owner/name"). */
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Chat$1>;
+    /** Creates a chat thread. */
+    create(chat: Chat$1, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /** Updates a chat thread; `id` is "owner/name". */
+    update(id: string, chat: Chat$1, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /** Deletes a chat thread (and its messages, server-side). */
+    delete(chat: Chat$1, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+}
+
+/** Anthropic Messages API (/v1/messages). */
+declare class Messages {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Non-streaming message. */
+    create(params: MessageCreateParams & {
+        stream?: false;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<AnthropicMessageResponse>;
+    /** Streaming message — yields Anthropic stream events. */
+    create(params: MessageCreateParams & {
+        stream: true;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<AsyncGenerator<AnthropicStreamEvent, void, unknown>>;
+}
+
+/** Model catalog (/v1/models, OpenAI-compatible). */
+declare class Models {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Lists available models. */
+    list(options?: {
+        signal?: AbortSignal;
+    }): Promise<Model[]>;
+}
+
+/**
+ * The Hanzo AI client. Headless: no UI, no React, no DOM dependency beyond
+ * the standard `fetch`/`ReadableStream` web APIs.
+ */
+declare class AiClient {
+    /** OpenAI-compatible completions: `chat.completions.create(...)`. */
+    readonly chat: Chat;
+    /** Anthropic Messages API: `messages.create(...)`. */
+    readonly messages: Messages;
+    /** Model catalog: `models.list()`. */
+    readonly models: Models;
+    /** Portable chat threads + their messages (cross-surface store). */
+    readonly chats: Chats;
+    /** Current signed-in account. */
+    readonly account: AccountResource;
+    /** Shared transport, exposed for advanced/custom calls. */
+    readonly http: HttpClient;
+    constructor(config?: ClientConfig);
+}
+/** Creates a typed Hanzo AI client. */
+declare function createAiClient(config?: ClientConfig): AiClient;
+
+/** Base error for every failure surfaced by the SDK. */
+declare class HanzoAIError extends Error {
+    constructor(message: string);
+}
+/** Non-2xx HTTP response, or a CRUD envelope with status "error". */
+declare class APIError extends HanzoAIError {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/** No token was available when a request required authentication. */
+declare class AuthError extends HanzoAIError {
+    constructor(message?: string);
+}
+
+/** A single decoded Server-Sent Event. */
+interface SSEvent {
+    event?: string;
+    data: string;
+}
+/**
+ * Parses a byte stream into SSE events. Handles chunk boundaries that split a
+ * single event across reads, CRLF or LF line endings, and multi-line `data:`
+ * fields per the SSE spec. Comment lines (starting with ":") are ignored.
+ */
+declare function parseSSE(body: ReadableStream<Uint8Array>): AsyncGenerator<SSEvent, void, unknown>;
+/**
+ * Yields OpenAI `chat.completion.chunk` objects from a streaming
+ * /v1/chat/completions response, stopping at the `[DONE]` sentinel.
+ */
+declare function streamChatCompletion(res: Response): AsyncGenerator<ChatCompletionChunk, void, unknown>;
+/**
+ * Yields Anthropic stream events from a streaming /v1/messages response. The
+ * event name is carried on `type` (Anthropic also includes it in the JSON, but
+ * the SSE `event:` line is authoritative when present).
+ */
+declare function streamMessage(res: Response): AsyncGenerator<AnthropicStreamEvent, void, unknown>;
+
+export { APIError, type Account, AccountResource, AiClient, type AnthropicContentBlock, type AnthropicImageBlock, type AnthropicMessage, type AnthropicMessageResponse, type AnthropicStreamEvent, type AnthropicTextBlock, type AnthropicUsage, AuthError, Chat, type ChatCompletion, type ChatCompletionChoice, type ChatCompletionChunk, type ChatCompletionChunkChoice, type ChatCompletionChunkDelta, type ChatCompletionContentPart, type ChatCompletionContentPartImage, type ChatCompletionContentPartText, type ChatCompletionCreateParams, type ChatCompletionMessage, ChatMessages, Chats, type ClientConfig, type CompletionUsage, Completions, type Envelope, type FunctionDefinition, HanzoAIError, HttpClient, type Message, type MessageCreateParams, Messages, type Model, type ModelList, Models, type Role, type SSEvent, type Suggestion, type TokenProvider, type Tool, type ToolCall, type ToolChoice, type VectorScore, createAiClient, joinUrl, parseSSE, streamChatCompletion, streamMessage };