@useago/sdk 0.1.0

package/dist/api/HttpClient.d.ts

@@ -0,0 +1,31 @@
+import type { AgoConfig } from "../client/types";
+/**
+ * HTTP client with authentication headers
+ */
+export declare class HttpClient {
+    private baseUrl;
+    private headers;
+    constructor(config: AgoConfig);
+    /**
+     * Update configuration (e.g., JWT token)
+     */
+    updateConfig(config: Partial<AgoConfig>): void;
+    /**
+     * Make a GET request
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * Make a POST request with JSON body
+     */
+    post<T>(path: string, body?: unknown): Promise<T>;
+    /**
+     * Make a POST request and return the raw Response (for streaming)
+     */
+    postStream(path: string, body?: unknown): Promise<Response>;
+    /**
+     * Make a POST request with FormData (for file uploads)
+     */
+    postFormData(path: string, formData: FormData): Promise<Response>;
+    private request;
+    private handleErrorResponse;
+}

package/dist/api/index.d.ts

@@ -0,0 +1 @@
+export { HttpClient } from "./HttpClient";

package/dist/client/AgoClient.d.ts

@@ -0,0 +1,113 @@
+import type { ClientFunctionDefinition, ClientFunctionHandler, ClientFunctionSchema } from "../functions/types";
+import type { AgoConfig, AgoClientEvents, AgoEventName, AgoEventHandler, AgoMessage, Conversation, SendMessageOptions } from "./types";
+/**
+ * Main SDK client for AGO Chat integration
+ */
+export declare class AgoClient {
+    private httpClient;
+    private functionRegistry;
+    private eventEmitter;
+    private config;
+    constructor(config: AgoConfig);
+    /**
+     * Send a message and receive a streaming response
+     */
+    sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    private processSSEResponse;
+    private handleClientFunctionInvocation;
+    /**
+     * Get list of conversations
+     */
+    getConversations(): Promise<Conversation[]>;
+    /**
+     * Get a specific conversation with messages
+     */
+    getConversation(conversationId: string): Promise<Conversation>;
+    /**
+     * Get messages for a conversation
+     */
+    getMessages(conversationId: string): Promise<AgoMessage[]>;
+    /**
+     * Submit form data for a tool call
+     */
+    submitToolCallForm(toolCallId: string, formData: Record<string, unknown>): Promise<void>;
+    /**
+     * Confirm a tool call
+     */
+    confirmToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Reject a tool call
+     */
+    rejectToolCall(toolCallId: string): Promise<void>;
+    /**
+     * Submit feedback for a message
+     */
+    submitFeedback(messageId: string, rating: "positive" | "negative"): Promise<void>;
+    /**
+     * Register a client-side function that AGO can call.
+     * Accepts either a definition object or (name, handler, schema) args.
+     *
+     * ```ts
+     * // Single-object (preferred)
+     * client.registerFunction({
+     *   name: "lookupOrder",
+     *   description: "Look up an order",
+     *   parameters: { type: "object", properties: { id: { type: "string" } } },
+     *   handler: async (args) => fetchOrder(args.id),
+     * });
+     *
+     * // Classic 3-arg form
+     * client.registerFunction("lookupOrder", handler, schema);
+     * ```
+     */
+    registerFunction(definition: ClientFunctionDefinition): void;
+    registerFunction(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    /**
+     * Unregister a client-side function
+     */
+    unregisterFunction(name: string): boolean;
+    /**
+     * Get all registered function schemas
+     */
+    getRegisteredFunctions(): ClientFunctionSchema[];
+    /**
+     * Register a navigation function that lets AGO navigate users to different pages.
+     * @param navigate - A callback that performs the navigation (e.g. react-router's navigate)
+     * @param routes - Map of route names to paths, with descriptions for the LLM
+     */
+    registerNavigationFunction(navigate: (path: string) => void, routes: Array<{
+        name: string;
+        path: string;
+        description: string;
+    }>): void;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Unsubscribe from an event
+     */
+    off<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Subscribe to an event once — auto-unsubscribes after the first call.
+     */
+    once<K extends AgoEventName>(event: K, handler: AgoEventHandler<K>): void;
+    /**
+     * Returns a Promise that resolves the next time `event` fires.
+     *
+     * ```ts
+     * const msg = await client.waitFor("message:complete", { timeout: 10000 });
+     * ```
+     */
+    waitFor<K extends AgoEventName>(event: K, options?: {
+        timeout?: number;
+    }): Promise<AgoClientEvents[K]>;
+    /**
+     * Update client configuration
+     */
+    updateConfig(config: Partial<AgoConfig>): void;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}

package/dist/client/errors.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Base error class for AGO SDK
+ */
+export declare class AgoError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+/**
+ * Error from API response
+ */
+export declare class AgoApiError extends AgoError {
+    type: string;
+    param?: string | undefined;
+    docUrl?: string | undefined;
+    constructor(message: string, code: string, statusCode: number, type: string, param?: string | undefined, docUrl?: string | undefined);
+    static fromResponse(data: ApiErrorResponse, statusCode: number): AgoApiError;
+}
+export interface ApiErrorResponse {
+    error: {
+        type: string;
+        code: string;
+        message: string;
+        param?: string;
+        doc_url?: string;
+    };
+}
+/**
+ * Network/connection error
+ */
+export declare class AgoNetworkError extends AgoError {
+    originalError?: Error | undefined;
+    constructor(message: string, originalError?: Error | undefined);
+}
+/**
+ * SSE stream error
+ */
+export declare class AgoStreamError extends AgoError {
+    constructor(message: string);
+}
+/**
+ * Function execution error
+ */
+export declare class AgoFunctionError extends AgoError {
+    functionName: string;
+    originalError?: Error | undefined;
+    constructor(message: string, functionName: string, originalError?: Error | undefined);
+}

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+export { AgoClient } from "./AgoClient";
+export * from "./types";
+export * from "./errors";

package/dist/client/types.d.ts

@@ -0,0 +1,203 @@
+/**
+ * SDK Configuration
+ */
+export interface AgoConfig {
+    /** Widget API key (X-Widget-Key header) */
+    apiKey: string;
+    /** Widget ID (X-Widget-Id header) */
+    widgetId: string;
+    /** API base URL (default: https://api.useago.com) */
+    baseUrl?: string;
+    /** Default agent ID for new conversations */
+    defaultAgentId?: string;
+    /** User email for identification */
+    userEmail?: string;
+    /** JWT token for authenticated users */
+    userJwt?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Options for sending a message
+ */
+export interface SendMessageOptions {
+    /** Existing conversation ID */
+    conversationId?: string;
+    /** Override default agent */
+    agentId?: string;
+    /** File attachments */
+    files?: File[];
+}
+/**
+ * Message from AGO
+ */
+export interface AgoMessage {
+    id: string;
+    conversationId: string;
+    content: string;
+    role: "user" | "assistant";
+    status: MessageStatus;
+    agent?: AgoAgent;
+    sources?: AgoSource[];
+    toolCalls?: ToolCallData[];
+    followUpReplies?: string[];
+    createdAt: Date;
+}
+export type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
+/**
+ * Agent information
+ */
+export interface AgoAgent {
+    id: string;
+    name: string;
+    displayName?: string;
+}
+/**
+ * Knowledge source citation
+ */
+export interface AgoSource {
+    id: string;
+    title: string;
+    url?: string;
+}
+/**
+ * Conversation/Thread
+ */
+export interface Conversation {
+    id: string;
+    title: string;
+    lastMessageDate: Date;
+    messages?: AgoMessage[];
+}
+/**
+ * Tool call data from SSE stream
+ */
+export interface ToolCallData {
+    id: string;
+    type: ToolCallType;
+    status: string;
+    toolName: string;
+    toolDisplayName?: string;
+    message?: string;
+    formSchema?: FormSchema;
+    data?: Record<string, unknown>;
+    functionName?: string;
+    arguments?: Record<string, unknown>;
+}
+export type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
+/**
+ * Form schema for tool calls requiring user input
+ */
+export interface FormSchema {
+    type: "object";
+    properties: Record<string, FormField>;
+    required?: string[];
+}
+export interface FormField {
+    type: "string" | "number" | "boolean" | "array";
+    title?: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+}
+/**
+ * Client-side function types
+ */
+export interface FunctionSchema {
+    name: string;
+    description: string;
+    parameters: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+        }>;
+        required?: string[];
+    };
+}
+export type ClientFunction = (args: Record<string, unknown>) => Promise<unknown> | unknown;
+export interface FunctionDefinition {
+    name: string;
+    schema: FunctionSchema;
+    handler: ClientFunction;
+}
+export interface ClientFunctionInvocation {
+    invocationId: string;
+    functionName: string;
+    arguments: Record<string, unknown>;
+    conversationId: string;
+}
+/**
+ * SSE stream chunk data
+ */
+export interface SSEChunkData {
+    content?: string;
+    full_content?: string;
+    message_id?: string;
+    status?: MessageStatus;
+    thread?: {
+        id: string;
+    };
+    agent?: {
+        id: string;
+        name: string;
+        display_name?: string;
+    };
+    knowledge_sources?: Array<{
+        knowledge_document: {
+            id: string;
+            title: string;
+            use_external_link: boolean;
+            external_link_url?: string;
+            internal_link_url?: string;
+        };
+        position: number;
+    }>;
+    tool_call_data?: boolean;
+    type?: string;
+    id?: string;
+    tool_name?: string;
+    tool_display_name?: string;
+    function_name?: string;
+    arguments?: Record<string, unknown>;
+    form_schema?: FormSchema;
+    message?: string;
+    data?: Record<string, unknown>;
+    follow_up_replies?: string[];
+    satisfaction_feedback?: unknown;
+    ask_to_talk_to_human?: boolean;
+}
+/**
+ * SDK Events
+ */
+export interface AgoClientEvents {
+    "message:start": {
+        conversationId: string;
+        messageId: string;
+    };
+    "message:chunk": {
+        content: string;
+        conversationId: string;
+        messageId: string;
+    };
+    "message:complete": AgoMessage;
+    "message:error": {
+        error: string;
+        conversationId?: string;
+        messageId?: string;
+    };
+    "toolCall:received": ToolCallData;
+    "toolCall:form": ToolCallData;
+    "function:invoke": ClientFunctionInvocation;
+    "function:result": {
+        invocationId: string;
+        result: unknown;
+        error?: string;
+    };
+    "connection:status": {
+        connected: boolean;
+    };
+}
+export type AgoEventName = keyof AgoClientEvents;
+export type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;