lumiverse-spindle-types 0.6.14 → 0.6.16

package/package.json

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

package/src/api.ts

@@ -1536,6 +1536,8 @@ export type RegexMacroModeDTO = "none" | "find" | "raw" | "escaped" | "after";
 
 export interface RegexScriptDTO {
   id: string;
+  /** True when the calling extension may update or delete this script. */
+  readonly can_mutate: boolean;
   name: string;
   script_id: string;
   find_regex: string;

package/src/dom.ts

@@ -890,6 +890,61 @@ export interface SpindleDisplayResolverRegistry {
   }): void;
 }
 
+/** Query options shared by the Lumiverse recent-chats host reads. */
+export interface SpindleRecentChatsQuery {
+  limit?: number;
+  offset?: number;
+  search?: string;
+  sort?: "name" | "recent" | "created";
+  direction?: "asc" | "desc";
+}
+
+/**
+ * A flat recent-chat row: one entry per chat, newest-first by default.
+ * `message_count` and `last_message_preview` ride along so list UIs never
+ * need a per-row message fetch.
+ */
+export interface SpindleRecentChat {
+  id: string;
+  character_id: string;
+  name: string;
+  created_at: number;
+  updated_at: number;
+  character_name: string;
+  character_image_id: string | null;
+  character_avatar_path?: string | null;
+  message_count: number;
+  last_message_preview: string;
+  [key: string]: unknown;
+}
+
+/**
+ * A grouped recent-chat row: one entry per solo character / group member
+ * set, pointing at that lineage's most recent chat.
+ */
+export interface SpindleGroupedRecentChat {
+  character_id: string;
+  character_name: string;
+  character_image_id: string | null;
+  character_avatar_path?: string | null;
+  latest_chat_id: string;
+  latest_chat_name: string;
+  updated_at: number;
+  chat_count: number;
+  is_group: boolean;
+  group_character_ids?: string[];
+  group_name?: string;
+  multiplayer?: boolean;
+  [key: string]: unknown;
+}
+
+/** Paginated recent-chats response (`data` + `total`). */
+export interface SpindleRecentChatsPage<TRow = SpindleRecentChat> {
+  data: TRow[];
+  total: number;
+  [key: string]: unknown;
+}
+
 /** Context object provided to frontend extension modules */
 export interface SpindleFrontendContext {
   /** Immutable host compatibility descriptor for this extension runtime. */
@@ -1078,6 +1133,22 @@ export interface SpindleFrontendContext {
   chats: {
     /** Update a message through the host app's authenticated API. */
     updateMessage(chatId: string, messageId: string, input: { content?: string }): Promise<unknown>;
+    /**
+     * Lumiverse host extension: flat one-row-per-chat recent list with
+     * server-side search/sort and per-row preview enrichment. Free
+     * (session-authenticated REST read). Undefined on hosts without it.
+     */
+    listRecent?(options?: SpindleRecentChatsQuery): Promise<SpindleRecentChatsPage<SpindleRecentChat>>;
+    /**
+     * Lumiverse host extension: recent chats grouped per character/group with
+     * server-side search, sort, and pagination. Free (session-authenticated
+     * REST read). Undefined on hosts without it.
+     */
+    listRecentGrouped?(options?: SpindleRecentChatsQuery): Promise<SpindleRecentChatsPage<SpindleGroupedRecentChat>>;
+    /** Lumiverse host extension: rename a chat / merge metadata (permission: "chats"). */
+    update?(chatId: string, input: { name?: string; metadata?: Record<string, unknown> }): Promise<unknown>;
+    /** Lumiverse host extension: permanently delete a chat (permission: "chats"). */
+    delete?(chatId: string): Promise<void>;
   };
   /** Take over display-time content resolution in the browser. */
   display?: SpindleDisplayResolverRegistry;

package/src/index.ts

@@ -267,6 +267,10 @@ export type {
   SpindleMessageWidgetOptions,
   PermissionRequestOptions,
   SpindleFrontendContext,
+  SpindleRecentChatsQuery,
+  SpindleRecentChat,
+  SpindleGroupedRecentChat,
+  SpindleRecentChatsPage,
   SpindleFrontendModule,
   SpindleFrontendTeardown,
   SpindleGuideDefinition,

package/src/spindle-api.ts

@@ -312,9 +312,14 @@ export interface SpindleAPI {
   /** Subscribe to a Lumiverse event. Multi-user extensions should use the optional `userId` to keep per-user state and notifications isolated. */
   on(event: string, handler: (payload: unknown, userId?: string) => void): () => void;
 
-  /** Register a macro. Handler contexts expose `commit === false` during dry resolves. */
+  /**
+   * Register a macro owned by this extension. Registrations cannot replace
+   * system macros or macros owned by another extension. Preset/request dynamic
+   * macros take precedence over extension macros with the same name.
+   * Handler contexts expose `commit === false` during dry resolves.
+   */
   registerMacro(def: MacroDefinitionDTO): void;
-  /** Unregister a macro */
+  /** Unregister a macro owned by this extension. */
   unregisterMacro(name: string): void;
   /**
    * Push the latest value for a registered macro.
@@ -1012,10 +1017,14 @@ export interface SpindleAPI {
   };
 
   /**
-   * Regex Scripts CRUD (permission: "regex_scripts").
-   * Full access to regex scripts attached to the user's account, including
-   * global, character-scoped, and chat-scoped rules. Same shape Lumiverse uses
-   * internally during prompt assembly, response baking, and display rendering.
+   * Regex Scripts API (permission: "regex_scripts").
+   * Read access to regex scripts attached to the user's account and write
+   * access to unbound scripts created by the calling extension. Legacy or
+   * unattributed scripts, preset-bound scripts, and scripts owned by another
+   * extension remain readable and executable but cannot be updated or deleted.
+   * Check `RegexScriptDTO.can_mutate` before presenting mutation controls.
+   * Uses the same shape Lumiverse applies internally during prompt assembly,
+   * response baking, and display rendering.
    * For user-scoped extensions, userId is inferred from the extension owner.
    * For operator-scoped extensions, pass userId to scope to a specific user.
    */