@butlerbot/sdk 0.0.6-alpha.2 → 0.0.6-alpha.4

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

@@ -0,0 +1,344 @@
+import { ModelMessage } from "./aisdk_types";
+/** A message in the conversation, extending AI SDK's ModelMessage with AI3 metadata */
+export type ConversationMessage = ModelMessage & {
+    /** AI3-specific metadata */
+    ai3?: {
+        /** ID of the participant who sent this message */
+        participantId?: string;
+        /** Condensed/summarized version of this message content */
+        summarized?: any;
+        /** When this message was added */
+        timestamp?: number;
+    };
+};
+/** Display information for a participant */
+export type DisplayEntity = {
+    name?: string;
+    avatarUrl?: string;
+};
+/** Rich content that can be attached to tool status updates.
+ *  Clients can render these if supported, or fall back to just the `label` field on ToolStatus. */
+export type ToolStatusContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "code";
+    language: string;
+    code: string;
+} | {
+    type: "image";
+    url: string;
+    alt?: string;
+} | {
+    type: "progress";
+    current: number;
+    total: number;
+    label?: string;
+} | {
+    type: "data";
+    data: Record<string, unknown>;
+};
+/** Tool execution status. **/
+export type ToolStatus = {
+    /** Unique ID for this tool execution */
+    id: string;
+    /** Parent tool ID (for nested tool calls, e.g., agent sub-tools) */
+    parentId?: string;
+    /** Top-level status label — always available, suitable for minimal UI */
+    label: string;
+    /** Current state of the tool execution */
+    state: "running" | "completed" | "failed";
+    /** Optional rich content for clients that support it */
+    content?: ToolStatusContent[];
+    /** Whether this tool call is ending the conversation */
+    endingConvo?: boolean;
+};
+export type TokenUsage = {
+    /**
+ * The total number of input (prompt) tokens used.
+ */
+    inputTokens: number | undefined;
+    /**
+     * Detailed information about the input tokens.
+     */
+    inputTokenDetails: {
+        /**
+         * The number of non-cached input (prompt) tokens used.
+         */
+        noCacheTokens: number | undefined;
+        /**
+         * The number of cached input (prompt) tokens read.
+         */
+        cacheReadTokens: number | undefined;
+        /**
+         * The number of cached input (prompt) tokens written.
+         */
+        cacheWriteTokens: number | undefined;
+    };
+    /**
+     * The number of total output (completion) tokens used.
+     */
+    outputTokens: number | undefined;
+    /**
+     * Detailed information about the output tokens.
+     */
+    outputTokenDetails: {
+        /**
+         * The number of text tokens used.
+         */
+        textTokens: number | undefined;
+        /**
+         * The number of reasoning tokens used.
+         */
+        reasoningTokens: number | undefined;
+    };
+    /**
+     * The total number of tokens used.
+     */
+    totalTokens: number | undefined;
+    /**
+     * Raw usage information from the provider.
+     *
+     * This is the usage information in the shape that the provider returns.
+     * It can include additional information that is not part of the standard usage information.
+     */
+    raw?: any;
+};
+export type ModelMessageCost = {
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+    inputCostDetails: {
+        noCacheCost: number;
+        cacheReadCost: number;
+        cacheWriteCost: number;
+    };
+    outputCostDetails: {
+        textCost: number;
+        reasoningCost: number;
+    };
+};
+/** Detailed metadata about a completed response. **/
+export type ResponseMetadata = {
+    /** Human-readable model name (e.g. "Claude-Sonnet") */
+    model: string;
+    /** Provider model identifier (e.g. "claude-sonnet-4-6") */
+    modelId: string;
+    /** Model-specific information */
+    modelInfo: {
+        /** Maximum context length for this model */
+        contextLimit?: number;
+    };
+    /** Token usage breakdown */
+    tokens: TokenUsage;
+    /** The cost breakdown */
+    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 */
+        firstEventMs: number;
+        /** Total response time in milliseconds */
+        totalMs: number;
+    };
+};
+export type MessagePayload = {
+    /** The message content */
+    message: string;
+    /** The UUID of this message */
+    messageId: string;
+    /** Whether this message chunk is the final one */
+    completed: boolean;
+};
+export type ReasoningPayload = {
+    /** The reasoning content */
+    reasoning: string;
+    /** The UUID of this reasoning */
+    reasoningId: string;
+    /** Whether this reasoning chunk is the final one */
+    completed: boolean;
+};
+export type FilePayload = {
+    /** The file URL */
+    url?: string;
+    /** The media type of the file */
+    mediaType: string;
+};
+export type ToolPayload = {
+    /** The tool status */
+    status: ToolStatus;
+};
+export type ConvoStatusPayload = {
+    /** 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;
+    /** Short summary generated for this conversation */
+    shortSummary?: string;
+};
+export type ResponseStatusPayload = {
+    completed: boolean;
+    /** Rich response metadata — only present on the final `completed: true` event.
+     *  Populated by the caller (e.g. gateway) after the response finishes and usage is available. */
+    metadata?: ResponseMetadata;
+};
+export type BaseResponseMetadata = {
+    /** Unique response ID */
+    responseId: string;
+    /** Model display name (e.g., "GPT-5") */
+    model: string;
+    /** Actual model ID (e.g., "gpt-5.2-2025-12-11") */
+    modelId: string;
+    /** Timestamp of first action (first stream chunk) */
+    firstTimestamp: number;
+    /** Timestamp of last action */
+    timestamp: number;
+    /** The participant who generated this response */
+    participantId?: string;
+};
+export type MessageEvent = {
+    type: "message";
+    payload: MessagePayload;
+    metadata: BaseResponseMetadata & {
+        display?: DisplayEntity;
+    };
+};
+export type ReasoningEvent = {
+    type: "reasoning";
+    payload: ReasoningPayload;
+    metadata: BaseResponseMetadata;
+};
+export type FileEvent = {
+    type: "file";
+    payload: FilePayload & {
+        base64?: string;
+    };
+    metadata: BaseResponseMetadata & {
+        display?: DisplayEntity;
+    };
+};
+export type ToolEvent = {
+    type: "tool";
+    payload: ToolPayload;
+    metadata: BaseResponseMetadata;
+};
+export type ResponseStatusEvent = {
+    type: "response_status";
+    payload: ResponseStatusPayload;
+};
+export type ConvoStatusEvent = {
+    type: "convo_status";
+    payload: ConvoStatusPayload;
+};
+/** An entry in the client-facing dialogue history.
+ *  Unlike `ConversationMessage` (which stores raw AI SDK messages),
+ *  dialogue entries are human-readable and intended for UI rendering. */
+export type DialogueEntry = {
+    /** Who sent this */
+    from: "user" | "assistant";
+    /** Display info for the sender */
+    display?: DisplayEntity;
+    /** When this happened */
+    timestamp: number;
+} & ({
+    type: "message";
+    payload: {
+        message: string;
+    };
+} | {
+    type: "reasoning";
+    payload: {
+        reasoning: string;
+        reasoningId: string;
+    };
+} | {
+    type: "file";
+    payload: {
+        url?: string;
+        mediaType: string;
+    };
+} | {
+    type: "tool";
+    payload: {
+        status: ToolStatus;
+    };
+} | {
+    type: "convo_status";
+    payload: {
+        disabled?: boolean;
+        stopped?: boolean;
+        shortSummary?: string;
+    };
+} | {
+    type: "response_status";
+    payload: {
+        completed: boolean;
+    };
+});
+/** Serializable conversation state **/
+export type ConversationState = {
+    /** Conversation settings */
+    settings: {
+        /** Default AI model name */
+        model?: string;
+        /** Conversation title */
+        title?: string;
+        /** System prompt override (bypasses personality generation when set) */
+        system?: string;
+        /** Where this conversation takes place */
+        location?: string;
+        /** Location-specific formatting instructions (e.g., "use discord formatting") */
+        locationInstructions?: string;
+        /** AI temperature (0-1) */
+        temperature?: number;
+        /** Disable auto-title generation */
+        disableAutoTitle?: boolean;
+        /** Enable token caching */
+        tokenCaching?: boolean;
+    };
+    /** Conversation summaries */
+    summary?: {
+        shortSummary?: string;
+        longSummary?: string;
+    };
+    /** Raw message history (AI SDK compatible) */
+    messages: ConversationMessage[];
+    /** Client-facing dialogue history */
+    dialogue: DialogueEntry[];
+};
+export interface ConversationV3 {
+    version: "3.0";
+    conversationId: string;
+    ownerUserId: string;
+    /** Whether to disable the ability for the user to view this conversation */
+    disableView?: boolean;
+    /** AI3 conversation state */
+    state: ConversationState;
+}

