needle-cloud 2.0.0 → 2.0.1

package/dist/index.d.ts

@@ -147,15 +147,8 @@ type RecentChatsResponse$1 = {
 }
 
 
-/** Tool definition provided by the client for client-side execution. */
-type ClientToolDefinition$1 = {
-    name: string,
-    description: string,
-    parameters?: Record<string, any>,
-}
-
 /** Context block sent by the client (e.g. page metadata, scene hierarchy). */
-type ClientContext$1 = {
+type ClientContext = {
     type: "text",
     text: string,
 }
@@ -183,7 +176,7 @@ type ChatMessage = {
         interrupted?: boolean,
     } | null,
 }
-type AIChatGETResponse$1 = {
+type AIChatGETResponse = {
     chat_id: string,
     messages: Array<ChatMessage>,
     token_usage: AiTokenUsageInfo | null,
@@ -192,7 +185,7 @@ type AIChatGETResponse$1 = {
 }
 
 /** Response type when using stream: false in the request body. */
-type AIChatSyncResponse$1 = {
+type AIChatSyncResponse = {
     chat_id: string,
     message_id: string,
     role: "assistant",
@@ -202,21 +195,154 @@ type AIChatSyncResponse$1 = {
     token_usage?: AiTokenUsageInfo | null,
 }
 
-/** Discriminated union for events yielded by the SSE chat stream. */
-type ChatStreamEvent$1 = { /** SSE event id for position tracking. */ id?: number } & (
+/**
+ * Discriminated union for events yielded by the SSE chat stream.
+ *
+ * **Minimal handling** — for a basic chat UI, handle these:
+ * - `delta` — append to the current message
+ * - `done` — message complete, read `token_usage` for limits
+ * - `error` — display error to user
+ *
+ * **Full handling** — for a complete implementation:
+ * - `delta` / `message` — streaming text chunks / complete message text
+ * - `message_id` — server-assigned ID for the AI message (for storage/reference)
+ * - `chat_id` — server-assigned chat ID (emitted on first message when chat is created)
+ * - `tool_call` / `tool_result` — AI called a tool; tool returned a result (for UI status indicators)
+ * - `status` — human-readable status text (e.g. "Searching docs...", "Thinking...")
+ * - `stopped` — generation was interrupted by the user (via `interruptChat()`)
+ * - `done` — stream finished; includes `token_usage` with current usage/limits
+ * - `error` — something went wrong; `message` contains the error description
+ */
+type ChatStreamEvent = { /** SSE event id for position tracking. */ id?: number } & (
+    /** Streaming text chunk — append to the current AI message. */
     | { type: "delta", content: string }
+    /** Complete message text (sent once at the end, contains the full response). */
     | { type: "message", content: string }
+    /** Server-assigned message ID for the AI response. */
     | { type: "message_id", message_id: string }
+    /** The AI invoked a tool. Use for UI indicators (e.g. "Running get_screenshot..."). */
     | { type: "tool_call", name: string, args: Record<string, any> }
+    /** A tool finished executing. The AI will continue generating with the result. */
     | { type: "tool_result", name: string }
-    | { type: "client_tool_request", request_id: string, name: string, args: Record<string, any> }
+    /** An error occurred. Display `message` to the user. */
     | { type: "error", message: string }
+    /** Generation was interrupted by the user (via `interruptChat()`). */
     | { type: "stopped" }
+    /** Informational status update (e.g. "Searching documentation..."). */
     | { type: "status", message: string }
+    /** Stream complete. `token_usage` contains current usage and remaining quota. */
     | { type: "done", token_usage: AiTokenUsageInfo }
+    /** Server-assigned chat ID (emitted when a new chat is created on the first message). */
     | { type: "chat_id", chat_id: string }
 )
 
+
+// ─── WebSocket Tool Connection Types ────────────────────────────────
+
+/** Tool definition for registering tools via WebSocket. */
+type ToolDefinition$1 = {
+    name: string,
+    description: string,
+    inputSchema: Record<string, any>,
+}
+
+
+// ─── ChatSession Types ──────────────────────────────────────────────
+
+/**
+ * Options for `createChatSession()`.
+ *
+ * A ChatSession coordinates HTTP chat requests and an optional WebSocket
+ * tool connection into a single abstraction. If `tools` are provided,
+ * the session connects via WebSocket and waits for tool registration
+ * before allowing messages. If no tools are provided, it's HTTP-only.
+ */
+type ChatSessionOptions$1 = {
+    /** Source identifier (e.g. "editor", "cli", "my-app"). Defaults to "sdk". */
+    source?: string,
+    /** Tools to register via WebSocket. If empty/omitted, no WS connection is made. */
+    tools?: ToolDefinition$1[],
+    /**
+     * Called when the server requests tool execution.
+     * Return `{ result: ... }` on success or `{ error: "..." }` on failure.
+     * Required if `tools` is non-empty.
+     */
+    onToolRequest?: (name: string, args: Record<string, any>) => Promise<{ result?: any, error?: string }>,
+    /**
+     * How long (ms) to wait for the WebSocket to connect and register tools
+     * before `ready` rejects. Defaults to 5000. Set to 0 to skip WS entirely.
+     */
+    toolReadyTimeout?: number,
+    /** Use personal chat context instead of team. Defaults to false (team). */
+    personal?: boolean,
+}
+
+/**
+ * A coordinated chat session that manages both HTTP chat and WebSocket tool connections.
+ *
+ * Created via `createChatSession()`. The `ready` promise resolves once the session
+ * is fully initialized (WS connected + tools registered, or immediately if no tools).
+ *
+ * @example
+ * ```js
+ * const session = createChatSession(authArgs, {
+ *     tools: [{ name: "screenshot", description: "Take screenshot", inputSchema: {} }],
+ *     onToolRequest: async (name, args) => ({ result: "data..." }),
+ * });
+ *
+ * await session.ready;
+ *
+ * for await (const event of session.sendMessage("my-chat", "Hello")) {
+ *     if (event.type === "delta") process.stdout.write(event.content);
+ * }
+ *
+ * session.close();
+ * ```
+ */
+type ChatSessionHandle$1 = {
+    /**
+     * Resolves when the session is ready to send messages.
+     * - With tools: resolves after WS connects and tools are registered.
+     * - Without tools: resolves immediately.
+     * Rejects if the WS connection fails or `toolReadyTimeout` is exceeded.
+     */
+    readonly ready: Promise<void>,
+    /**
+     * Send a message to a chat. Returns an async generator of stream events.
+     * Internally awaits `ready` before sending.
+     */
+    sendMessage(slug: string, message: string, options?: ChatSessionSendOptions$1): AsyncGenerator<ChatStreamEvent>,
+    /**
+     * Send a message and get a single JSON response (non-streaming).
+     * Internally awaits `ready` before sending.
+     */
+    sendMessageSync(slug: string, message: string, options?: ChatSessionSendOptions$1): Promise<AIChatSyncResponse>,
+    /** Interrupt an active AI generation for the given chat slug. */
+    interruptChat(slug: string): Promise<void>,
+    /** Read chat history for a slug. */
+    readChat(slug: string, options?: { offset?: number, limit?: number }): Promise<AIChatGETResponse>,
+    /** List recent chats. */
+    listChats(): Promise<RecentChatsResponse$1>,
+    /** Update the tools registered with the server. No-op if no WS connection. */
+    updateTools(tools: ToolDefinition$1[]): void,
+    /** Most recent token usage info, auto-updated from `done` events. Null until first message completes. */
+    readonly usage: AiTokenUsageInfo | null,
+    /** Whether the WebSocket tool connection is active. Always false if no tools were provided. */
+    readonly toolsConnected: boolean,
+    /** Close the session (WebSocket + cleanup). */
+    close(): void,
+}
+
+/** Options for `ChatSessionHandle.sendMessage()` and `sendMessageSync()`. */
+type ChatSessionSendOptions$1 = {
+    /** Full URL of the page (for context). */
+    full_url?: string,
+    /** Pathname of the page (for context). */
+    pathname?: string,
+    /** Additional context blocks to send with the message. */
+    context?: ClientContext[],
+}
+
 /**
  * @typedef {{ name: string, mimetype: string, buffer:Buffer }} Filelike
  * @typedef {import("../web.types.js").AuthData} AuthData
@@ -353,96 +479,57 @@ type Deployment = {
  */
 declare function listChats(opts?: ChatAuthOpts): Promise<RecentChatsResponse>;
 /**
- * Read an AI chat by slug. Returns JSON with messages by default.
- * When `reconnect: true`, attempts to reconnect to an active SSE stream.
- * @overload
- * @param {string} slug
- * @param {ChatAuthOpts & { offset?: number, limit?: number, personal?: boolean, reconnect?: false }} [opts]
- * @returns {Promise<AIChatGETResponse>}
- */
-declare function readChat(slug: string, opts?: ChatAuthOpts & {
-    offset?: number;
-    limit?: number;
-    personal?: boolean;
-    reconnect?: false;
-}): Promise<AIChatGETResponse>;
-/**
- * @overload
- * @param {string} slug
- * @param {ChatAuthOpts & { personal?: boolean, reconnect: true, signal?: AbortSignal }} opts
- * @returns {Promise<AsyncGenerator<ChatStreamEvent> | null>}
- */
-declare function readChat(slug: string, opts: ChatAuthOpts & {
-    personal?: boolean;
-    reconnect: true;
-    signal?: AbortSignal;
-}): Promise<AsyncGenerator<ChatStreamEvent> | null>;
-/**
- * Send a message to an AI chat.
- * @overload
- * @param {string} slug
- * @param {string} message
- * @param {ChatAuthOpts & { stream?: false, source?: string, personal?: boolean, full_url?: string, pathname?: string, client_tools?: ClientToolDefinition[], context?: ClientContext[] }} [opts]
- * @returns {Promise<AIChatSyncResponse>}
- */
-declare function sendChatMessage(slug: string, message: string, opts?: ChatAuthOpts & {
-    stream?: false;
-    source?: string;
-    personal?: boolean;
-    full_url?: string;
-    pathname?: string;
-    client_tools?: ClientToolDefinition[];
-    context?: ClientContext[];
-}): Promise<AIChatSyncResponse>;
-/**
- * @overload
- * @param {string} slug
- * @param {string} message
- * @param {ChatAuthOpts & { stream: true, source?: string, personal?: boolean, full_url?: string, pathname?: string, client_tools?: ClientToolDefinition[], context?: ClientContext[] }} opts
- * @returns {Promise<AsyncGenerator<ChatStreamEvent>>}
- */
-declare function sendChatMessage(slug: string, message: string, opts: ChatAuthOpts & {
-    stream: true;
-    source?: string;
-    personal?: boolean;
-    full_url?: string;
-    pathname?: string;
-    client_tools?: ClientToolDefinition[];
-    context?: ClientContext[];
-}): Promise<AsyncGenerator<ChatStreamEvent>>;
-/**
- * Interrupt an active AI generation for the given chat slug.
- * @param {string} slug
- * @param {ChatAuthOpts & { personal?: boolean }} [opts]
- * @returns {Promise<void>}
- */
-declare function interruptChat(slug: string, opts?: ChatAuthOpts & {
-    personal?: boolean;
-}): Promise<void>;
-/**
- * Submit a client-side tool execution result back to the server.
- * Call this when you receive a `client_tool_request` event from the SSE stream.
- * @param {string} requestId - The `request_id` from the `client_tool_request` event
- * @param {{ result?: any, error?: string }} outcome - The tool result or error
- * @param {ChatAuthOpts & { personal?: boolean }} [opts]
- * @returns {Promise<void>}
+ * Create a coordinated chat session with optional WebSocket tool support.
+ *
+ * This is the primary API for interacting with Needle Cloud AI chat.
+ * It combines HTTP chat requests and an optional WebSocket tool connection
+ * into a single abstraction.
+ *
+ * If `tools` are provided, the session connects via WebSocket and waits
+ * for tool registration before allowing messages. If no tools are provided,
+ * it's HTTP-only.
+ *
+ * @example
+ * ```js
+ * import { createChatSession } from "needle-cloud";
+ *
+ * // Simple chat (no tools)
+ * const session = await createChatSession();
+ * await session.ready;
+ * for await (const event of session.sendMessage("my-chat", "Hello")) {
+ *     if (event.type === "delta") process.stdout.write(event.content);
+ * }
+ * session.close();
+ * ```
+ *
+ * @example
+ * ```js
+ * // Chat with tools
+ * const session = await createChatSession({
+ *     tools: [{ name: "screenshot", description: "Take screenshot", inputSchema: {} }],
+ *     onToolRequest: async (name, args) => ({ result: "data" }),
+ * });
+ * await session.ready; // waits for WS + tool registration
+ * for await (const event of session.sendMessage("my-chat", "Take a screenshot")) {
+ *     if (event.type === "delta") process.stdout.write(event.content);
+ * }
+ * session.close();
+ * ```
+ *
+ * @param {import("@needle-tools/cloud-sdk/types/api.ai.js").ChatSessionOptions} [options]
+ * @param {ChatAuthOpts} [authOpts]
+ * @returns {Promise<import("@needle-tools/cloud-sdk/types/api.ai.js").ChatSessionHandle>}
  */
-declare function submitToolResult(requestId: string, outcome: {
-    result?: any;
-    error?: string;
-}, opts?: ChatAuthOpts & {
-    personal?: boolean;
-}): Promise<void>;
+declare function createChatSession(options?: ChatSessionOptions$1, authOpts?: ChatAuthOpts): Promise<ChatSessionHandle$1>;
 type ChatAuthOpts = {
     org?: string;
     authToken?: string;
 };
 type RecentChatsResponse = RecentChatsResponse$1;
-type AIChatGETResponse = AIChatGETResponse$1;
-type ChatStreamEvent = ChatStreamEvent$1;
-type ClientToolDefinition = ClientToolDefinition$1;
-type ClientContext = ClientContext$1;
-type AIChatSyncResponse = AIChatSyncResponse$1;
+type ChatSessionOptions = ChatSessionOptions$1;
+type ChatSessionHandle = ChatSessionHandle$1;
+type ChatSessionSendOptions = ChatSessionSendOptions$1;
+type ToolDefinition = ToolDefinition$1;
 
 /**
  * Start the checkout process
@@ -461,5 +548,5 @@ declare namespace AuthScopes {
     let All: string[];
 }
 
-export { Auth, AuthScopes, NeedleLoginButton, getDeployments, getUserLicenses, interruptChat, listChats, ownsProduct, readChat, sendChatMessage, startCheckoutSession, submitToolResult, uploadFiles };
-export type { AIChatGETResponse, AIChatSyncResponse, AuthData, AuthInitOpts, ChatAuthOpts, ChatStreamEvent, ClientContext, ClientToolDefinition, Deployment, Filelike, LogtoUserCustomData, RecentChatsResponse, ResourceUrl, UserInfoResponse };
+export { Auth, AuthScopes, NeedleLoginButton, createChatSession, getDeployments, getUserLicenses, listChats, ownsProduct, startCheckoutSession, uploadFiles };
+export type { AuthData, AuthInitOpts, ChatAuthOpts, ChatSessionHandle, ChatSessionOptions, ChatSessionSendOptions, Deployment, Filelike, LogtoUserCustomData, RecentChatsResponse, ResourceUrl, ToolDefinition, UserInfoResponse };