lumiverse-spindle-types 0.4.29 → 0.4.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.4.29",
+  "version": "0.4.31",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -293,6 +293,15 @@ export interface CharacterUpdateDTO {
   world_book_ids?: string[];
 }
 
+export interface CharacterAvatarUploadDTO {
+  /** Raw avatar bytes. Extensions can source these from fetch(), storage, etc. */
+  data: Uint8Array;
+  /** Optional filename used to preserve the extension/MIME when storing the image. */
+  filename?: string;
+  /** Optional content type for the uploaded avatar. Defaults to image/png. */
+  mime_type?: string;
+}
+
 // ─── Chat DTOs ──────────────────────────────────────────────────────────
 
 /**
@@ -1031,16 +1040,22 @@ export interface GenerationObserver {
 
 // ─── Token Count DTOs ───────────────────────────────────────────────────
 
-/** Which configured model should be used for server-side token counting. */
-export type TokenModelSourceDTO = "main" | "sidecar";
+/** Where the model used for server-side token counting came from. */
+export type TokenModelSourceDTO = "main" | "sidecar" | "explicit";
 
 /** Optional settings for Spindle token count helpers. */
 export interface TokenCountOptionsDTO {
+  /**
+   * Explicit model ID to resolve the tokenizer against.
+   *
+   * When provided, this takes precedence over `modelSource`.
+   */
+  model?: string;
   /**
    * Which configured model to use when resolving the tokenizer.
    *
-   * - `"main"`    → the user's default main connection profile model
-   * - `"sidecar"` → the user's selected sidecar model (or its backing connection model)
+    * - `"main"`    → the user's default main connection profile model
+    * - `"sidecar"` → the user's selected sidecar model (or its backing connection model)
    *
    * Defaults to `"main"`.
    */
@@ -1054,7 +1069,7 @@ export interface TokenCountResultDTO {
   total_tokens: number;
   /** Model ID that was actually used to resolve the tokenizer. */
   model: string;
-  /** Whether the model came from the main connection or the sidecar selection. */
+  /** Whether the model came from the main connection, sidecar selection, or an explicit override. */
   modelSource: TokenModelSourceDTO;
   /** Null when no exact tokenizer match was found and an approximate fallback was used. */
   tokenizer_id: string | null;
@@ -1282,6 +1297,7 @@ export type WorkerToHost =
   | { type: "characters_list"; requestId: string; limit?: number; offset?: number; userId?: string }
   | { type: "characters_get"; requestId: string; characterId: string; userId?: string }
   | { type: "characters_create"; requestId: string; input: CharacterCreateDTO; userId?: string }
+  | { type: "characters_set_avatar"; requestId: string; characterId: string; avatar: CharacterAvatarUploadDTO; userId?: string }
   | { type: "characters_update"; requestId: string; characterId: string; input: CharacterUpdateDTO; userId?: string }
   | { type: "characters_delete"; requestId: string; characterId: string; userId?: string }
   // ─── Chats (gated: "chats") ────────────────────────────────────────
@@ -1360,6 +1376,7 @@ export type WorkerToHost =
       type: "tokens_count_text";
       requestId: string;
       text: string;
+      model?: string;
       modelSource?: TokenModelSourceDTO;
       userId?: string;
     }
@@ -1367,6 +1384,7 @@ export type WorkerToHost =
       type: "tokens_count_messages";
       requestId: string;
       messages: Array<Pick<LlmMessageDTO, "role" | "content">>;
+      model?: string;
       modelSource?: TokenModelSourceDTO;
       userId?: string;
     }
@@ -1374,6 +1392,7 @@ export type WorkerToHost =
       type: "tokens_count_chat";
       requestId: string;
       chatId: string;
+      model?: string;
       modelSource?: TokenModelSourceDTO;
       userId?: string;
     };

package/src/index.ts

@@ -27,6 +27,7 @@ export type {
   PermissionChangedDetail,
   CharacterDTO,
   CharacterCreateDTO,
+  CharacterAvatarUploadDTO,
   CharacterUpdateDTO,
   ChatDTO,
   ChatUpdateDTO,

package/src/spindle-api.ts

@@ -11,6 +11,7 @@ import type {
   PermissionChangedDetail,
   CharacterDTO,
   CharacterCreateDTO,
+  CharacterAvatarUploadDTO,
   CharacterUpdateDTO,
   ChatDTO,
   ChatUpdateDTO,
@@ -469,20 +470,20 @@ export interface SpindleAPI {
 
   /** Server-side token counting helpers (free tier). */
   tokens: {
-    /** Count tokens for an arbitrary text string. */
+    /** Count tokens for an arbitrary text string. `options.model` overrides `options.modelSource`. */
     countText(text: string, options?: TokenCountOptionsDTO): Promise<TokenCountResultDTO>;
     /**
      * Count tokens for an array of chat-style messages.
      *
      * This accepts any array whose items expose `{ role, content }`, so the
      * normalized output of `spindle.chat.getMessages(chatId)` can be passed
-     * directly without reshaping.
+     * directly without reshaping. `options.model` overrides `options.modelSource`.
      */
     countMessages(
       messages: Array<Pick<LlmMessageDTO, "role" | "content">>,
       options?: TokenCountOptionsDTO
     ): Promise<TokenCountResultDTO>;
-    /** Count tokens for a live stored chat by ID. */
+    /** Count tokens for a live stored chat by ID. `options.model` overrides `options.modelSource`. */
     countChat(chatId: string, options?: TokenCountOptionsDTO): Promise<TokenCountResultDTO>;
   };
 
@@ -561,6 +562,7 @@ export interface SpindleAPI {
     list(options?: { limit?: number; offset?: number; userId?: string }): Promise<{ data: CharacterDTO[]; total: number }>;
     get(characterId: string, userId?: string): Promise<CharacterDTO | null>;
     create(input: CharacterCreateDTO, userId?: string): Promise<CharacterDTO>;
+    setAvatar(characterId: string, avatar: CharacterAvatarUploadDTO, userId?: string): Promise<CharacterDTO>;
     update(characterId: string, input: CharacterUpdateDTO, userId?: string): Promise<CharacterDTO>;
     delete(characterId: string, userId?: string): Promise<boolean>;
   };