package/dist/types/conversation/v3/conversation_v3.js

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

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

@@ -0,0 +1 @@
+export * from "./conversation_v3";

package/dist/types/conversation/v3/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./conversation_v3"), exports);

package/dist/types/model.d.ts

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

package/dist/types/model.js

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

package/dist/types/response/v3/ai_response_v3.d.ts

@@ -0,0 +1,98 @@
+import { AIToolStatusDataV3 } from "./ai_tools_v3";
+import { ErrorCode } from "../../error";
+import { AIChatProfileDisplayEntity } from "../../conversation/v2/conversation_v2";
+export type AIChatResultFailV3 = {
+    success: false;
+    errorcode: ErrorCode;
+};
+export type AIChatResultSuccessV3 = {
+    success: true;
+    response: AIResponseV3[];
+    usage: any;
+};
+export type AIChatResultV3 = AIChatResultFailV3 | AIChatResultSuccessV3;
+export type BaseAIResponseMetadataV3 = {
+    /** The model that generated this message */
+    model: string;
+    /** The actual model ID that generated this message */
+    modelId: string;
+    /** The time when this action started (represents time of first action, meaning in streamed messages it'll hold the time the first chunk was sent) */
+    firstTimestamp: number;
+    /** Epoch time for when this happened (represents time of last action, meaning in streamed messages it'll hold the time the last chunk was sent) */
+    timestamp: number;
+};
+type AIMessageResponseV3 = {
+    /** 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: BaseAIResponseMetadataV3 & {
+        /** Display data for this message response, such as the author's name and profile picture */
+        display?: AIChatProfileDisplayEntity;
+    };
+};
+export type AIReasoningResponseV3 = {
+    /** Specifies type to be a reasoning update */
+    type: "reasoning";
+    payload: {
+        /** The reasoning text */
+        reasoning: string;
+        /** The associated reasoning id */
+        reasoningId: string;
+        /** Whether this reasoning step is completed */
+        completed: boolean;
+    };
+    metadata: BaseAIResponseMetadataV3;
+};
+export type AIFileResponseV3 = {
+    /** Specifies type to be a message */
+    type: "file";
+    payload: {
+        /** URL location of the file */
+        url?: string;
+        /** Base64 representation of the file */
+        base64?: string;
+        /** The media type of the file */
+        mediaType: string;
+    };
+    metadata: BaseAIResponseMetadataV3 & {
+        /** Display data for this message response, such as the author's name and profile picture */
+        display?: AIChatProfileDisplayEntity;
+    };
+};
+export type AIResponseStatusResponseV3 = {
+    /** Specifies type to be a status update for the response */
+    type: "response_status";
+    payload: {
+        /** Whether the entire AI response is completed */
+        completed: boolean;
+    };
+};
+export type AIConvoStatusResponseV3 = {
+    /** 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;
+    };
+};
+export type AIToolResponseV3 = {
+    /** Specifies type to be a tool use status update */
+    type: "tool";
+    payload: {
+        status: string;
+        info: AIToolStatusDataV3;
+    };
+    metadata: BaseAIResponseMetadataV3 & {};
+};
+export type AIResponseV3 = AIMessageResponseV3 | AIToolResponseV3 | AIConvoStatusResponseV3 | AIResponseStatusResponseV3 | AIFileResponseV3 | AIReasoningResponseV3;
+export {};

