@butlerbot/sdk 0.0.18-alpha.2 → 0.0.18

package/dist/modules/transport_sse.d.ts

@@ -0,0 +1,28 @@
+import { EventSource } from "eventsource";
+import { ConversationStream, ConversationTransport, TransportHandlers, TransportTurnRequest } from "./transport";
+type StreamOptions = {
+    debug?: boolean;
+    onPayload(payload: {
+        success: boolean;
+        data?: {
+            convoId?: string;
+            quitStream?: boolean;
+        };
+    }): void;
+};
+/**
+ * Streams a server-sent-events endpoint, closing when the server says the stream is
+ * done. Shared by turns and by the progress stream, which is SSE-only.
+ */
+export declare function streamSSE(url: string, options: StreamOptions): EventSource;
+/** Carries a turn over the HTTP chat endpoint. The default. */
+export declare class SSEConversationTransport implements ConversationTransport {
+    private readonly config;
+    constructor(config: {
+        endpoint(): string;
+        apiKey: string;
+        debug?: boolean;
+    });
+    send(request: TransportTurnRequest, handlers: TransportHandlers): ConversationStream;
+}
+export {};

package/dist/modules/transport_sse.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SSEConversationTransport = void 0;
+exports.streamSSE = streamSSE;
+const eventsource_1 = require("eventsource");
+const url_formatter_1 = require("../util/url_formatter");
+/**
+ * Streams a server-sent-events endpoint, closing when the server says the stream is
+ * done. Shared by turns and by the progress stream, which is SSE-only.
+ */
+function streamSSE(url, options) {
+    const sse = new eventsource_1.EventSource(url);
+    sse.addEventListener("message", (event) => {
+        const payload = JSON.parse(event.data);
+        options.onPayload(payload);
+        if (payload.data?.quitStream)
+            sse.close();
+    });
+    sse.addEventListener("error", (event) => {
+        if (options.debug)
+            console.warn(`[Stream Error: ${url}]`, event);
+    });
+    return sse;
+}
+/** Carries a turn over the HTTP chat endpoint. The default. */
+class SSEConversationTransport {
+    constructor(config) {
+        this.config = config;
+    }
+    send(request, handlers) {
+        const url = (0, url_formatter_1.formatURL)(this.config.endpoint(), asQuery(request), { apiKey: this.config.apiKey, debug: this.config.debug });
+        const sse = streamSSE(url, {
+            debug: this.config.debug,
+            onPayload: (payload) => {
+                const convoId = payload.success ? payload.data?.convoId : undefined;
+                if (convoId)
+                    handlers.convoId(convoId);
+                handlers.payload(payload);
+            },
+        });
+        return { close: () => sse.close(), source: sse };
+    }
+}
+exports.SSEConversationTransport = SSEConversationTransport;
+function asQuery(request) {
+    const query = { message: request.message };
+    if (request.chatId)
+        query.chatId = request.chatId;
+    if (request.model)
+        query.model = request.model;
+    if (request.instructions)
+        query.instructions = request.instructions;
+    if (request.platform)
+        query.platform = request.platform;
+    if (request.personality)
+        query.personality = request.personality;
+    return query;
+}

package/dist/modules/usage.js

@@ -1,34 +1,23 @@
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUsagePolicyData = getUsagePolicyData;
 const config_1 = require("../config");
 const url_formatter_1 = require("../util/url_formatter");
 /** Fetches the current usage policy data from the server */
