@useago/sdk 0.3.2 → 0.3.3

package/dist/angular.cjs

@@ -1,143 +1 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_AgoClient = require("./AgoClient-wMVUQqCD.cjs");
-//#region src/angular/ago.service.ts
-/**
-* Angular-style service wrapping AgoClient.
-* Provides RxJS-like Observables for streaming events and standard Promise-based methods.
-*
-* Usage with Angular DI:
-* ```ts
-* import { provideAgo, AgoService } from "@useago/sdk/angular";
-*
-* // In providers array:
-* provideAgo({ baseUrl: "https://YOUR-DOMAIN.useago.com" })
-*
-* // In component:
-* @Component({...})
-* export class ChatComponent {
-*   private ago = inject(AgoService);
-*   messages$ = this.ago.messages$;
-* }
-* ```
-*
-* Works without Angular DI too — just instantiate directly:
-* ```ts
-* const ago = new AgoService({ baseUrl: "https://YOUR-DOMAIN.useago.com" });
-* ```
-*/
-var AgoService = class {
-	constructor(config) {
-		this.client = new require_AgoClient.AgoClient(config);
-		this.messages$ = this.fromEvent("message:complete");
-		this.chunks$ = this.fromEvent("message:chunk");
-		this.errors$ = this.fromEvent("message:error");
-		this.messageStart$ = this.fromEvent("message:start");
-	}
-	/** Create a minimal Observable from an AgoClient event */
-	fromEvent(event) {
-		const client = this.client;
-		return { subscribe(observer) {
-			const handler = (data) => {
-				observer.next?.(data);
-			};
-			client.on(event, handler);
-			return { unsubscribe: () => client.off(event, handler) };
-		} };
-	}
-	/** Send a message and get a streaming response */
-	sendMessage(content, options) {
-		return this.client.sendMessage(content, options);
-	}
-	/** Get all conversations */
-	getConversations() {
-		return this.client.getConversations();
-	}
-	/** Get a specific conversation with messages */
-	getConversation(id) {
-		return this.client.getConversation(id);
-	}
-	/** Get messages for a conversation */
-	getMessages(conversationId) {
-		return this.client.getMessages(conversationId);
-	}
-	/** Submit form data for a tool call */
-	submitToolCallForm(toolCallId, formData) {
-		return this.client.submitToolCallForm(toolCallId, formData);
-	}
-	/** Confirm a tool call */
-	confirmToolCall(toolCallId) {
-		return this.client.confirmToolCall(toolCallId);
-	}
-	/** Reject a tool call */
-	rejectToolCall(toolCallId) {
-		return this.client.rejectToolCall(toolCallId);
-	}
-	/** Submit feedback for a message */
-	submitFeedback(messageId, rating) {
-		return this.client.submitFeedback(messageId, rating);
-	}
-	registerFunction(nameOrDef, handler, schema) {
-		if (typeof nameOrDef === "object") this.client.registerFunction(nameOrDef);
-		else this.client.registerFunction(nameOrDef, handler, schema);
-	}
-	/** Unregister a client-side function */
-	unregisterFunction(name) {
-		return this.client.unregisterFunction(name);
-	}
-	/** Register navigation routes */
-	registerNavigationFunction(navigate, routes) {
-		this.client.registerNavigationFunction(navigate, routes);
-	}
-	/** Subscribe to a client event */
-	on(event, handler) {
-		this.client.on(event, handler);
-	}
-	/** Unsubscribe from a client event */
-	off(event, handler) {
-		this.client.off(event, handler);
-	}
-	/** Update client config */
-	updateConfig(config) {
-		this.client.updateConfig(config);
-	}
-	/** Get the underlying AgoClient instance */
-	getClient() {
-		return this.client;
-	}
-	/** Destroy the service and clean up resources */
-	destroy() {
-		this.client.destroy();
-	}
-};
-//#endregion
-//#region src/angular/provide.ts
-/**
-* Factory function that returns an Angular-compatible provider.
-* Use in your app's `providers` array or `bootstrapApplication`:
-*
-* ```ts
-* import { provideAgo, AgoService } from "@useago/sdk/angular";
-*
-* bootstrapApplication(AppComponent, {
-*   providers: [provideAgo({ baseUrl: "https://YOUR-DOMAIN.useago.com" })],
-* });
-*
-* // Then inject in any component:
-* const ago = inject(AgoService);
-* ```
-*
-* Returns a provider tuple compatible with Angular's DI.
-* Since this package avoids a hard Angular dependency, the provider
-* is returned as a plain object — Angular's injector accepts this format.
-*/
-function provideAgo(options) {
-	return {
-		provide: AgoService,
-		useValue: new AgoService(options)
-	};
-}
-//#endregion
-exports.AgoService = AgoService;
-exports.provideAgo = provideAgo;
-
-//# sourceMappingURL=angular.cjs.map
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("./AgoClient-bjN-z2ZQ.cjs");var n=class{constructor(e){this.client=new o.AgoClient(e),this.messages$=this.fromEvent("message:complete"),this.chunks$=this.fromEvent("message:chunk"),this.errors$=this.fromEvent("message:error"),this.messageStart$=this.fromEvent("message:start")}fromEvent(e){const t=this.client;return{subscribe(i){const s=r=>{i.next?.(r)};return t.on(e,s),{unsubscribe:()=>t.off(e,s)}}}}sendMessage(e,t){return this.client.sendMessage(e,t)}getConversations(){return this.client.getConversations()}getConversation(e){return this.client.getConversation(e)}getMessages(e){return this.client.getMessages(e)}submitToolCallForm(e,t){return this.client.submitToolCallForm(e,t)}confirmToolCall(e){return this.client.confirmToolCall(e)}rejectToolCall(e){return this.client.rejectToolCall(e)}submitFeedback(e,t){return this.client.submitFeedback(e,t)}registerFunction(e,t,i){typeof e=="object"?this.client.registerFunction(e):this.client.registerFunction(e,t,i)}unregisterFunction(e){return this.client.unregisterFunction(e)}registerNavigationFunction(e,t){this.client.registerNavigationFunction(e,t)}on(e,t){this.client.on(e,t)}off(e,t){this.client.off(e,t)}updateConfig(e){this.client.updateConfig(e)}getClient(){return this.client}destroy(){this.client.destroy()}};function c(e){return{provide:n,useValue:new n(e)}}exports.AgoService=n;exports.provideAgo=c;

