@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/features/client/AskAiProvider.tsx

@@ -0,0 +1,551 @@
+'use client'
+import {
+  Suspense,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+import {
+  AskAiInputSchema,
+  AskAiWidgetSettingsSchema,
+  type AskAiInput,
+  type AiSource,
+} from '../contracts'
+import { AskAiContext, type AskAiController } from './useAskAI'
+import { useSiteFeatures } from './context'
+import { PageReporter } from './PageReporter'
+import { emptyRecovery, mergeRecoveryPage, type RecoveryState } from './askAiRecovery'
+import { FeatureClientError, type createFeatureTransport } from './transport'
+const defaults = AskAiWidgetSettingsSchema.parse({})
+type Transport = ReturnType<typeof createFeatureTransport>
+const missing = (cause: unknown) =>
+  cause instanceof FeatureClientError &&
+  ['not_found', 'unauthorized', 'verification_required'].includes(cause.code)
+function errorCopy(cause: unknown, settings: typeof defaults) {
+  const code = cause instanceof FeatureClientError ? cause.code : null
+  if (code === 'budget_exceeded') return 'The Ask AI allowance has been reached. Please contact us.'
+  if (code === 'rate_limited') return 'Too many requests. Please wait before trying again.'
+  if (code === 'conflict')
+    return 'This request is still running or its history changed. Check the saved answer before retrying.'
+  if (missing(cause)) return 'This conversation is no longer available. Start a new conversation.'
+  if (typeof navigator !== 'undefined' && navigator.onLine === false)
+    return 'You are offline. Your partial answer is preserved. Reconnect to check the saved answer.'
+  return (
+    settings.errorMessage +
+    ' The answer may be incomplete. Check the saved answer or retry the same request.'
+  )
+}
+/** Root-owned state: presentations and pathname navigation do not own a paid request. */
+export function AskAiProvider({
+  children,
+  endpoint,
+  getTransport,
+}: {
+  children: ReactNode
+  endpoint: string
+  getTransport: () => Transport
+}) {
+  const runtime = useSiteFeatures(),
+    committed = useRef(runtime)
+  useLayoutEffect(() => {
+    committed.current = runtime
+  }, [runtime])
+  const [view, setView] = useState({
+      messages: [] as RecoveryState['messages'],
+      hasEarlier: false,
+      canRecover: false,
+      awaitingAnswer: false,
+      canRetry: false,
+      canNewAttempt: false,
+    }),
+    [draft, setDraft] = useState(''),
+    [status, setStatus] = useState<AskAiController['status']>('idle'),
+    [error, setError] = useState<string | null>(null),
+    [ratingError, setRatingError] = useState<string | null>(null),
+    [recovering, setRecovering] = useState(false),
+    [ratings, setRatings] = useState<Record<string, 'helpful' | 'unhelpful'>>({})
+  const data = useRef<RecoveryState>(emptyRecovery('')),
+    attempt = useRef<AskAiInput | null>(null),
+    terminal = useRef(false),
+    alive = useRef(false),
+    operation = useRef<AbortController | null>(null),
+    pending = useRef<Promise<void> | null>(null),
+    epoch = useRef(0),
+    page = useRef<string | null>(null),
+    titleReady = useRef(false),
+    ratingWork = useRef(
+      new Map<
+        string,
+        { requestId: string; rating: 'helpful' | 'unhelpful'; pending?: Promise<void> }
+      >(),
+    )
+  const storageKey = 'u90.askAi:' + endpoint
+  const redraw = useCallback(
+    () =>
+      setView({
+        messages: [...data.current.messages],
+        hasEarlier: Boolean(data.current.cursor),
+        canRecover: Boolean(data.current.conversationId),
+        awaitingAnswer:
+          !attempt.current &&
+          data.current.messages.some(
+            (message) =>
+              message.role === 'assistant' && ['queued', 'streaming'].includes(message.state),
+          ),
+        canRetry: Boolean(attempt.current && !terminal.current && !pending.current),
+        canNewAttempt: Boolean(attempt.current && terminal.current && !pending.current),
+      }),
+    [],
+  )
+  const invalidate = useCallback(() => {
+    epoch.current++
+  }, [])
+  const persist = useCallback(
+    (id: string) => {
+      try {
+        if (id) window.sessionStorage.setItem(storageKey, id)
+        else window.sessionStorage.removeItem(storageKey)
+      } catch {}
+    },
+    [storageKey],
+  )
+  const clear = useCallback(() => {
+    epoch.current++
+    operation.current?.abort()
+    operation.current = null
+    pending.current = null
+    attempt.current = null
+    terminal.current = false
+    data.current = emptyRecovery('')
+    ratingWork.current.clear()
+    persist('')
+    setRatings({})
+    setRatingError(null)
+    setDraft('')
+    setStatus('idle')
+    setRecovering(false)
+    setError(null)
+    redraw()
+  }, [persist, redraw])
+  useLayoutEffect(() => {
+    alive.current = true
+    return () => {
+      alive.current = false
+      invalidate()
+      operation.current?.abort()
+    }
+  }, [invalidate])
+  const settings = runtime.config?.askAi ?? defaults
+  const enabled = Boolean(runtime.config?.enabled.askAi)
+  useLayoutEffect(() => {
+    if (!enabled && operation.current) {
+      epoch.current++
+      operation.current.abort()
+      operation.current = null
+      pending.current = null
+      setRecovering(false)
+      setStatus('error')
+      setError('Ask AI is currently unavailable. Your answer may be incomplete.')
+      redraw()
+    }
+  }, [enabled, redraw])
+  const report = useCallback((path: string) => {
+    if (page.current !== path) {
+      titleReady.current = page.current === null
+      page.current = path
+    }
+  }, [])
+  const titleChanged = useCallback(() => {
+    titleReady.current = page.current === window.location.pathname
+  }, [])
+  const read = useCallback(
+    async (signal: AbortSignal, current: () => boolean, continuation = false) => {
+      if (!data.current.conversationId) return
+      setRecovering(true)
+      if (!continuation)
+        data.current = { ...data.current, cursor: null, snapshot: null, fragments: new Map() }
+      let bytes = 0
+      for (let count = 0; count < 4; count++) {
+        const id = data.current.conversationId,
+          cursor = data.current.cursor
+        let result
+        try {
+          result = await getTransport().aiConversation(id, cursor, signal)
+        } catch (cause) {
+          if (current() && cause instanceof FeatureClientError && cause.code === 'conflict') {
+            data.current = { ...data.current, cursor: null, snapshot: null, fragments: new Map() }
+            setError('History changed. Check the saved answer again.')
+            return
+          }
+          throw cause
+        }
+        if (!current() || id !== data.current.conversationId) return
+        bytes += new TextEncoder().encode(JSON.stringify(result)).length
+        if (bytes > 524288) throw new FeatureClientError('too_large')
+        data.current = mergeRecoveryPage(data.current, result)
+        redraw()
+        if (!data.current.cursor) break
+      }
+      const last =
+        attempt.current &&
+        data.current.messages.find(
+          (m) => m.requestId === attempt.current!.requestId && m.role === 'assistant',
+        )
+      if (last && ['completed', 'failed', 'aborted', 'unknown'].includes(last.state)) {
+        terminal.current = true
+        if (last.state === 'completed') {
+          attempt.current = null
+          setStatus('idle')
+          setError(null)
+        }
+      }
+      if (!attempt.current) {
+        setStatus('idle')
+        setError(null)
+      }
+      setRecovering(false)
+    },
+    [getTransport, redraw],
+  )
+  const recover = useCallback(
+    (continuation = false): Promise<void> => {
+      if (
+        pending.current ||
+        !alive.current ||
+        !committed.current.config?.enabled.askAi ||
+        !data.current.conversationId
+      )
+        return pending.current ?? Promise.resolve()
+      const controller = new AbortController(),
+        generation = epoch.current
+      operation.current = controller
+      const current = () =>
+        alive.current &&
+        generation === epoch.current &&
+        operation.current === controller &&
+        !controller.signal.aborted &&
+        Boolean(committed.current.config?.enabled.askAi)
+      const work = Promise.resolve()
+        .then(() => read(controller.signal, current, continuation))
+        .catch((cause) => {
+          if (current()) {
+            if (missing(cause)) clear()
+            setError(errorCopy(cause, committed.current.config?.askAi ?? defaults))
+            setStatus('error')
+          }
+        })
+        .finally(() => {
+          if (operation.current === controller) {
+            operation.current = null
+            pending.current = null
+            setRecovering(false)
+            redraw()
+          }
+        })
+      pending.current = work
+      redraw()
+      return work
+    },
+    [read, clear, redraw],
+  )
+  const resumed = useRef(false)
+  useEffect(() => {
+    if (!enabled || resumed.current) return
+    resumed.current = true
+    let id: string | null = null
+    try {
+      id = window.sessionStorage.getItem(storageKey)
+    } catch {}
+    if (id && /^[A-Za-z0-9_-]{1,128}$/.test(id)) {
+      data.current = emptyRecovery(id)
+      void recover()
+    } else persist('')
+  }, [enabled, storageKey, recover, persist])
+  const run = useCallback((): Promise<void> => {
+    if (
+      pending.current ||
+      !attempt.current ||
+      terminal.current ||
+      !alive.current ||
+      !committed.current.config?.enabled.askAi
+    )
+      return pending.current ?? Promise.resolve()
+    const body = attempt.current,
+      controller = new AbortController(),
+      generation = epoch.current,
+      signal = AbortSignal.any([controller.signal, AbortSignal.timeout(90000)])
+    // Keep the last usable display while a same-ID replay assembles independently.
+    // Only its terminal result (or authoritative GET recovery) replaces prior content.
+    const retainDisplay = data.current.messages.some(
+      (message) =>
+        message.requestId === body.requestId &&
+        message.role === 'assistant' &&
+        (message.text.length > 0 || message.sources.length > 0),
+    )
+    let replayText = ''
+    let replaySources: AiSource[] = []
+    operation.current = controller
+    setStatus('sending')
+    setError(null)
+    const current = () =>
+      alive.current &&
+      generation === epoch.current &&
+      operation.current === controller &&
+      !signal.aborted &&
+      Boolean(committed.current.config?.enabled.askAi)
+    const work = Promise.resolve()
+      .then(async () => {
+        await committed.current.ensureSession(signal)
+        if (!current()) return
+        await getTransport().aiMessage(body, signal, (event) => {
+          if (!current()) return
+          if (event.type === 'start') {
+            if (data.current.conversationId && data.current.conversationId !== event.conversationId)
+              throw new FeatureClientError()
+            data.current.conversationId = event.conversationId
+            persist(event.conversationId)
+            data.current.messages = data.current.messages.map((m) =>
+              m.requestId === body.requestId && m.role === 'assistant'
+                ? { ...m, id: event.messageId, state: 'streaming' }
+                : m,
+            )
+            setStatus('streaming')
+          } else if (
+            event.type === 'delta' ||
+            event.type === 'sources' ||
+            event.type === 'done' ||
+            event.type === 'error'
+          ) {
+            if (event.type === 'delta') replayText += event.text
+            if (event.type === 'sources') replaySources = event.sources
+            data.current.messages = data.current.messages.map((m) =>
+              m.requestId === body.requestId && m.role === 'assistant'
+                ? {
+                    ...m,
+                    ...(event.type === 'delta'
+                      ? retainDisplay
+                        ? {}
+                        : { text: replayText }
+                      : event.type === 'sources'
+                        ? retainDisplay
+                          ? {}
+                          : { sources: replaySources }
+                        : { text: replayText, sources: replaySources, state: event.state }),
+                  }
+                : m,
+            )
+            if (event.type === 'done') {
+              terminal.current = true
+              attempt.current = null
+              setStatus('idle')
+              committed.current.announce('Answer complete.')
+            }
+            if (event.type === 'error') {
+              terminal.current = true
+              setStatus('error')
+              setError(
+                errorCopy(
+                  new FeatureClientError(event.code),
+                  committed.current.config?.askAi ?? defaults,
+                ),
+              )
+            }
+          }
+          redraw()
+        })
+      })
+      .catch(async (cause) => {
+        if (!alive.current || generation !== epoch.current || operation.current !== controller)
+          return
+        if (missing(cause)) {
+          clear()
+          setError(errorCopy(cause, committed.current.config?.askAi ?? defaults))
+          return
+        }
+        data.current.messages = data.current.messages.map((m) =>
+          m.requestId === body.requestId &&
+          m.role === 'assistant' &&
+          !['completed', 'failed', 'aborted'].includes(m.state)
+            ? { ...m, state: 'unknown' }
+            : m,
+        )
+        setStatus('error')
+        setError(errorCopy(cause, committed.current.config?.askAi ?? defaults))
+        redraw()
+        if (current() && data.current.conversationId)
+          try {
+            await read(signal, current)
+          } catch (recoveryError) {
+            if (current() && missing(recoveryError)) {
+              clear()
+              setError(errorCopy(recoveryError, committed.current.config?.askAi ?? defaults))
+            }
+          }
+      })
+      .finally(() => {
+        if (operation.current === controller) {
+          operation.current = null
+          pending.current = null
+          setRecovering(false)
+          redraw()
+        }
+      })
+    pending.current = work
+    redraw()
+    return work
+  }, [getTransport, persist, redraw, clear, read])
+  const send = useCallback(
+    (message: string, newAttempt = false): Promise<void> => {
+      if (pending.current) return pending.current
+      if (attempt.current) {
+        setError('Check or retry the current answer, or explicitly start a new attempt.')
+        return Promise.resolve()
+      }
+      if (!alive.current || !committed.current.config?.enabled.askAi) return Promise.resolve()
+      if (!page.current || page.current !== window.location.pathname) {
+        setError('The page is changing. Please try again once it is ready.')
+        return Promise.resolve()
+      }
+      const parsed = AskAiInputSchema.safeParse({
+        requestId: crypto.randomUUID(),
+        ...(data.current.conversationId ? { conversationId: data.current.conversationId } : {}),
+        message,
+        page: {
+          path: page.current,
+          ...(titleReady.current && document.title ? { title: document.title.slice(0, 200) } : {}),
+        },
+      })
+      if (!parsed.success) {
+        setError('Enter a message of up to 2,000 characters.')
+        return Promise.resolve()
+      }
+      terminal.current = false
+      attempt.current = parsed.data
+      const sequence = Math.max(-1, ...data.current.messages.map((m) => m.sequence)) + 1
+      data.current.messages.push(
+        {
+          id: 'user-' + parsed.data.requestId,
+          requestId: parsed.data.requestId,
+          role: 'user',
+          text: parsed.data.message,
+          sources: [],
+          state: 'completed',
+          sequence,
+          newAttempt,
+        },
+        {
+          id: 'assistant-' + parsed.data.requestId,
+          requestId: parsed.data.requestId,
+          role: 'assistant',
+          text: '',
+          sources: [],
+          state: 'queued',
+          sequence: sequence + 1,
+        },
+      )
+      setDraft('')
+      redraw()
+      return run()
+    },
+    [run, redraw],
+  )
+  const retryAnswer = useCallback(() => {
+    if (!terminal.current || !attempt.current || pending.current) return Promise.resolve()
+    const message = attempt.current.message
+    attempt.current = null
+    return send(message, true)
+  }, [send])
+  const stop = useCallback(() => {
+    operation.current?.abort()
+    setStatus('error')
+    setError('Stopped. Your answer may be incomplete; check the saved answer before retrying.')
+    data.current.messages = data.current.messages.map((m) =>
+      m.state === 'streaming' || m.state === 'queued' ? { ...m, state: 'unknown' } : m,
+    )
+    redraw()
+  }, [redraw])
+  const rate = useCallback(
+    (id: string, rating: 'helpful' | 'unhelpful'): Promise<void> => {
+      const message = data.current.messages.find(
+        (m) =>
+          m.id === id &&
+          m.role === 'assistant' &&
+          ['completed', 'failed', 'aborted', 'unknown'].includes(m.state),
+      )
+      if (!message || !committed.current.config?.enabled.askAi) return Promise.resolve()
+      const existing = ratingWork.current.get(id)
+      if (existing?.pending) return existing.pending
+      const receipt =
+        existing?.rating === rating ? existing : { requestId: crypto.randomUUID(), rating }
+      ratingWork.current.set(id, receipt)
+      const generation = epoch.current
+      const current = () =>
+        alive.current &&
+        generation === epoch.current &&
+        Boolean(committed.current.config?.enabled.askAi)
+      const work = getTransport()
+        .aiRating(
+          id,
+          { requestId: receipt.requestId, rating: receipt.rating },
+          AbortSignal.timeout(10000),
+        )
+        .then(() => {
+          if (current()) {
+            setRatings((r) => ({ ...r, [id]: rating }))
+            setRatingError(null)
+            ratingWork.current.delete(id)
+          }
+        })
+        .catch((cause) => {
+          if (current()) {
+            if (missing(cause)) clear()
+            setRatingError(errorCopy(cause, committed.current.config?.askAi ?? defaults))
+          }
+        })
+        .finally(() => {
+          delete receipt.pending
+        })
+      receipt.pending = work
+      return work
+    },
+    [getTransport, clear],
+  )
+  const value: Omit<AskAiController, 'launcherRef'> = {
+    open: runtime.overlay.active === 'askAi',
+    messages: view.messages,
+    status,
+    error,
+    ratingError,
+    settings,
+    draft,
+    setDraft,
+    recovering,
+    hasEarlier: view.hasEarlier,
+    canRecover: view.canRecover,
+    awaitingAnswer: view.awaitingAnswer,
+    canRetry: view.canRetry,
+    canNewAttempt: view.canNewAttempt,
+    ratings,
+    show: () => runtime.overlay.open('askAi'),
+    hide: runtime.overlay.close,
+    send,
+    stop,
+    startNewConversation: clear,
+    retry: run,
+    retryAnswer,
+    recover: () => recover(),
+    loadEarlier: () => recover(true),
+    rate,
+  }
+  return (
+    <AskAiContext.Provider value={value}>
+      <Suspense fallback={null}>
+        <PageReporter report={report} titleChanged={titleChanged} />
+      </Suspense>
+      {children}
+    </AskAiContext.Provider>
+  )
+}