@butlerbot/sdk 0.0.1-alpha1

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export declare const CONFIG: {
+    server: string;
+    healthcheckPath: string;
+    paths: {
+        conversation: {
+            v3: {
+                base: string;
+            };
+        };
+    };
+};

package/dist/config.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG = void 0;
+exports.CONFIG = {
+    server: "https://core.butlerbot.net",
+    healthcheckPath: "/api/healthcheck",
+    paths: {
+        conversation: {
+            v3: { base: "/api/alfred/v3/chat" }
+        }
+    }
+};

package/dist/examples/simple_message.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const src_1 = require("../src");
+const client = new src_1.ButlerBotClient({
+    apiKey: "your_api_key_here"
+});
+const convo = client.createConversation();
+convo.send("Hello, world!", (response) => {
+    console.log(response);
+});

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { Conversation, ConversationOptions } from "./modules/conversation";
+type OptionalApiKey<T> = Omit<T, "apiKey"> & {
+    /** Optional API key, defaults to API key specified in client */
+    apiKey?: string;
+};
+export type ButlerBotClientOptions = {
+    /** The server endpoint, API calls are sent here */
+    serverUrl?: string;
+    /** The API key to use with ButlerBot */
+    apiKey: string;
+    /** Whether to enable debug logs */
+    debug?: boolean;
+};
+export declare class ButlerBotClient {
+    private apiKey;
+    private serverUrl;
+    private debug;
+    constructor(config: ButlerBotClientOptions);
+    /** Checks the health of the server returning true if server is alive */
+    healthCheck(healthCheckPath?: string): Promise<boolean>;
+    /** Spawns a new Conversation, inherits api key and server URL */
+    createConversation(config?: OptionalApiKey<ConversationOptions>): Conversation;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,41 @@
+"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.ButlerBotClient = void 0;
+const config_1 = require("./config");
+const conversation_1 = require("./modules/conversation");
+class ButlerBotClient {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.serverUrl = config.serverUrl || config_1.CONFIG.server;
+        this.debug = config.debug || false;
+    }
+    /** Checks the health of the server returning true if server is alive */
+    healthCheck() {
+        return __awaiter(this, arguments, void 0, function* (healthCheckPath = config_1.CONFIG.healthcheckPath) {
+            const url = `${this.serverUrl}${healthCheckPath}`;
+            try {
+                const response = yield fetch(url);
+                return response.ok;
+            }
+            catch (error) {
+                if (this.debug)
+                    console.warn("[Healthcheck Failure]", error);
+                return false;
+            }
+        });
+    }
+    /** Spawns a new Conversation, inherits api key and server URL */
+    createConversation(config = {}) {
+        return new conversation_1.Conversation(Object.assign({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl }, config));
+    }
+}
+exports.ButlerBotClient = ButlerBotClient;

package/dist/modules/conversation.d.ts

@@ -0,0 +1,36 @@
+import { RequestResponse } from "../types/dialogue_response_v3";
+export type DialogueRequestParams = {
+    /** Unique identifier for the chat session */
+    chatId?: string;
+    /** The message to be sent to the AI */
+    message: string;
+    /** AI model to use for generating responses */
+    model?: string;
+    /** Additional instructions for location-specific context */
+    instructions?: string;
+    /** Platform where the chat is occurring */
+    platform?: string;
+    /** Custom personality configuration for the AI */
+    personality?: string;
+};
+export type ConversationOptions = {
+    /** The conversation ID to load the conversation from, server will error if this convo id doesn't exist */
+    convoId?: string;
+    /** The API key to use */
+    apiKey: string;
+    /** The server URL to use */
+    serverUrl?: string;
+    /** The path to append to the server URL specifying the API endpoint to use */
+    path?: string;
+    /** Whether to enable debug logs */
+    debug?: boolean;
+};
+export declare class Conversation {
+    convoId?: string;
+    endpoint: string;
+    apiKey: string;
+    private debug;
+    constructor(config: ConversationOptions);
+    /** Sends a message into the conversation */
+    send(message: string, cb: (chunk: RequestResponse) => any): Promise<void>;
+}

package/dist/modules/conversation.js

