@butlerbot/sdk 0.0.6 → 0.0.7-alpha.1

package/dist/config.d.ts

@@ -22,5 +22,12 @@ export declare const CONFIG: {
                 };
             };
         };
+        usage: {
+            policy: {
+                v3: {
+                    base: string;
+                };
+            };
+        };
     };
 };

package/dist/config.js

@@ -16,6 +16,11 @@ exports.CONFIG = {
             chats: {
                 v1: { base: "/api/convo/get/history" }
             }
+        },
+        usage: {
+            policy: {
+                v3: { base: "/api/user/usage/v3/policy" },
+            }
         }
     }
 };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { Conversation, ConversationOptions } from "./modules/conversation";
+import { UsagePolicyDataOptions } from "./modules/usage";
 type OptionalApiKey<T> = Omit<T, "apiKey"> & {
     /** Optional API key, defaults to API key specified in client */
     apiKey?: string;
@@ -20,6 +21,8 @@ export declare class ButlerBotClient {
     healthCheck(healthCheckPath?: string): Promise<boolean>;
     /** Spawns a new Conversation, inherits api key and server URL */
     createConversation(config?: OptionalApiKey<ConversationOptions>): Conversation;
+    /** Get current usage policy data */
+    getUsagePolicyData(config: OptionalApiKey<UsagePolicyDataOptions>): Promise<import("./types/usage/policy").UsagePolicyData>;
 }
-export { Conversation, ConversationOptions };
 export * from "./types/type_registry";
+export { Conversation, ConversationOptions };

package/dist/index.js

@@ -27,6 +27,7 @@ exports.Conversation = exports.ButlerBotClient = void 0;
 const config_1 = require("./config");
 const conversation_1 = require("./modules/conversation");
 Object.defineProperty(exports, "Conversation", { enumerable: true, get: function () { return conversation_1.Conversation; } });
+const usage_1 = require("./modules/usage");
 class ButlerBotClient {
     constructor(config) {
         this.apiKey = config.apiKey;
@@ -52,6 +53,11 @@ class ButlerBotClient {
     createConversation(config = {}) {
         return new conversation_1.Conversation(Object.assign({ debug: this.debug, apiKey: this.apiKey, serverUrl: this.serverUrl }, config));
     }
+    /** Get current usage policy data */
+    getUsagePolicyData(config) {
+        return (0, usage_1.getUsagePolicyData)(Object.assign({ serverURL: this.serverUrl, apiKey: this.apiKey, debug: this.debug }, config));
+    }
 }
 exports.ButlerBotClient = ButlerBotClient;
+// Expose types from subsequent modules
 __exportStar(require("./types/type_registry"), exports);

package/dist/modules/conversation.d.ts

@@ -84,7 +84,6 @@ export declare class Conversation {
     getPlatform(): string | undefined;
     /** Gets the current personality configuration */
     getPersonality(): string | undefined;
-    formatURL(url: string, params?: Object): string;
     /** Fetches the conversation state from the server, including message history and metadata */
     fetchState(): Promise<ConversationStateResponse>;
     /** Sends a message into the conversation */

package/dist/modules/conversation.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Conversation = void 0;
 const eventsource_1 = require("eventsource");
 const config_1 = require("../config");
+const url_formatter_1 = require("../util/url_formatter");
 const DEFAULT_CONVO_API_V = "v3";
 class Conversation {
     constructor(config) {
@@ -108,29 +109,13 @@ class Conversation {
         var _a;
         return (_a = this.options) === null || _a === void 0 ? void 0 : _a.personality;
     }
-    // HELPERS
-    formatURL(url, params = {}) {
-        const fParams = Object.assign({ api_key: this.apiKey }, params);
-        const paramQuery = new URLSearchParams(fParams).toString();
-        const fUrl = `${url}?${paramQuery}`;
-        if (this.debug) {
-            const debugUrl = new URL(fUrl);
-            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(`[Formatting URL ${debugUrl.toString()}]`);
-        }
-        return fUrl;
-    }
     // GETTERS
     /** Fetches the conversation state from the server, including message history and metadata */
     fetchState() {
         return __awaiter(this, void 0, void 0, function* () {
             if (!this.convoId)
                 throw new Error("Conversation ID is not set");
-            const url = this.formatURL(`${this.endpoints.history}/${this.convoId}`);
+            const url = (0, url_formatter_1.formatURL)(`${this.endpoints.history}/${this.convoId}`, undefined, { apiKey: this.apiKey, debug: this.debug });
             const response = yield fetch(url);
             if (!response.ok) {
                 const errorText = yield response.text();
@@ -148,7 +133,7 @@ class Conversation {
             );
             if (this.convoId)
                 payload.chatId = this.convoId;
-            const url = this.formatURL(this.endpoints.conversation, payload);
+            const url = (0, url_formatter_1.formatURL)(this.endpoints.conversation, payload, { apiKey: this.apiKey, debug: this.debug });
             const sse = new eventsource_1.EventSource(url);
             sse.addEventListener("message", (event) => {
                 const data = JSON.parse(event.data);

package/dist/modules/usage.d.ts

@@ -0,0 +1,9 @@
+import { UsagePolicyData } from "../types/usage/policy";
+export type UsagePolicyDataOptions = {
+    serverURL?: string;
+    path?: string;
+    apiKey: string;
+    debug?: boolean;
+};
+/** Fetches the current usage policy data from the server */
+export declare function getUsagePolicyData(options: UsagePolicyDataOptions): Promise<UsagePolicyData>;

package/dist/modules/usage.js

@@ -0,0 +1,31 @@
+"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'}`);
+        }
+        return data;
+    });
+}

package/dist/types/conversation/v3/conversation_v3.d.ts

@@ -131,40 +131,15 @@ export type ResponseMetadata = {
     };
     /** Token usage breakdown */
     tokens: TokenUsage;
-    /** The cost breakdown */
+    /** The cost of the current turn */
     cost: {
-        /** The cost of the current turn */
         turnCost?: ModelMessageCost;
-        /** The current user's usage cost */
-        dailyUsageCost: number;
-        /** The user's cost limit for the conversation (e.g., daily limit) */
-        dailyUsageCostLimit: number;
-    };
-    /** Usage budget info */
-    limit: {
-        /** Current usage cost as a percentage of daily limit (0–1) */
-        percentage: number;
-        /** Human-readable percentage (e.g. "42.3%") */
-        percentageDisplay: string;
-        /** Name of the active usage stage */
-        stageName: string;
-    };
-    /** Model switching info (tiered auto-downgrade) */
-    modelSwitching: {
-        /** Whether the model was switched from the user's request */
-        switched: boolean;
-        /** Originally requested model */
-        requestedModel: string;
-        /** Model that was actually used */
-        activeModel: string;
-        /** Usage stage that triggered the switch */
-        stage?: string;
     };
     /** Response timing */
     timing: {
-        /** Milliseconds from request start to first streamed event */
+        /** Milliseconds from turn start to first streamed event */
         firstEventMs: number;
-        /** Total response time in milliseconds */
+        /** Total turn time in milliseconds */
         totalMs: number;
     };
 };

package/dist/types/usage/policy.d.ts

@@ -0,0 +1,45 @@
+import { AI_MODEL } from "../model";
+export type PolicyRule = {
+    /** When the current usage exceeds this threshold */
+    whenUsageAbove: {
+        type: "percentage";
+        value: number;
+    };
+    /** When the current chosen model is equal to this model */
+    whenModelEquals?: {
+        value: AI_MODEL;
+    };
+    /** The model to overwrite the convos as, 'null' means no overwrite - use user's choice */
+    model: AI_MODEL | null;
+    /** When this rule is activated, this message will be sent to the user */
+    switchMessage?: string;
+    /** The message appended on the end of every message sent giving additional info */
+    appendMessage?: string;
+};
+export type UsagePolicy = {
+    rules: PolicyRule[];
+    maxConvoLength?: number;
+};
+export type UsagePolicyData = {
+    limit: {
+        /** Current usage cost as a percentage of daily limit (0–1) */
+        percentage: number;
+    };
+    /** Model switching info (tiered auto-downgrade) */
+    modelSwitching: {
+        /** Whether the model was switched from the user's request */
+        switched: boolean;
+        /** Originally requested model */
+        requestedModel?: string;
+        /** Model that was actually used */
+        activeModel?: string;
+    };
+    /** Usage policy information */
+    usagePolicy: UsagePolicy;
+    daily: {
+        /** The current user's usage cost */
+        dailyUsageCost: number;
+        /** The user's cost limit for the conversation (e.g., daily limit) */
+        dailyUsageCostLimit: number;
+    };
+};

package/dist/types/usage/policy.js

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

package/dist/util/url_formatter.d.ts

@@ -0,0 +1,4 @@
+export declare function formatURL(url: string, params: Object | undefined, config: {
+    apiKey: string;
+    debug?: boolean;
+}): string;

package/dist/util/url_formatter.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatURL = formatURL;
+function formatURL(url, params = {}, config) {
+    const fParams = Object.assign({ api_key: config.apiKey }, params);
+    const paramQuery = new URLSearchParams(fParams).toString();
+    const fUrl = `${url}?${paramQuery}`;
+    if (config.debug) {
+        const debugUrl = new URL(fUrl);
+        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(`[Formatting URL ${debugUrl.toString()}]`);
+    }
+    return fUrl;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.6",
+	"version": "0.0.7-alpha.1",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",