lumiverse-spindle-types 0.4.16 → 0.4.18

package/package.json

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

package/src/api.ts

@@ -169,7 +169,8 @@ export interface ImageGenResultDTO {
 
 /**
  * Safe representation of a character exposed to extensions.
- * Omits raw extensions blob — only exposes user-facing fields.
+ * Omits the raw `extensions` blob — only exposes user-facing fields plus
+ * a small allowlist of structured extension state (e.g. `world_book_ids`).
  */
 export interface CharacterDTO {
   id: string;
@@ -186,6 +187,11 @@ export interface CharacterDTO {
   alternate_greetings: string[];
   creator: string;
   image_id: string | null;
+  /**
+   * IDs of world books attached directly to this character. The legacy
+   * single-id form is auto-migrated, so consumers can rely on the array.
+   */
+  world_book_ids: string[];
   created_at: number;
   updated_at: number;
 }
@@ -203,6 +209,8 @@ export interface CharacterCreateDTO {
   tags?: string[];
   alternate_greetings?: string[];
   creator?: string;
+  /** Optional initial world book attachments. */
+  world_book_ids?: string[];
 }
 
 export interface CharacterUpdateDTO {
@@ -218,6 +226,11 @@ export interface CharacterUpdateDTO {
   tags?: string[];
   alternate_greetings?: string[];
   creator?: string;
+  /**
+   * Replace the character's world book attachments. Pass an empty array to
+   * detach all books. Omit the field to leave attachments unchanged.
+   */
+  world_book_ids?: string[];
 }
 
 // ─── Chat DTOs ──────────────────────────────────────────────────────────
@@ -799,6 +812,81 @@ export interface GenerationStoppedPayloadDTO {
   content?: string;
 }
 
+// ─── Chat Message Event Payload DTOs ────────────────────────────────────
+
+/**
+ * Wire shape of a chat message as delivered in WebSocket event payloads
+ * (e.g. `MESSAGE_SENT`, `MESSAGE_EDITED`, `MESSAGE_SWIPED`).
+ *
+ * This is the raw backend message shape and is distinct from the normalized
+ * `{ id, role, content, ... }` object returned by `spindle.chat.getMessages()`,
+ * which collapses `is_user`/`name` into a `role` discriminator.
+ */
+export interface ChatMessageDTO {
+  id: string;
+  chat_id: string;
+  index_in_chat: number;
+  is_user: boolean;
+  name: string;
+  /** The currently active swipe content (mirrors `swipes[swipe_id]`). */
+  content: string;
+  send_date: number;
+  /** Index of the active swipe in `swipes`. `0` when the message has no alternates. */
+  swipe_id: number;
+  /** All swipe variants for this message, including the currently active one. */
+  swipes: string[];
+  /** Per-swipe creation timestamps (unix epoch seconds), aligned with `swipes`. */
+  swipe_dates: number[];
+  /** Free-form metadata bag (attachments, spindle metadata, reasoning, etc.). */
+  extra: Record<string, unknown>;
+  parent_message_id: string | null;
+  branch_id: string | null;
+  created_at: number;
+}
+
+/**
+ * Distinguishes the four ways a `MESSAGE_SWIPED` event can be triggered.
+ *
+ *  - `'added'`     — a new swipe variant was created (e.g. regenerate, manual add)
+ *  - `'updated'`   — an existing swipe's content was edited in place
+ *  - `'deleted'`   — a swipe variant was removed from the message
+ *  - `'navigated'` — the user (or an extension) cycled the active swipe slot
+ */
+export type MessageSwipeAction = "added" | "updated" | "deleted" | "navigated";
+
+/**
+ * Payload for `MESSAGE_SWIPED` events.
+ *
+ * The discriminator fields (`action`, `swipeId`, `previousSwipeId`) let
+ * extensions tell the four swipe operations apart and maintain swipe-keyed
+ * state correctly without diffing the `swipes` array on every event.
+ */
+export interface MessageSwipedPayloadDTO {
+  chatId: string;
+  /** The full message after the mutation. */
+  message: ChatMessageDTO;
+  /** Distinguishes which swipe operation produced this event. */
+  action: MessageSwipeAction;
+  /**
+   * The swipe index this event concerns. Semantics depend on `action`:
+   *
+   *  - `'added'`     — index of the new swipe (equal to `message.swipe_id` post-add)
+   *  - `'updated'`   — index of the edited swipe (may or may not equal `message.swipe_id`)
+   *  - `'deleted'`   — index that was removed. Note: this slot is no longer present
+   *                    in `message.swipes`, and `message.swipe_id` may have shifted
+   *                    if the deleted slot was at or before the previously active one.
+   *  - `'navigated'` — destination index (equal to `message.swipe_id`)
+   */
+  swipeId: number;
+  /**
+   * For `'navigated'` and `'deleted'` events: the active swipe index *before*
+   * the change. Useful for direction detection on navigation, and for detecting
+   * whether the active slot was the one removed on deletion. Omitted for
+   * `'added'` and `'updated'`.
+   */
+  previousSwipeId?: number;
+}
+
 /**
  * Observer handle returned by `spindle.generate.observe()`.
  * Provides a high-level API for watching an in-flight generation on a
@@ -916,6 +1004,26 @@ export type WorkerToHost =
       chatId: string;
       messageId: string;
     }
+  | {
+      type: "chat_set_message_hidden";
+      requestId: string;
+      chatId: string;
+      messageId: string;
+      hidden: boolean;
+    }
+  | {
+      type: "chat_set_messages_hidden";
+      requestId: string;
+      chatId: string;
+      messageIds: string[];
+      hidden: boolean;
+    }
+  | {
+      type: "chat_is_message_hidden";
+      requestId: string;
+      chatId: string;
+      messageId: string;
+    }
   | {
       type: "events_track";
       requestId: string;

package/src/index.ts

@@ -67,6 +67,9 @@ export type {
   GenerationEndedPayloadDTO,
   GenerationStoppedPayloadDTO,
   GenerationObserver,
+  ChatMessageDTO,
+  MessageSwipeAction,
+  MessageSwipedPayloadDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";

package/src/spindle-api.ts

@@ -44,6 +44,7 @@ import type {
   GenerationEndedPayloadDTO,
   GenerationStoppedPayloadDTO,
   GenerationObserver,
+  MessageSwipedPayloadDTO,
 } from "./api";
 
 /** The global `spindle` object available in backend extension workers */
@@ -56,6 +57,12 @@ export interface SpindleAPI {
   on(event: "GENERATION_ENDED", handler: (payload: GenerationEndedPayloadDTO) => void): () => void;
   /** Subscribe to generation-stopped events (requires `generation` permission). */
   on(event: "GENERATION_STOPPED", handler: (payload: GenerationStoppedPayloadDTO) => void): () => void;
+  /**
+   * Subscribe to swipe lifecycle events. The payload's `action` discriminator
+   * tells you whether a swipe was added, updated, deleted, or navigated, and
+   * `swipeId` identifies which slot the event concerns.
+   */
+  on(event: "MESSAGE_SWIPED", handler: (payload: MessageSwipedPayloadDTO) => void): () => void;
   /** Subscribe to a Lumiverse event. */
   on(event: string, handler: (payload: unknown) => void): () => void;
 
@@ -245,6 +252,27 @@ export interface SpindleAPI {
       }
     ): Promise<void>;
     deleteMessage(chatId: string, messageId: string): Promise<void>;
+    /**
+     * Mark a single message as hidden or visible. Hidden messages are
+     * excluded from chat memory embeddings (vector retrieval) but, in the
+     * current build, are still included in chat history during prompt
+     * assembly. See `chat-mutation.md` for the full semantics.
+     *
+     * Requires the `chat_mutation` permission.
+     */
+    setMessageHidden(chatId: string, messageId: string, hidden: boolean): Promise<void>;
+    /**
+     * Bulk variant of {@link setMessageHidden}. Capped at 500 message IDs
+     * per call (matching the underlying service limit).
+     *
+     * Requires the `chat_mutation` permission.
+     */
+    setMessagesHidden(chatId: string, messageIds: string[], hidden: boolean): Promise<void>;
+    /**
+     * Read the hidden flag for a single message. Returns `false` for messages
+     * that have never had the flag set. Requires the `chat_mutation` permission.
+     */
+    isMessageHidden(chatId: string, messageId: string): Promise<boolean>;
   };
 
   /** Extension-level telemetry */