@@ -0,0 +1,65 @@
+"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.Conversation = void 0;
+const eventsource_1 = require("eventsource");
+const config_1 = require("../config");
+class Conversation {
+    constructor(config) {
+        this.convoId = config.convoId;
+        this.endpoint = (config.serverUrl || config_1.CONFIG.server) + (config.path || config_1.CONFIG.paths.conversation.v3.base);
+        this.apiKey = config.apiKey;
+        this.debug = config.debug || false;
+    }
+    /** Sends a message into the conversation */
+    send(message, cb) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const params = {
+                message,
+                api_key: this.apiKey
+            };
+            if (this.convoId)
+                params.chatId = this.convoId;
+            const paramQuery = new URLSearchParams(params).toString();
+            const url = `${this.endpoint}?${paramQuery}`;
+            if (this.debug) {
+                const debugUrl = new URL(url);
+                const apiKey = debugUrl.searchParams.get('api_key');
+                if (apiKey) {
+                    const obscuredKey = apiKey.length > 6 ? `${apiKey.slice(0, 3)}...${apiKey.slice(-3)}` : '***';
+                    debugUrl.searchParams.set('api_key', obscuredKey);
+                }
+                console.log(`[Requesting URL ${debugUrl.toString()}]`);
+            }
+            const sse = new eventsource_1.EventSource(url);
+            sse.addEventListener("message", (event) => {
+                const data = JSON.parse(event.data);
+                cb(data);
+                if (data.data.quitStream)
+                    sse.close();
+            });
+            sse.addEventListener("error", (event) => {
+                if (this.debug)
+                    console.warn(`[Stream Error: ${url}]`, event);
+                cb({
+                    success: false,
+                    data: {
+                        code: "STREAM_ERROR",
+                        error: "Stream error",
+                        message: event.message || "An error occurred while streaming",
+                        quitStream: true
+                    }
+                });
+            });
+        });
+    }
+}
+exports.Conversation = Conversation;

package/dist/src/config.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG = void 0;
+exports.CONFIG = {
+    server: "https://core.butlerbot.net",
+    paths: {
+        conversation: {
+            v3: { base: "/api/alfred/v3" }
+        }
+    }
+};

package/dist/src/index.js

@@ -0,0 +1,37 @@
+"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.ButlerBotClient = void 0;
+const conversation_1 = require("./modules/conversation");
+class ButlerBotClient {
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.serverUrl = config.serverUrl;
+    }
+    /** Checks the health of the server returning true if server is alive */
+    healthCheck() {
+        return __awaiter(this, arguments, void 0, function* (healthCheckPath = "/health") {
+            const url = `${this.serverUrl}${healthCheckPath}`;
+            try {
+                const response = yield fetch(url);
+                return response.ok;
+            }
+            catch (error) {
+                return false;
+            }
+        });
+    }
+    /** Spawns a new Conversation, inherits api key and server URL */
+    createConversation(config = {}) {
+        return new conversation_1.Conversation(Object.assign({ apiKey: this.apiKey, serverUrl: this.serverUrl }, config));
+    }
+}
+exports.ButlerBotClient = ButlerBotClient;

package/dist/src/modules/conversation.js

@@ -0,0 +1,43 @@
+"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.Conversation = void 0;
+const config_1 = require("../config");
+class Conversation {
+    constructor(config) {
+        this.convoId = config.convoId;
+        this.endpoint = (config.serverUrl || config_1.CONFIG.server) + (config.path || config_1.CONFIG.paths.conversation.v3.base);
+        this.apiKey = config.apiKey;
+    }
+    /** Sends a message into the conversation */
+    send(message, cb) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const params = {
+                message,
+                api_key: this.apiKey,
+                chatId: this.convoId,
+            };
+            const paramQuery = new URLSearchParams(params).toString();
+            const url = `${this.endpoint}?${paramQuery}`;
+            const sse = new EventSource(url);
+            sse.onmessage = (event) => {
+                const data = JSON.parse(event.data);
+                if (data.payload.quitStream)
+                    sse.close();
+                cb(data);
+            };
+            sse.onerror = (event) => {
+                console.error(event);
+            };
+        });
+    }
+}
+exports.Conversation = Conversation;

package/dist/src/types/ai_response_v3.js

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

package/dist/src/types/dialogue_response_v3.js

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

package/dist/src/types/error.js

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

package/dist/types/ai_response_v3.d.ts