package/dist/angular.d.cts

@@ -0,0 +1,530 @@
+/**
+ * Agent information
+ */
+export declare interface AgoAgent {
+    id: string;
+    name: string;
+    displayName?: string;
+}
+
+/**
+ * Main SDK client for AGO Chat integration
+ */
+declare class AgoClient {
+    private httpClient;
+    private functionRegistry;
+    private contextRegistry;
+    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>;
+    /**
+     * Relay a completed form collector's values to a server-configured destination.
+     *
+     * Used by `createFormCollector` / `useFormCollector` in `{ via: "backend" }` mode:
+     * the browser never holds the destination URL or its secret — the backend resolves
+     * `destination` (a named, opted-in tool) and forwards the values from the server.
+     */
+    submitFormCollector(destination: string, values: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 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;
+    /**
+     * Short alias for `registerFunction`. Also accepts an array of definitions.
+     *
+     * ```ts
+     * client.register(lookupOrder);
+     * client.register([lookupOrder, cancelOrder]);
+     * ```
+     */
+    register(definition: ClientFunctionDefinition | ClientFunctionDefinition[]): 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;
+    /**
+     * Register or update a piece of client-side context.
+     * This context is sent with every message so the AI understands the user's situation.
+     *
+     * ```ts
+     * client.setContext("order-page", {
+     *   name: "Order detail",
+     *   description: "User is viewing order #123",
+     *   data: { orderId: "123", status: "shipped" },
+     * });
+     * ```
+     */
+    setContext(key: string, entry: ContextEntry): void;
+    /**
+     * Remove a previously registered context entry.
+     */
+    removeContext(key: string): boolean;
+    /**
+     * Register a dynamic context provider. The callback is invoked every time
+     * a message is sent, so the AI always gets the freshest data.
+     *
+     * Use this for context that lives outside React state — global stores,
+     * refs, or computed values.
+     *
+     * ```ts
+     * client.addDynamicContext("cart", () => ({
+     *   name: "Checkout",
+     *   data: { itemCount: cart.items.length, total: cart.total },
+     * }));
+     * ```
+     */
+    addDynamicContext(key: string, provider: DynamicContextProvider): void;
+    /**
+     * Remove a dynamic context provider.
+     */
+    removeDynamicContext(key: string): boolean;
+    /**
+     * Enable automatic capture of the current browser page (URL + title).
+     * Injected as a dynamic context entry named `browser-page`.
+     */
+    enableAutoPageContext(): void;
+    /**
+     * Get the current context snapshot.
+     */
+    getContextSnapshot(): ContextSnapshot | null;
+    /**
+     * 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;
+}
+
+/**
+ * SDK Events
+ */
+export declare 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;
+    };
+}
+
+/**
+ * SDK Configuration
+ */
+export declare interface AgoConfig {
+    /** API base URL (e.g., https://YOUR-DOMAIN.useago.com) */
+    baseUrl: string;
+    /** Widget ID (X-Widget-Id header). Auto-generated if not provided. */
+    widgetId?: string;
+    /** Default agent (id or slug) for new conversations. Shorthand for `defaultAgentId`. */
+    agent?: string;
+    /** Default agent ID for new conversations. Prefer `agent`. */
+    defaultAgentId?: string;
+    /** Permission name to apply to all requests (sent as `X-Widget-Permission`). Mirrors the widget's `window.AGO.permission`. */
+    permission?: string;
+    /** User email for identification */
+    userEmail?: string;
+    /** JWT token for authenticated users */
+    userJwt?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+declare type AgoEventHandler<K extends AgoEventName> = (data: AgoClientEvents[K]) => void;
+
+export declare type AgoEventName = keyof AgoClientEvents;
+
+/**
+ * Message from AGO
+ */
+export declare interface AgoMessage {
+    id: string;
+    conversationId: string;
+    content: string;
+    role: "user" | "assistant";
+    status: MessageStatus;
+    agent?: AgoAgent;
+    sources?: AgoSource[];
+    toolCalls?: ToolCallData[];
+    followUpReplies?: string[];
+    createdAt: Date;
+}
+
+export declare interface AgoProvideOptions extends AgoConfig {
+}
+
+/**
+ * Angular-style service wrapping AgoClient.
+ * Provides RxJS-like Observables for streaming events and standard Promise-based methods.
+ *
+ * Usage with Angular DI:
+ * ```ts
+ * import { provideAgo, AgoService } from "@useago/sdk/angular";
+ *
+ * // In providers array:
+ * provideAgo({ baseUrl: "https://YOUR-DOMAIN.useago.com" })
+ *
+ * // In component:
+ * @Component({...})
+ * export class ChatComponent {
+ *   private ago = inject(AgoService);
+ *   messages$ = this.ago.messages$;
+ * }
+ * ```
+ *
+ * Works without Angular DI too — just instantiate directly:
+ * ```ts
+ * const ago = new AgoService({ baseUrl: "https://YOUR-DOMAIN.useago.com" });
+ * ```
+ */
+export declare class AgoService {
+    private client;
+    /** Observable of complete messages */
+    readonly messages$: Observable<AgoMessage>;
+    /** Observable of streaming chunks */
+    readonly chunks$: Observable<{
+        content: string;
+        conversationId: string;
+        messageId: string;
+    }>;
+    /** Observable of errors */
+    readonly errors$: Observable<{
+        error: string;
+        conversationId?: string;
+        messageId?: string;
+    }>;
+    /** Observable of message start events */
+    readonly messageStart$: Observable<{
+        conversationId: string;
+        messageId: string;
+    }>;
+    constructor(config: AgoConfig);
+    /** Create a minimal Observable from an AgoClient event */
+    private fromEvent;
+    /** Send a message and get a streaming response */
+    sendMessage(content: string, options?: SendMessageOptions): Promise<AgoMessage>;
+    /** Get all conversations */
+    getConversations(): Promise<Conversation[]>;
+    /** Get a specific conversation with messages */
+    getConversation(id: 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 */
+    registerFunction(definition: ClientFunctionDefinition): void;
+    registerFunction(name: string, handler: ClientFunctionHandler, schema: Omit<ClientFunctionSchema, "name">): void;
+    /** Unregister a client-side function */
+    unregisterFunction(name: string): boolean;
+    /** Register navigation routes */
+    registerNavigationFunction(navigate: (path: string) => void, routes: Array<{
+        name: string;
+        path: string;
+        description: string;
+    }>): void;
+    /** Subscribe to a client event */
+    on<K extends AgoEventName>(event: K, handler: (data: AgoClientEvents[K]) => void): void;
+    /** Unsubscribe from a client event */
+    off<K extends AgoEventName>(event: K, handler: (data: AgoClientEvents[K]) => void): void;
+    /** Update client config */
+    updateConfig(config: Partial<AgoConfig>): void;
+    /** Get the underlying AgoClient instance */
+    getClient(): AgoClient;
+    /** Destroy the service and clean up resources */
+    destroy(): void;
+}
+
+/**
+ * Knowledge source citation
+ */
+export declare interface AgoSource {
+    id: string;
+    title: string;
+    url?: string;
+}
+
+/**
+ * Single-object function definition — combines name, schema, and handler.
+ *
+ * ```ts
+ * const fn = defineFunction({
+ *   name: "lookupOrder",
+ *   description: "Look up an order by ID",
+ *   parameters: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+ *   handler: async (args) => fetchOrder(args.id as string),
+ * });
+ * client.registerFunction(fn);
+ * ```
+ */
+declare interface ClientFunctionDefinition {
+    name: string;
+    description: string;
+    parameters: ClientFunctionSchema["parameters"];
+    handler: ClientFunctionHandler;
+}
+
+/**
+ * Function handler type
+ */
+declare type ClientFunctionHandler = (args: Record<string, unknown>) => Promise<unknown> | unknown;
+
+declare interface ClientFunctionInvocation {
+    invocationId: string;
+    functionName: string;
+    arguments: Record<string, unknown>;
+    conversationId: string;
+}
+
+/**
+ * Schema for a client-side function that AGO can call
+ */
+declare interface ClientFunctionSchema {
+    /** Function name (must be unique) */
+    name: string;
+    /** Description for the LLM to understand when to call this function */
+    description: string;
+    /** JSON Schema for function parameters */
+    parameters: {
+        type: "object";
+        properties: Record<string, {
+            type: string;
+            description?: string;
+            enum?: string[];
+            default?: unknown;
+        }>;
+        required?: string[];
+    };
+}
+
+/**
+ * A single piece of context the client wants the LLM to know about.
+ */
+declare interface ContextEntry {
+    /** Human-readable label (e.g. "Order detail", "Current user") */
+    name?: string;
+    /** Short description of what this context represents */
+    description?: string;
+    /** Arbitrary structured data the AI should know about */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Serialised client context sent with each message.
+ */
+declare interface ContextSnapshot {
+    /** All active context entries keyed by their registration key */
+    entries: Record<string, ContextEntry>;
+}
+
+/**
+ * Conversation/Thread
+ */
+export declare interface Conversation {
+    id: string;
+    title: string;
+    lastMessageDate: Date;
+    messages?: AgoMessage[];
+}
+
+/**
+ * A function that returns a fresh context entry on demand.
+ * Evaluated every time a message is sent — use it to pull data from stores,
+ * refs, or any source that isn't captured by React state.
+ */
+declare type DynamicContextProvider = () => ContextEntry | null | undefined;
+
+declare interface FormField {
+    type: "string" | "number" | "boolean" | "array";
+    title?: string;
+    description?: string;
+    enum?: string[];
+    default?: unknown;
+}
+
+/**
+ * Form schema for tool calls requiring user input
+ */
+declare interface FormSchema {
+    type: "object";
+    properties: Record<string, FormField>;
+    required?: string[];
+}
+
+declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED";
+
+declare interface Observable<T> {
+    subscribe(observer: {
+        next?: (value: T) => void;
+        error?: (err: unknown) => void;
+    }): {
+        unsubscribe: () => void;
+    };
+}
+
+/**
+ * Factory function that returns an Angular-compatible provider.
+ * Use in your app's `providers` array or `bootstrapApplication`:
+ *
+ * ```ts
+ * import { provideAgo, AgoService } from "@useago/sdk/angular";
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [provideAgo({ baseUrl: "https://YOUR-DOMAIN.useago.com" })],
+ * });
+ *
+ * // Then inject in any component:
+ * const ago = inject(AgoService);
+ * ```
+ *
+ * Returns a provider tuple compatible with Angular's DI.
+ * Since this package avoids a hard Angular dependency, the provider
+ * is returned as a plain object — Angular's injector accepts this format.
+ */
+export declare function provideAgo(options: AgoProvideOptions): {
+    provide: typeof AgoService;
+    useValue: AgoService;
+};
+
+/**
+ * Options for sending a message
+ */
+declare interface SendMessageOptions {
+    /** Existing conversation ID */
+    conversationId?: string;
+    /** Override default agent */
+    agentId?: string;
+    /** File attachments */
+    files?: File[];
+}
+
+/**
+ * Tool call data from SSE stream
+ */
+export declare 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>;
+}
+
+declare type ToolCallType = "form" | "confirmation_input" | "status_message" | "progress_indicator" | "client_function" | "reasoning" | "mcp_ui_resource";
+
+export { }