feat(frontend): add session and playlist API client

frontend/src/composables/useChatStream.ts

@@ -0,0 +1,265 @@
+import { computed, onUnmounted, ref } from 'vue'
+import type { AssistantTurn, ChatTurn, EventLogEntry, TransportFailure } from '../lib/models'
+import { EMPTY_PLAYLIST_STATE } from '../lib/models'
+import {
+  isAbortError,
+  streamRecommendations,
+  StreamTransportError,
+} from '../lib/recommendationStream'
+import type {
+  HistoryTurn,
+  PlaylistCreateRequest,
+  PlaylistCreateResponse,
+  PriorRecommendation,
+  RecommendationRequest,
+  StreamEvent,
+} from '../lib/types'
+
+const HISTORY_LIMIT = 12
+const PRIOR_RECOMMENDATION_LIMIT = 50
+const EVENT_LOG_LIMIT = 100
+
+type PlaylistCreator = (request: PlaylistCreateRequest) => Promise<PlaylistCreateResponse>
+
+function assistantContent(turn: AssistantTurn): string {
+  const trackLines = turn.tracks.map(
+    (event) => `${event.rank}. ${event.track.title} by ${event.track.artists.join(', ')}`,
+  )
+  const content = [turn.intentSummary, ...trackLines].filter(Boolean).join('\n')
+  return content.slice(0, 2000)
+}
+
+function buildHistory(turns: ChatTurn[]): HistoryTurn[] {
+  return turns
+    .map((turn): HistoryTurn | null => {
+      if (turn.role === 'user') return { role: 'user', content: turn.text }
+      const content = assistantContent(turn)
+      return content ? { role: 'assistant', content } : null
+    })
+    .filter((turn): turn is HistoryTurn => turn !== null)
+    .slice(-HISTORY_LIMIT)
+}
+
+function buildPriorRecommendations(turns: ChatTurn[]): PriorRecommendation[] {
+  const latest = [...turns]
+    .reverse()
+    .find((turn): turn is AssistantTurn => turn.role === 'assistant' && turn.status === 'done')
+  if (!latest) return []
+  return latest.tracks.slice(0, PRIOR_RECOMMENDATION_LIMIT).map((event) => ({
+    rank: event.rank,
+    track_id: event.track.id,
+    title: event.track.title,
+    artists: event.track.artists,
+  }))
+}
+
+function reduceEvent(turn: AssistantTurn, event: StreamEvent): AssistantTurn {
+  switch (event.type) {
+    case 'metadata':
+      return {
+        ...turn,
+        requestId: event.request_id,
+        intentSummary: event.intent_summary,
+        candidateCount: event.candidate_count,
+      }
+    case 'track':
+      return { ...turn, tracks: [...turn.tracks, event] }
+    case 'warning':
+      return { ...turn, warnings: [...turn.warnings, event] }
+    case 'error':
+      return { ...turn, status: 'error', error: event }
+    case 'done':
+      if (event.track_count !== turn.tracks.length) {
+        return {
+          ...turn,
+          status: 'error',
+          completion: event,
+          transportFailure: {
+            kind: 'protocol',
+            message: 'The final track count did not match the streamed results.',
+          },
+        }
+      }
+      return { ...turn, status: 'done', completion: event }
+  }
+}
+
+function playlistName(query: string): string {
+  return `[discovery-by-llm] ${query}`.slice(0, 100).trim()
+}
+
+function createTurnId(): string {
+  return typeof crypto.randomUUID === 'function'
+    ? crypto.randomUUID()
+    : `${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+/** Reduce recommendation streams into conversation view state. */
+export function useChatStream(createPlaylist: PlaylistCreator) {
+  const turns = ref<ChatTurn[]>([])
+  const eventLog = ref<EventLogEntry[]>([])
+  let activeController: AbortController | null = null
+  let activeTurnId: string | null = null
+
+  const isStreaming = computed(() =>
+    turns.value.some((turn) => turn.role === 'assistant' && turn.status === 'streaming'),
+  )
+  const turnCount = computed(() => turns.value.filter((turn) => turn.role === 'user').length)
+  const isEmpty = computed(() => turns.value.length === 0)
+  const latestAssistant = computed(() =>
+    [...turns.value].reverse().find((turn): turn is AssistantTurn => turn.role === 'assistant'),
+  )
+
+  function updateAssistant(id: string, update: (turn: AssistantTurn) => AssistantTurn): void {
+    turns.value = turns.value.map((turn) =>
+      turn.role === 'assistant' && turn.id === id ? update(turn) : turn,
+    )
+  }
+
+  function addLog(type: string, detail: string): void {
+    eventLog.value = [
+      ...eventLog.value,
+      { timestamp: new Date().toLocaleTimeString(), type, detail },
+    ].slice(-EVENT_LOG_LIMIT)
+  }
+
+  function cancelActive(shouldMarkTurn: boolean): void {
+    if (!activeController) return
+    activeController.abort()
+    if (shouldMarkTurn && activeTurnId) {
+      const failure: TransportFailure = {
+        kind: 'cancelled',
+        message: 'This request was replaced by a newer request.',
+      }
+      updateAssistant(activeTurnId, (turn) => ({
+        ...turn,
+        status: 'error',
+        transportFailure: failure,
+      }))
+    }
+    activeController = null
+    activeTurnId = null
+  }
+
+  async function send(query: string): Promise<void> {
+    const text = query.trim()
+    if (!text) return
+    cancelActive(true)
+
+    const request: RecommendationRequest = {
+      schema_version: 1,
+      query: text,
+      history: buildHistory(turns.value),
+      prior_recommendations: buildPriorRecommendations(turns.value),
+    }
+    const userTurn: ChatTurn = { id: createTurnId(), role: 'user', text }
+    const assistantTurn: AssistantTurn = {
+      id: createTurnId(),
+      role: 'assistant',
+      query: text,
+      status: 'streaming',
+      requestId: null,
+      intentSummary: '',
+      candidateCount: null,
+      tracks: [],
+      warnings: [],
+      error: null,
+      transportFailure: null,
+      completion: null,
+      playlist: { ...EMPTY_PLAYLIST_STATE },
+    }
+    turns.value = [...turns.value, userTurn, assistantTurn]
+
+    const controller = new AbortController()
+    activeController = controller
+    activeTurnId = assistantTurn.id
+
+    try {
+      await streamRecommendations(request, controller.signal, (event) => {
+        updateAssistant(assistantTurn.id, (turn) => reduceEvent(turn, event))
+        addLog(event.type, JSON.stringify(event))
+      })
+    } catch (error) {
+      if (isAbortError(error, controller.signal)) return
+      const failure: TransportFailure =
+        error instanceof StreamTransportError
+          ? { kind: error.kind, message: error.message }
+          : { kind: 'network', message: 'The recommendation request failed unexpectedly.' }
+      updateAssistant(assistantTurn.id, (turn) => ({
+        ...turn,
+        status: 'error',
+        transportFailure: failure,
+      }))
+      addLog('transport', `${failure.kind}: ${failure.message}`)
+    } finally {
+      if (activeController === controller) {
+        activeController = null
+        activeTurnId = null
+      }
+    }
+  }
+
+  async function savePlaylist(turnId: string): Promise<void> {
+    const turn = turns.value.find(
+      (candidate): candidate is AssistantTurn =>
+        candidate.role === 'assistant' && candidate.id === turnId,
+    )
+    if (
+      !turn ||
+      turn.status !== 'done' ||
+      turn.tracks.length === 0 ||
+      turn.playlist.status === 'saving' ||
+      turn.playlist.status === 'saved'
+    ) {
+      return
+    }
+
+    const name = playlistName(turn.query)
+    updateAssistant(turnId, (current) => ({
+      ...current,
+      playlist: { status: 'saving', name, url: null, message: null },
+    }))
+
+    try {
+      const response = await createPlaylist({
+        schema_version: 1,
+        name,
+        track_uris: turn.tracks.map((event) => event.track.uri),
+      })
+      updateAssistant(turnId, (current) => ({
+        ...current,
+        playlist: { status: 'saved', name, url: response.url, message: null },
+      }))
+    } catch {
+      updateAssistant(turnId, (current) => ({
+        ...current,
+        playlist: {
+          status: 'error',
+          name,
+          url: null,
+          message: 'Spotify could not create the playlist. Nothing was retried.',
+        },
+      }))
+    }
+  }
+
+  function reset(): void {
+    cancelActive(false)
+    turns.value = []
+    eventLog.value = []
+  }
+
+  onUnmounted(() => cancelActive(false))
+
+  return {
+    turns,
+    eventLog,
+    isStreaming,
+    turnCount,
+    isEmpty,
+    latestAssistant,
+    send,
+    savePlaylist,
+    reset,
+  }
+}