package/dist/types/response/v3/ai_response_v3.js

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

package/dist/types/response/v3/ai_tools_v3.d.ts

@@ -0,0 +1,7 @@
+export type AIToolStatusDataV3 = {
+    failed: boolean;
+    done: boolean;
+    id: string;
+    parentId?: string;
+    endingConvo?: boolean;
+};

package/dist/types/response/v3/ai_tools_v3.js

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

package/dist/types/response/v3/dialogue_response_v3.d.ts

@@ -0,0 +1,29 @@
+import { AIResponseV3 } from "./ai_response_v3";
+import { ErrorCode } from "../../error";
+export type RequestBaseResponsePayloadV3 = {
+    /** Whether the conversation's ending */
+    end?: boolean;
+    /** Whether the stream is ending */
+    quitStream?: boolean;
+};
+export type RequestFailResponseV3 = {
+    success: false;
+    data: {
+        /** Error code */
+        code: ErrorCode;
+        /** Error message */
+        error: string;
+        /** User facing message */
+        message: string;
+    } & RequestBaseResponsePayloadV3;
+};
+export type RequestSuccessResponseV3 = {
+    success: true;
+    data: {
+        /** The AI's response */
+        response: AIResponseV3;
+        /** The convoId, passed in most responses */
+        convoId?: string;
+    } & RequestBaseResponsePayloadV3;
+};
+export type RequestResponseV3 = RequestFailResponseV3 | RequestSuccessResponseV3;