-function getUsagePolicyData(options) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const useEndpoint = (options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.usage.policy.v3.base);
-        const url = (0, url_formatter_1.formatURL)(useEndpoint, {}, { apiKey: options.apiKey, debug: options.debug });
-        const response = yield fetch(url);
-        const data = yield response.json();
-        if (!response.ok) {
-            const errorText = yield response.text();
-            throw new Error(`Failed to fetch usage policy data: ${response.status} ${response.statusText} - ${errorText}`);
-        }
-        if (!data.success) {
-            throw new Error(`API error while fetching usage policy data: ${data.error || 'Unknown error'}`);
-        }
-        if (!data.policy) {
-            throw new Error(`API error while fetching usage policy data: ${data.error || 'Unknown error'}`);
-        }
-        return data.policy;
-    });
+async function getUsagePolicyData(options) {
+    const useEndpoint = (options.serverURL || config_1.CONFIG.server) + (options.path || config_1.CONFIG.paths.usage.policy.v3.base);
+    const url = (0, url_formatter_1.formatURL)(useEndpoint, {}, { apiKey: options.apiKey, debug: options.debug });
+    const response = await fetch(url);
+    const data = await response.json();
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Failed to fetch usage policy data: ${response.status} ${response.statusText} - ${errorText}`);
+    }
+    if (!data.success) {
+        throw new Error(`API error while fetching usage policy data: ${data.error || 'Unknown error'}`);
+    }
+    if (!data.policy) {
+        throw new Error(`API error while fetching usage policy data: ${data.error || 'Unknown error'}`);
+    }
+    return data.policy;
 }

package/dist/types/conversation/v4/conversation_v4.d.ts

@@ -0,0 +1,50 @@
+import type { MessagePayload, ReasoningPayload, FilePayload, ToolPayload, ConvoStatusPayload, ResponseStatusPayload, BaseResponseMetadata, DisplayEntity } from "../../response/v5/ai_response_v5";
+import type { ConversationMessage } from "./message_v4";
+export type DialogueEntry = {
+    from: "user" | "assistant";
+    display?: DisplayEntity;
+    timestamp: number;
+    metadata?: BaseResponseMetadata;
+} & ({
+    type: "message";
+    payload: MessagePayload;
+} | {
+    type: "reasoning";
+    payload: ReasoningPayload;
+} | {
+    type: "file";
+    payload: FilePayload;
+} | {
+    type: "tool";
+    payload: ToolPayload;
+} | {
+    type: "convo_status";
+    payload: ConvoStatusPayload;
+} | {
+    type: "response_status";
+    payload: ResponseStatusPayload;
+});
+export type ConversationState = {
+    settings: {
+        model?: string;
+        title?: string;
+        system?: string;
+        location?: string;
+        locationInstructions?: string;
+        temperature?: number;
+        disableAutoTitle?: boolean;
+    };
+    summary?: {
+        shortSummary?: string;
+        longSummary?: string;
+    };
+    messages: ConversationMessage[];
+    dialogue: DialogueEntry[];
+};
+export interface ConversationV4 {
+    version: "4.0";
+    conversationId: string;
+    ownerUserId: string;
+    disableView?: boolean;
+    state: ConversationState;
+}

package/dist/types/conversation/v4/conversation_v4.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/conversation/v4/message_v4.d.ts

@@ -0,0 +1,85 @@
+export type ConversationMessageContentText = {
+    type: "input_text";
+    text: string;
+};
+export type ConversationMessageContentOutputText = {
+    type: "output_text";
+    text: string;
+};
+export type ConversationMessageMeta = {
+    participantId?: string;
+    attributedUserId?: string;
+    summarized?: unknown;
+    timestamp?: number;
+};
+export type ConversationMessage = {
+    type: "user_message";
+    role: "user";
+    content: string | ConversationMessageContentText[];
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "system_message";
+    role: "system";
+    content: string;
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "assistant_message";
+    role: "assistant";
+    content: ConversationMessageContentOutputText[];
+    id: string;
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "function_call";
+    name: string;
+    arguments: string;
+    callId: string;
+    id?: string;
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "function_call_output";
+    callId: string;
+    output: string;
+    id?: string;
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "reasoning";
+    content: Array<{
+        text: string;
+        type?: string;
+    }>;
+    summary?: Array<{
+        text: string;
+        type?: string;
+    }>;
+    id: string;
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "web_search_call";
+    id: string;
+    status: string;
+    action: Record<string, unknown>;
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "file_search_call";
+    id: string;
+    queries: string[];
+    status: string;
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "image_generation_call";
+    id: string;
+    result?: string;
+    status: string;
+    image?: {
+        b64_json?: string;
+        url?: string;
+        media_type?: string;
+    };
+    ai4?: ConversationMessageMeta;
+} | {
+    type: "server_tool_item";
+    id: string;
+    outputType: string;
+    output: Record<string, unknown>;
+    ai4?: ConversationMessageMeta;
+};

package/dist/types/conversation/v4/message_v4.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/state/convo_state_response.d.ts

@@ -1,9 +1,10 @@
 import { ConversationV1 } from "../conversation/v1/conversation_v1";
 import { ConversationV2 } from "../conversation/v2/conversation_v2";
 import { ConversationV3 } from "../conversation/v3/conversation_v3";
+import { ConversationV4 } from "../conversation/v4/conversation_v4";
 export type ConversationStateResponse = {
     success: true;
-    conversation: ConversationV1 | ConversationV2 | ConversationV3;
+    conversation: ConversationV1 | ConversationV2 | ConversationV3 | ConversationV4;
 } | {
     success: false;
     error: string;

package/dist/types/type_registry.d.ts

@@ -1,4 +1,6 @@
 export * from "./response/v3";
 export * from "./response/v4";
 export * from "./response/v5";
+export * from "./state/convo_state_response";
+export * from "./conversation/v4/conversation_v4";
 export * from "./error";

package/dist/types/type_registry.js

@@ -17,4 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./response/v3"), exports);
 __exportStar(require("./response/v4"), exports);
 __exportStar(require("./response/v5"), exports);
+__exportStar(require("./state/convo_state_response"), exports);
+__exportStar(require("./conversation/v4/conversation_v4"), exports);
 __exportStar(require("./error"), exports);

package/dist/util/emitter.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A tiny typed event emitter.
+ *
+ * `on` returns an id used to remove the listener again, which is the convention
+ * the SDK already used for conversation events.
+ */
+export declare class Emitter<Events extends Record<string, unknown[]>> {
+    private listeners;
+    private nextId;
+    on<K extends keyof Events>(event: K, listener: (...args: Events[K]) => unknown): string;
+    once<K extends keyof Events>(event: K, listener: (...args: Events[K]) => unknown): string;
+    off<K extends keyof Events>(event: K, id: string): void;
+    emit<K extends keyof Events>(event: K, ...args: Events[K]): void;
+    clear(event?: keyof Events): void;
+}

package/dist/util/emitter.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Emitter = void 0;
+/**
+ * A tiny typed event emitter.
+ *
+ * `on` returns an id used to remove the listener again, which is the convention
+ * the SDK already used for conversation events.
+ */
+class Emitter {
+    constructor() {
+        this.listeners = new Map();
+        this.nextId = 0;
+    }
+    on(event, listener) {
+        let forEvent = this.listeners.get(event);
+        if (!forEvent) {
+            forEvent = new Map();
+            this.listeners.set(event, forEvent);
+        }
+        const id = `l${++this.nextId}`;
+        forEvent.set(id, listener);
+        return id;
+    }
+    once(event, listener) {
+        const id = this.on(event, ((...args) => {
+            this.off(event, id);
+            return listener(...args);
+        }));
+        return id;
+    }
+    off(event, id) {
+        this.listeners.get(event)?.delete(id);
+    }
+    emit(event, ...args) {
+        const forEvent = this.listeners.get(event);
+        if (!forEvent)
+            return;
+        // Copied first: a listener may remove itself, or another, while we iterate.
+        for (const listener of Array.from(forEvent.values())) {
+            listener(...args);
+        }
+    }
+    clear(event) {
+        if (event === undefined)
+            this.listeners.clear();
+        else
+            this.listeners.delete(event);
+    }
+}
+exports.Emitter = Emitter;

package/dist/util/url_formatter.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatURL = formatURL;
 function formatURL(url, params = {}, config) {
-    const fParams = Object.assign({ api_key: config.apiKey }, params);
+    const fParams = {
+        api_key: config.apiKey,
+        ...params
+    };
     const paramQuery = new URLSearchParams(fParams).toString();
     const fUrl = `${url}?${paramQuery}`;
     if (config.debug) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.18-alpha.2",
+	"version": "0.0.18",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -12,34 +12,58 @@
 		"pack": "npm run build && npm pack --pack-destination=\"G:\\tarballs\"",
 		"update": "npm run build && npm publish --access public",
 		"update:alpha": "npm run build && npm publish --access public --tag alpha",
-		"test": "jest"
+		"test": "bun test",
+		"typecheck": "tsc --noEmit -p tsconfig.check.json"
 	},
 	"keywords": [
-		"butlerbot",
+		"agents",
+		"ai",
 		"alfred",
-		"sdk",
+		"butler",
+		"butlerbot",
 		"chatbot",
-		"ai",
-		"butler"
+		"sdk",
+		"tools",
+		"websocket"
 	],
 	"author": "Fragly",
 	"license": "MIT",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/isdevco/alfred5_sdk.git"
+		"url": "git+https://github.com/butlerbots/alfred5_sdk.git"
 	},
 	"bugs": {
-		"url": "https://github.com/isdevco/alfred5_sdk/issues"
+		"url": "https://github.com/butlerbots/alfred5_sdk/issues"
 	},
 	"homepage": "https://butlerbot.net",
 	"engines": {
-		"node": ">=14.0.0"
+		"node": ">=18.0.0"
 	},
 	"devDependencies": {
+		"@types/bun": "^1.1.0",
 		"@types/node": "^22.13.10",
-		"typescript": "^5.8.2"
+		"typescript": "^5.8.2",
+		"zod": "^4.0.0"
 	},
 	"dependencies": {
 		"eventsource": "^3.0.5"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"peerDependencies": {
+		"zod": ">=3.24.0",
+		"ws": ">=8.0.0"
+	},
+	"peerDependenciesMeta": {
+		"zod": {
+			"optional": true
+		},
+		"ws": {
+			"optional": true
+		}
 	}
 }

package/readme.md

@@ -16,7 +16,7 @@ npm i @butlerbot/sdk
 
 - ButlerBot API key
 
-## Example
+## Talking to Alfred
 
 ```typescript
 import { ButlerBotClient } from "@butlerbot/sdk";
@@ -34,3 +34,128 @@ convo.send("Hey there Alfred!", (res) => {
   console.log(type, payload); // message { message: "Good day", ... }
 });
 ```
+
+Or, when you only want the answer:
+
+```typescript
+const { text } = await convo.ask("Hey there Alfred!");
+```
+
+## Link
+
+A Link is a live connection to Alfred. It does three things:
+
+- **Tools** — Alfred calls code that runs on your machine
+- **Hooks** — your code wakes the user's background agents when something happens
+- **Conversations** — turns are carried over the same connection instead of an HTTP stream
+
+```typescript
+import { ButlerBotClient, Tool, Hook } from "@butlerbot/sdk";
+import { z } from "zod";
+
+const client = new ButlerBotClient({ apiKey: "your_api_key_here" });
+const link = client.createLink({ linkId: "coffee-machine" });
+
+link.addTool(new Tool({
+  id: "brew",
+  description: "Brew a coffee for the user",
+  schema: z.object({ cups: z.number().int().min(1).max(4) }),
+  run: async ({ args, status }) => {
+    status.update("Grinding beans");
+    return `Brewed ${args.cups} cup(s).`;   // args is typed from the schema
+  },
+}));
+
+const waterLow = new Hook({
+  id: "water-low",
+  name: "Water tank low",
+  description: "Fires when the water tank drops below a quarter full",
+  events: [{ name: "low", description: "The tank needs refilling" }],
+});
+link.addHook(waterLow);
+
+await link.connect();
+await waterLow.emit("low", { level: 0.2 });
+```
+
+See [`examples/link.ts`](./examples/link.ts) for a fuller version.
+
+### linkId is permanent
+
+`linkId` is yours to choose and must never change. Every id the link creates is derived
+from it (`link:coffee-machine/brew`), and those ids are what the user's saved tool
+settings and background agent subscriptions point at — so changing it silently orphans
+both. Pick a deliberate constant; never a hostname, a version, or something generated at
+startup.
+
+Nothing else is stored on either side: the server keeps no record of a link between
+connections, and the SDK re-declares everything on connect. A link can reconnect from
+anywhere and land on the same settings.
+
+Two live connections using the same `linkId` is last-writer-wins — the newer one takes
+over and the older one's registrations are released. That is deliberate, so a half-dead
+socket cannot lock out a fresh one during a deploy, but it does mean two genuinely
+different clients must not share an id.
+
+### Tools belong to the user, not to a conversation
+
+Once a tool is registered, Alfred can call it anywhere that user talks to it — the web
+app and Discord included, not just conversations you started. `defaultEnabled` decides
+whether it is on before the user has touched it; after that their own setting wins.
+
+### Schemas
+
+`schema` takes a [zod](https://zod.dev) 4 schema, any
+[Standard Schema](https://standardschema.dev), or a plain JSON Schema object. The SDK has
+no dependency on any of them.
+
+With a schema that can validate, arguments are checked before your tool runs (the server
+deliberately doesn't — you wrote the schema, so you own the check) and `args` is typed
+from it. With zod 3, pass `jsonSchema` alongside `schema`, since zod 3 cannot produce
+JSON Schema itself.
+
+## Conversations over a Link
+
+Pass a connected Link as the transport. Everything else is identical — the same methods,
+the same payloads — so nothing that consumes a conversation needs to change:
+
+```typescript
+const convo = client.createConversation({ transport: link });    // over the websocket
+const overHttp = client.createConversation();                    // over SSE, the default
+```
+
+Which to use:
+
+- **SSE** is the simplest thing that works and needs no connection to manage. Best for a
+  one-off request, a serverless function, or a page that just wants an answer.
+- **A Link** reuses a connection you already have and avoids a new HTTP stream per turn.
+  Best when you are already running a link for tools or hooks, or holding many
+  conversations at once — one socket carries them all.
+
+Two differences to know about:
+
+- Sessions are ephemeral. If the connection drops mid-turn the SDK reopens the session
+  and resends transparently; the conversation itself is persisted server-side, so
+  nothing is lost.
+- The HTTP transport replays your own message back to you (it exists so a browser
+  reconnecting mid-turn sees it). A Link does not, since it has nothing to replay.
+
+Neither transport can cancel a turn: `close()` stops delivery locally, and the reply is
+still generated and stored.
+
+## Environment
+
+Node 18+. Node 22 and every browser have a built-in WebSocket; on older Node, install
+`ws` or pass your own `socketFactory`.
+
+Browsers are supported: a websocket handshake cannot carry headers there, so the SDK
+sends the service and credential as subprotocols instead of putting the key in the URL.
+
+## Development
+
+```bash
+npm install
+npm test         # bun test
+npm run typecheck
+npm run build
+```