@@ -0,0 +1,59 @@
+import { ErrorCode } from "./error";
+type AIChatResultFail = {
+    success: false;
+    errorcode: ErrorCode;
+};
+type AIChatResultSuccess = {
+    success: true;
+    response: AIResponse[];
+    usage: any;
+};
+export type AIChatResult = AIChatResultFail | AIChatResultSuccess;
+type BaseAIResponseMetadata = {
+    /** The model that generated this message */
+    model: string;
+    /** The actual model ID that generated this message */
+    modelId: string;
+    /** Epoch time for when this happened */
+    timestamp: number;
+};
+type AIMessageResponse = {
+    /** Specifies type to be a message */
+    type: "message";
+    payload: {
+        /** Message to send to the user */
+        message: string;
+        /** The associated message id */
+        messageId: string;
+        /** Whether this message was completed */
+        completed: boolean;
+    };
+    metadata: BaseAIResponseMetadata & {};
+};
+type AIResponseStatusResponse = {
+    /** Specifies type to be a status update for the response */
+    type: "response_status";
+    payload: {
+        /** Whether the entire AI response is completed */
+        completed: boolean;
+    };
+};
+type AIConvoStatusResponse = {
+    /** Specifies type to be a status update for the conversation */
+    type: "convo_status";
+    payload: {
+        /** Whether the entire AI convo has been disabled, a disabled convo cannot be restarted */
+        disabled: boolean;
+        /** Whether the AI convo has been stopped, a stopped convo can be restarted
+         * although just because it's not stopped does not necasserily mean it's an ongoing conversation */
+        stopped: boolean;
+    };
+};
+type AIToolResponse = {
+    /** Specifies type to be a tool use status update */
+    type: "tool";
+    payload: {};
+    metadata: BaseAIResponseMetadata & {};
+};
+export type AIResponse = AIMessageResponse | AIToolResponse | AIConvoStatusResponse | AIResponseStatusResponse;
+export {};

package/dist/types/ai_response_v3.js

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

package/dist/types/dialogue_response_v3.d.ts

@@ -0,0 +1,28 @@
+import { AIResponse } from "./ai_response_v3";
+import { ErrorCode } from "./error";
+type RequestBaseResponsePayload = {
+    /** Whether the conversation's ending */
+    end?: boolean;
+    /** Whether the stream is ending */
+    quitStream?: boolean;
+};
+export type RequestFailResponse = {
+    success: false;
+    data: {
+        /** Error code */
+        code: ErrorCode;
+        /** Error message */
+        error: string;
+        /** User facing message */
+        message: string;
+    } & RequestBaseResponsePayload;
+};
+export type RequestSucessResponse = {
+    success: true;
+    data: {
+        /** The AI's response */
+        response: AIResponse;
+    } & RequestBaseResponsePayload;
+};
+export type RequestResponse = RequestFailResponse | RequestSucessResponse;
+export {};

package/dist/types/dialogue_response_v3.js

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

package/dist/types/error.d.ts

@@ -0,0 +1 @@
+export type ErrorCode = string;

package/dist/types/error.js

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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@butlerbot/sdk",
+  "version": "0.0.1-alpha1",
+  "description": "The official ButlerBot SDK",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "pack": "npm run build && npm pack --pack-destination=\"G:\\tarballs\"",
+
+    "test": "jest"
+  },
+  "keywords": [
+    "butlerbot",
+    "alfred",
+    "sdk",
+    "chatbot",
+    "ai",
+    "butler"
+  ],
+  "author": "Fragly",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isdevco/alfred5_sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/isdevco/alfred5_sdk/issues"
+  },
+  "homepage": "https://butlerbot.net",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  },
+  "dependencies": {
+    "eventsource": "^3.0.5"
+  }
+}

package/readme.md

@@ -0,0 +1,26 @@
+# ButlerBot SDK
+
+ButlerBot SDK is a JavaScript library that provides a simple way to interact with the [ButlerBot](https://butlerbot.net/) API.
+
+## Prerequisites
+
+- ButlerBot API key
+
+## Example
+
+```typescript
+import { ButlerBotClient } from "butlerbot";
+
+const client = new ButlerBotClient({
+  apiKey: "your_api_key_here",
+});
+
+const convo = client.createConversation();
+
+convo.send("Hey there Alfred!", (res) => {
+  if (!res.success) return;
+
+  const { type, payload } = res.data.response;
+  console.log(type, payload); // message { message: "Good day", ... }
+});
+```