package/dist/types/response/v3/dialogue_response_v3.js

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

package/dist/types/response/v3/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./ai_response_v3";
+export * from "./dialogue_response_v3";
+export * from "./ai_tools_v3";

package/dist/types/response/v3/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ai_response_v3"), exports);
+__exportStar(require("./dialogue_response_v3"), exports);
+__exportStar(require("./ai_tools_v3"), exports);

package/dist/types/response/v4/ai_response_v4.d.ts

@@ -0,0 +1,22 @@
+import { ConvoStatusEvent, FileEvent, MessageEvent, ModelMessageCost, ReasoningEvent, ResponseMetadata, ResponseStatusEvent, TokenUsage, ToolEvent } from "../../conversation/v3/conversation_v3";
+import { ErrorCode } from "../../error";
+export type AIChatResultFailV4 = {
+    success: false;
+    errorcode: ErrorCode;
+};
+export type AIChatResultSuccessV4 = {
+    success: true;
+    response: AIResponseV4[];
+    usage: any;
+};
+export type AIChatResultV4 = AIChatResultFailV4 | AIChatResultSuccessV4;
+export type TokenUsageV4 = TokenUsage;
+export type ModelMessageCostV4 = ModelMessageCost;
+export type ResponseStatusMetadataV4 = ResponseMetadata;
+export type AIMessageResponseV4 = MessageEvent;
+export type AIReasoningResponseV4 = ReasoningEvent;
+export type AIFileResponseV4 = FileEvent;
+export type AIResponseStatusResponseV4 = ResponseStatusEvent;
+export type AIConvoStatusResponseV4 = ConvoStatusEvent;
+export type AIToolResponseV4 = ToolEvent;
+export type AIResponseV4 = AIMessageResponseV4 | AIToolResponseV4 | AIConvoStatusResponseV4 | AIResponseStatusResponseV4 | AIFileResponseV4 | AIReasoningResponseV4;

package/dist/types/response/v4/ai_response_v4.js

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

package/dist/types/response/v4/dialogue_response_v4.d.ts

@@ -0,0 +1,29 @@
+import { AIResponseV4 } from "./ai_response_v4";
+import { ErrorCode } from "../../error";
+export type RequestBaseResponsePayloadV4 = {
+    /** Whether the conversation's ending */
+    end?: boolean;
+    /** Whether the stream is ending */
+    quitStream?: boolean;
+};
+export type RequestFailResponseV4 = {
+    success: false;
+    data: {
+        /** Error code */
+        code: ErrorCode;
+        /** Error message */
+        error: string;
+        /** User facing message */
+        message: string;
+    } & RequestBaseResponsePayloadV4;
+};
+export type RequestSuccessResponseV4 = {
+    success: true;
+    data: {
+        /** The AI's response */
+        response: AIResponseV4;
+        /** The convoId, passed in most responses */
+        convoId?: string;
+    } & RequestBaseResponsePayloadV4;
+};
+export type RequestResponseV4 = RequestFailResponseV4 | RequestSuccessResponseV4;

package/dist/types/response/v4/dialogue_response_v4.js

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

package/dist/types/response/v4/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ai_response_v4";
+export * from "./dialogue_response_v4";

package/dist/types/response/v4/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./ai_response_v4"), exports);
+__exportStar(require("./dialogue_response_v4"), exports);

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

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

package/dist/types/state/convo_state_response.js

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

package/dist/types/type_registry.d.ts

@@ -1,3 +1,3 @@
-export * from "./v3";
-export * from "./v4";
+export * from "./response/v3";
+export * from "./response/v4";
 export * from "./error";

package/dist/types/type_registry.js

@@ -14,6 +14,6 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./v3"), exports);
-__exportStar(require("./v4"), exports);
+__exportStar(require("./response/v3"), exports);
+__exportStar(require("./response/v4"), exports);
 __exportStar(require("./error"), exports);

package/package.json

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