edgecrab-sdk 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,234 @@
+/** Type definitions for the EdgeCrab Node.js SDK. */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    name?: string;
+    tool_call_id?: string;
+}
+interface ChatCompletionRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    stream?: boolean;
+    tools?: Record<string, unknown>[];
+}
+interface UsageInfo {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: string | null;
+}
+interface ChatCompletionResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatChoice[];
+    usage?: UsageInfo;
+}
+interface StreamDelta {
+    role?: string;
+    content?: string;
+}
+interface StreamChoice {
+    index: number;
+    delta: StreamDelta;
+    finish_reason: string | null;
+}
+interface StreamChunk {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: StreamChoice[];
+}
+interface ModelInfo {
+    id: string;
+    object: string;
+    created?: number;
+    owned_by?: string;
+}
+interface HealthResponse {
+    status: string;
+    version?: string;
+}
+interface AgentOptions {
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    systemPrompt?: string;
+    maxTurns?: number;
+    temperature?: number;
+    maxTokens?: number;
+    timeout?: number;
+    sessionId?: string;
+    streaming?: boolean;
+    maxRetries?: number;
+    onToken?: (token: string) => void;
+    onToolCall?: (name: string, args: Record<string, unknown>) => void;
+    onTurn?: (turnNum: number, message: ChatMessage) => void;
+    onError?: (error: Error) => void;
+}
+interface AgentResult {
+    response: string;
+    messages: ChatMessage[];
+    sessionId: string;
+    model: string;
+    turnsUsed: number;
+    finishedNaturally: boolean;
+    interrupted: boolean;
+    maxTurnsExceeded: boolean;
+    usage: UsageInfo;
+}
+interface ClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    timeout?: number;
+    maxRetries?: number;
+    retryBaseDelay?: number;
+}
+interface ExportedConversation {
+    sessionId: string;
+    model: string;
+    messages: ChatMessage[];
+    turnCount: number;
+    usage: UsageInfo;
+}
+
+/**
+ * High-level Agent abstraction for the EdgeCrab Node.js SDK.
+ *
+ * Inspired by hermes-agent's AIAgent — provides a batteries-included Agent
+ * object that manages conversation state, streaming, and session lifecycle.
+ */
+
+declare class Agent {
+    readonly model: string;
+    readonly systemPrompt: string | undefined;
+    readonly maxTurns: number;
+    readonly temperature: number | undefined;
+    readonly maxTokens: number | undefined;
+    readonly streaming: boolean;
+    sessionId: string;
+    onToken: ((token: string) => void) | undefined;
+    onToolCall: ((name: string, args: Record<string, unknown>) => void) | undefined;
+    onTurn: ((turnNum: number, message: ChatMessage) => void) | undefined;
+    onError: ((error: Error) => void) | undefined;
+    private messages;
+    private turnCount;
+    private totalUsage;
+    private client;
+    private interrupted;
+    constructor(options?: AgentOptions);
+    /** Signal the agent to stop after the current turn. */
+    interrupt(): void;
+    /** Clear the interrupt flag so the agent can continue. */
+    clearInterrupt(): void;
+    /** Whether the agent has been interrupted. */
+    get isInterrupted(): boolean;
+    /** Send a message and return the assistant's text reply. Maintains history. */
+    chat(message: string): Promise<string>;
+    private chatStreaming;
+    /** Run a full agent conversation. Returns a structured AgentResult. */
+    run(message: string, options?: {
+        conversationHistory?: ChatMessage[];
+    }): Promise<AgentResult>;
+    /** Stream response tokens as an async iterable. */
+    stream(message: string): AsyncGenerator<string>;
+    /** Manually inject a message into the conversation history. */
+    addMessage(role: ChatMessage['role'], content: string): void;
+    /** Reset conversation state for a new session. */
+    reset(): void;
+    /** Export the current conversation state as a serializable object. */
+    exportConversation(): ExportedConversation;
+    /** Restore a conversation state from a previously exported object. */
+    importConversation(data: ExportedConversation): void;
+    /** Create a fork of this agent with an independent copy of the conversation. */
+    clone(): Agent;
+    /** Current conversation history (copy). */
+    getMessages(): ChatMessage[];
+    /** Number of user turns completed. */
+    getTurnCount(): number;
+    /** Accumulated token usage. */
+    getUsage(): UsageInfo;
+    /** List available models from the server. */
+    listModels(): Promise<ModelInfo[]>;
+    /** Check server health. */
+    health(): Promise<HealthResponse>;
+    private extractResponse;
+    private accumulateUsage;
+}
+
+/**
+ * Low-level HTTP client for the EdgeCrab OpenAI-compatible API.
+ */
+
+declare class EdgeCrabError extends Error {
+    statusCode: number | undefined;
+    constructor(message: string, statusCode?: number);
+}
+declare class AuthenticationError extends EdgeCrabError {
+    constructor(message: string, statusCode?: number);
+}
+declare class RateLimitError extends EdgeCrabError {
+    retryAfter: number | undefined;
+    constructor(message: string, retryAfter?: number);
+}
+declare class ServerError extends EdgeCrabError {
+    constructor(message: string, statusCode?: number);
+}
+declare class TimeoutError extends EdgeCrabError {
+    constructor(message?: string);
+}
+declare class ConnectionError extends EdgeCrabError {
+    constructor(message?: string);
+}
+declare class MaxTurnsExceededError extends EdgeCrabError {
+    maxTurns: number;
+    constructor(maxTurns: number);
+}
+declare class InterruptedError extends EdgeCrabError {
+    constructor();
+}
+declare class EdgeCrabClient {
+    private baseUrl;
+    private headers;
+    private timeout;
+    private maxRetries;
+    private retryBaseDelay;
+    constructor(options?: ClientOptions);
+    /** Simple chat — send a message, get a reply string. */
+    chat(message: string, options?: {
+        model?: string;
+        system?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<string>;
+    /** Create a chat completion (non-streaming). */
+    createCompletion(messages: ChatMessage[], options?: {
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+        tools?: Record<string, unknown>[];
+    }): Promise<ChatCompletionResponse>;
+    private postWithRetry;
+    /** Create a streaming chat completion. Returns an async iterator of chunks. */
+    streamCompletion(messages: ChatMessage[], options?: {
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+        tools?: Record<string, unknown>[];
+    }): AsyncGenerator<StreamChunk>;
+    /** List available models. */
+    listModels(): Promise<ModelInfo[]>;
+    /** Check server health. */
+    health(): Promise<HealthResponse>;
+    private fetchJSON;
+}
+
+export { Agent, type AgentOptions, type AgentResult, AuthenticationError, type ChatChoice, type ChatCompletionRequest, type ChatCompletionResponse, type ChatMessage, type ClientOptions, ConnectionError, EdgeCrabClient, EdgeCrabError, type ExportedConversation, type HealthResponse, InterruptedError, MaxTurnsExceededError, type ModelInfo, RateLimitError, ServerError, type StreamChoice, type StreamChunk, type StreamDelta, TimeoutError, type UsageInfo };

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+/** Type definitions for the EdgeCrab Node.js SDK. */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    name?: string;
+    tool_call_id?: string;
+}
+interface ChatCompletionRequest {
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    stream?: boolean;
+    tools?: Record<string, unknown>[];
+}
+interface UsageInfo {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+interface ChatChoice {
+    index: number;
+    message: ChatMessage;
+    finish_reason: string | null;
+}
+interface ChatCompletionResponse {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: ChatChoice[];
+    usage?: UsageInfo;
+}
+interface StreamDelta {
+    role?: string;
+    content?: string;
+}
+interface StreamChoice {
+    index: number;
+    delta: StreamDelta;
+    finish_reason: string | null;
+}
+interface StreamChunk {
+    id: string;
+    object: string;
+    created: number;
+    model: string;
+    choices: StreamChoice[];
+}
+interface ModelInfo {
+    id: string;
+    object: string;
+    created?: number;
+    owned_by?: string;
+}
+interface HealthResponse {
+    status: string;
+    version?: string;
+}
+interface AgentOptions {
+    model?: string;
+    baseUrl?: string;
+    apiKey?: string;
+    systemPrompt?: string;
+    maxTurns?: number;
+    temperature?: number;
+    maxTokens?: number;
+    timeout?: number;
+    sessionId?: string;
+    streaming?: boolean;
+    maxRetries?: number;
+    onToken?: (token: string) => void;
+    onToolCall?: (name: string, args: Record<string, unknown>) => void;
+    onTurn?: (turnNum: number, message: ChatMessage) => void;
+    onError?: (error: Error) => void;
+}
+interface AgentResult {
+    response: string;
+    messages: ChatMessage[];
+    sessionId: string;
+    model: string;
+    turnsUsed: number;
+    finishedNaturally: boolean;
+    interrupted: boolean;
+    maxTurnsExceeded: boolean;
+    usage: UsageInfo;
+}
+interface ClientOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    timeout?: number;
+    maxRetries?: number;
+    retryBaseDelay?: number;
+}
+interface ExportedConversation {
+    sessionId: string;
+    model: string;
+    messages: ChatMessage[];
+    turnCount: number;
+    usage: UsageInfo;
+}
+
+/**
+ * High-level Agent abstraction for the EdgeCrab Node.js SDK.
+ *
+ * Inspired by hermes-agent's AIAgent — provides a batteries-included Agent
+ * object that manages conversation state, streaming, and session lifecycle.
+ */
+
+declare class Agent {
+    readonly model: string;
+    readonly systemPrompt: string | undefined;
+    readonly maxTurns: number;
+    readonly temperature: number | undefined;
+    readonly maxTokens: number | undefined;
+    readonly streaming: boolean;
+    sessionId: string;
+    onToken: ((token: string) => void) | undefined;
+    onToolCall: ((name: string, args: Record<string, unknown>) => void) | undefined;
+    onTurn: ((turnNum: number, message: ChatMessage) => void) | undefined;
+    onError: ((error: Error) => void) | undefined;
+    private messages;
+    private turnCount;
+    private totalUsage;
+    private client;
+    private interrupted;
+    constructor(options?: AgentOptions);
+    /** Signal the agent to stop after the current turn. */
+    interrupt(): void;
+    /** Clear the interrupt flag so the agent can continue. */
+    clearInterrupt(): void;
+    /** Whether the agent has been interrupted. */
+    get isInterrupted(): boolean;
+    /** Send a message and return the assistant's text reply. Maintains history. */
+    chat(message: string): Promise<string>;
+    private chatStreaming;
+    /** Run a full agent conversation. Returns a structured AgentResult. */
+    run(message: string, options?: {
+        conversationHistory?: ChatMessage[];
+    }): Promise<AgentResult>;
+    /** Stream response tokens as an async iterable. */
+    stream(message: string): AsyncGenerator<string>;
+    /** Manually inject a message into the conversation history. */
+    addMessage(role: ChatMessage['role'], content: string): void;
+    /** Reset conversation state for a new session. */
+    reset(): void;
+    /** Export the current conversation state as a serializable object. */
+    exportConversation(): ExportedConversation;
+    /** Restore a conversation state from a previously exported object. */
+    importConversation(data: ExportedConversation): void;
+    /** Create a fork of this agent with an independent copy of the conversation. */
+    clone(): Agent;
+    /** Current conversation history (copy). */
+    getMessages(): ChatMessage[];
+    /** Number of user turns completed. */
+    getTurnCount(): number;
+    /** Accumulated token usage. */
+    getUsage(): UsageInfo;
+    /** List available models from the server. */
+    listModels(): Promise<ModelInfo[]>;
+    /** Check server health. */
+    health(): Promise<HealthResponse>;
+    private extractResponse;
+    private accumulateUsage;
+}
+
+/**
+ * Low-level HTTP client for the EdgeCrab OpenAI-compatible API.
+ */
+
+declare class EdgeCrabError extends Error {
+    statusCode: number | undefined;
+    constructor(message: string, statusCode?: number);
+}
+declare class AuthenticationError extends EdgeCrabError {
+    constructor(message: string, statusCode?: number);
+}
+declare class RateLimitError extends EdgeCrabError {
+    retryAfter: number | undefined;
+    constructor(message: string, retryAfter?: number);
+}
+declare class ServerError extends EdgeCrabError {
+    constructor(message: string, statusCode?: number);
+}
+declare class TimeoutError extends EdgeCrabError {
+    constructor(message?: string);
+}
+declare class ConnectionError extends EdgeCrabError {
+    constructor(message?: string);
+}
+declare class MaxTurnsExceededError extends EdgeCrabError {
+    maxTurns: number;
+    constructor(maxTurns: number);
+}
+declare class InterruptedError extends EdgeCrabError {
+    constructor();
+}
+declare class EdgeCrabClient {
+    private baseUrl;
+    private headers;
+    private timeout;
+    private maxRetries;
+    private retryBaseDelay;
+    constructor(options?: ClientOptions);
+    /** Simple chat — send a message, get a reply string. */
+    chat(message: string, options?: {
+        model?: string;
+        system?: string;
+        temperature?: number;
+        maxTokens?: number;
+    }): Promise<string>;
+    /** Create a chat completion (non-streaming). */
+    createCompletion(messages: ChatMessage[], options?: {
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+        tools?: Record<string, unknown>[];
+    }): Promise<ChatCompletionResponse>;
+    private postWithRetry;
+    /** Create a streaming chat completion. Returns an async iterator of chunks. */
+    streamCompletion(messages: ChatMessage[], options?: {
+        model?: string;
+        temperature?: number;
+        maxTokens?: number;
+        tools?: Record<string, unknown>[];
+    }): AsyncGenerator<StreamChunk>;
+    /** List available models. */
+    listModels(): Promise<ModelInfo[]>;
+    /** Check server health. */
+    health(): Promise<HealthResponse>;
+    private fetchJSON;
+}
+
+export { Agent, type AgentOptions, type AgentResult, AuthenticationError, type ChatChoice, type ChatCompletionRequest, type ChatCompletionResponse, type ChatMessage, type ClientOptions, ConnectionError, EdgeCrabClient, EdgeCrabError, type ExportedConversation, type HealthResponse, InterruptedError, MaxTurnsExceededError, type ModelInfo, RateLimitError, ServerError, type StreamChoice, type StreamChunk, type StreamDelta, TimeoutError, type UsageInfo };