Events¶

Subscribe to any Lumiverse lifecycle event. Returns an unsubscribe function.

// Subscribe
const unsub = spindle.on('MESSAGE_SENT', (payload) => {
  spindle.log.info(`Message sent in chat ${payload.chatId}`)
})

// Unsubscribe later
unsub()

Available Events¶

Chat Lifecycle¶

Generation¶

These events have typed overloads — payloads are automatically narrowed when using lumiverse-spindle-types:

spindle.on('STREAM_TOKEN_RECEIVED', (payload) => {
  // payload: StreamTokenPayloadDTO — fully typed
  console.log(payload.token, payload.seq, payload.type)
})

See Generation > Stream Observation for the high-level observe() helper and full payload field reference.

Swipe Events¶

Swipe state changes are surfaced through two events. Pick whichever matches how you want to react:

• MESSAGE_SWIPED — fine-grained. Fires from the four dedicated REST swipe routes (addSwipe, updateSwipe, deleteSwipe, cycleSwipe). Payload carries an action discriminator so you can tell add/update/delete/navigate apart without diffing arrays.
• SWIPE_EDITED — coarse. Fires when spindle.chat.updateMessage explicitly supplies one or more of swipes / swipe_id / swipe_dates. Use this when an extension rewrites the swipe array wholesale (e.g. regenerating alternates, merging variants) and you just need to know "the swipe state for this message changed, refetch it."

Plain content-only edits via updateMessage (patches that only touch content, metadata, name, or reasoning) do not emit SWIPE_EDITED — they emit MESSAGE_EDITED only, even though the host mirrors the new content into the active swipe slot under the hood.

MESSAGE_SWIPED¶

spindle.on('MESSAGE_SWIPED', (payload) => {
  // payload: MessageSwipedPayloadDTO — fully typed
  switch (payload.action) {
    case 'added':
      // payload.swipeId === payload.message.swipe_id (the new variant)
      break
    case 'updated':
      // payload.swipeId is the edited slot (may not be the active one)
      break
    case 'deleted':
      // payload.swipeId is the removed slot (no longer in message.swipes)
      // payload.previousSwipeId tells you the active slot before deletion
      if (payload.previousSwipeId === payload.swipeId) {
        // the active swipe was the one removed
      }
      break
    case 'navigated':
      // payload.swipeId === payload.message.swipe_id (the destination)
      // payload.previousSwipeId tells you which direction the user came from
      break
  }
})

SWIPE_EDITED¶

spindle.on('SWIPE_EDITED', (payload) => {
  // payload: SwipeEditedPayloadDTO — fully typed
  const { chatId, message, previousSwipeId } = payload

  if (previousSwipeId !== message.swipe_id) {
    // The active slot moved — treat as a navigation
  }
  // Re-render from message.swipes / message.swipe_dates
})

No action discriminator is provided — if you need add/update/delete/navigate semantics, diff message.swipes / message.swipe_dates against your cached state, or subscribe to MESSAGE_SWIPED instead.

Entities¶

Settings¶

Images¶

Regex Scripts¶

Expressions¶

Spindle Extensions¶

Permissions¶