lumiverse-spindle-types 0.4.30 → 0.4.32

package/package.json

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

package/src/api.ts

@@ -29,6 +29,27 @@ export interface MacroDefinitionDTO {
   handler: string; // serialized function body (executed in worker context)
 }
 
+/** Minimal shape exposed to extension macro handlers. Additional fields may be present. */
+export interface MacroInvocationContextDTO {
+  /** False when the host is performing a dry / non-committing resolve. */
+  commit: boolean;
+  [key: string]: unknown;
+}
+
+export interface MacroResolveOptionsDTO {
+  chatId?: string;
+  characterId?: string;
+  /** For operator-scoped extensions only. */
+  userId?: string;
+  /** Defaults to true. Set false to request a dry / non-committing resolve. */
+  commit?: boolean;
+}
+
+export interface MacroResolveResultDTO {
+  text: string;
+  diagnostics: Array<{ message: string; offset: number; length: number }>;
+}
+
 export interface ToolRegistrationDTO {
   name: string;
   display_name: string;
@@ -293,6 +314,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 ──────────────────────────────────────────────────────────
 
 /**
@@ -1288,6 +1318,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") ────────────────────────────────────────
@@ -1339,7 +1370,7 @@ export type WorkerToHost =
   | { type: "confirm_open"; requestId: string; title: string; message: string; variant?: "info" | "warning" | "danger" | "success"; confirmLabel?: string; cancelLabel?: string; userId?: string }
   | { type: "input_prompt_open"; requestId: string; title: string; message?: string; placeholder?: string; defaultValue?: string; submitLabel?: string; cancelLabel?: string; multiline?: boolean; userId?: string }
   // ─── Macro Resolution (free tier) ──────────────────────────────────
-  | { type: "macros_resolve"; requestId: string; template: string; chatId?: string; characterId?: string; userId?: string }
+  | { type: "macros_resolve"; requestId: string; template: string; chatId?: string; characterId?: string; userId?: string; commit?: boolean }
   // ─── Image Generation (gated: "image_gen") ──────────────────────────
   | { type: "image_gen_generate"; requestId: string; input: ImageGenRequestDTO }
   | { type: "image_gen_providers"; requestId: string; userId?: string }

package/src/index.ts

@@ -16,6 +16,9 @@ export type {
   LlmMessageDTO,
   InterceptorResultDTO,
   MacroDefinitionDTO,
+  MacroInvocationContextDTO,
+  MacroResolveOptionsDTO,
+  MacroResolveResultDTO,
   ToolRegistrationDTO,
   ToolSchemaDTO,
   ToolCallDTO,
@@ -27,6 +30,7 @@ export type {
   PermissionChangedDetail,
   CharacterDTO,
   CharacterCreateDTO,
+  CharacterAvatarUploadDTO,
   CharacterUpdateDTO,
   ChatDTO,
   ChatUpdateDTO,

package/src/spindle-api.ts

@@ -3,6 +3,8 @@ import type {
   LlmMessageDTO,
   InterceptorResultDTO,
   MacroDefinitionDTO,
+  MacroResolveOptionsDTO,
+  MacroResolveResultDTO,
   ToolRegistrationDTO,
   GenerationRequestDTO,
   RequestInitDTO,
@@ -11,6 +13,7 @@ import type {
   PermissionChangedDetail,
   CharacterDTO,
   CharacterCreateDTO,
+  CharacterAvatarUploadDTO,
   CharacterUpdateDTO,
   ChatDTO,
   ChatUpdateDTO,
@@ -95,7 +98,7 @@ export interface SpindleAPI {
   /** Subscribe to a Lumiverse event. */
   on(event: string, handler: (payload: unknown, userId?: string) => void): () => void;
 
-  /** Register a macro */
+  /** Register a macro. Handler contexts expose `commit === false` during dry resolves. */
   registerMacro(def: MacroDefinitionDTO): void;
   /** Unregister a macro */
   unregisterMacro(name: string): void;
@@ -561,6 +564,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>;
   };
@@ -761,6 +765,8 @@ export interface SpindleAPI {
      * Resolve all macros in the given template string.
      * Provide `chatId` and/or `characterId` for full context resolution.
      * Without them, only context-free macros (time, random, etc.) resolve.
+     * Set `commit: false` for a dry / non-committing resolve; extension macro
+     * handlers will receive `ctx.commit === false`.
      *
      * @example
      * ```ts
@@ -772,16 +778,8 @@ export interface SpindleAPI {
      */
     resolve(
       template: string,
-      options?: {
-        chatId?: string;
-        characterId?: string;
-        /** For operator-scoped extensions only. */
-        userId?: string;
-      },
-    ): Promise<{
-      text: string;
-      diagnostics: Array<{ message: string; offset: number; length: number }>;
-    }>;
+      options?: MacroResolveOptionsDTO,
+    ): Promise<MacroResolveResultDTO>;
   };
 
   /**