dsh-plugin-show-me-data 0.1.0

package/src/client/api.js

@@ -0,0 +1,323 @@
+/**
+ * The panel's single transport layer (docs/05 §3).
+ *
+ * Every call goes to the host half under '/api/show-me-data/*'; the browser never
+ * talks to an upstream data source (CORS and provenance both depend on that).
+ * Each request has a timeout, is cancellable, and turns a structured error
+ * payload into a value the UI can render instead of an exception the UI must
+ * catch blindly.
+ *
+ * @module client/api
+ */
+
+/** Request timeout in milliseconds (docs/05 §3). */
+export const REQUEST_TIMEOUT_MS = 8000
+
+/** The API root. */
+export const API_ROOT = '/api/show-me-data'
+
+/**
+ * Perform one JSON request.
+ *
+ * @param {string} path - path under {@link API_ROOT}, e.g. '/overview?range=1Y'.
+ * @param {{ method?: string, body?: any, signal?: AbortSignal, timeoutMs?: number, fetchImpl?: Function }} [options] - request options.
+ * @returns {Promise<{ ok: boolean, status: number, data?: any, error?: { kind: string, detail: string, retryable: boolean } }>} response.
+ */
+export async function request(path, { method = 'GET', body, signal, timeoutMs = REQUEST_TIMEOUT_MS, fetchImpl } = {}) {
+  const doFetch = fetchImpl ?? (typeof fetch === 'function' ? fetch : undefined)
+  if (doFetch === undefined) {
+    return { ok: false, status: 0, error: { kind: 'network', detail: 'fetch is unavailable in this environment', retryable: false } }
+  }
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  const composed = typeof AbortSignal !== 'undefined' && typeof AbortSignal.any === 'function' && signal !== undefined
+    ? AbortSignal.any([signal, controller.signal])
+    : controller.signal
+  try {
+    const response = await doFetch(`${API_ROOT}${path}`, {
+      method,
+      headers: body === undefined ? undefined : { 'content-type': 'application/json' },
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal: composed,
+    })
+    const text = await response.text()
+    let payload
+    try {
+      payload = text === '' ? undefined : JSON.parse(text)
+    } catch {
+      payload = undefined
+    }
+    if (!response.ok) {
+      return {
+        ok: false,
+        status: response.status,
+        // The payload rides along on failures too: a discussion whose session was
+        // created but whose first turn failed still returns its `sessionId`, and
+        // the panel needs it to offer 「打开会话」.
+        ...(payload === undefined ? {} : { data: payload }),
+        error: payload?.error ?? {
+          kind: response.status === 404 ? 'not-found' : 'http',
+          detail: `请求失败（HTTP ${response.status}）`,
+          retryable: response.status >= 500,
+        },
+      }
+    }
+    return { ok: true, status: response.status, data: payload }
+  } catch (error) {
+    const aborted = error?.name === 'AbortError'
+    return {
+      ok: false,
+      status: 0,
+      error: {
+        kind: aborted ? 'timeout' : 'network',
+        detail: aborted ? `请求超过 ${timeoutMs}ms 未返回` : `网络错误：${error?.message ?? error}`,
+        retryable: true,
+      },
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Start an SSE request, invoking handlers as events arrive.
+ *
+ * Uses 'fetch' + a stream reader rather than 'EventSource' so the POST payload
+ * and the caller's abort signal both work.
+ *
+ * @param {string} path - path under {@link API_ROOT}.
+ * @param {{ body?: any, signal?: AbortSignal, onText?: (text: string) => void, onDone?: (result: any) => void, onError?: (error: object) => void, fetchImpl?: Function }} options - options.
+ * @returns {Promise<{ ok: boolean, result?: any, error?: object }>} completion.
+ */
+export async function stream(path, { body, signal, onText, onDone, onError, fetchImpl } = {}) {
+  const doFetch = fetchImpl ?? (typeof fetch === 'function' ? fetch : undefined)
+  if (doFetch === undefined) {
+    const error = { kind: 'network', detail: 'fetch is unavailable', retryable: false }
+    onError?.(error)
+    return { ok: false, error }
+  }
+  try {
+    const response = await doFetch(`${API_ROOT}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', accept: 'text/event-stream' },
+      body: JSON.stringify(body ?? {}),
+      signal,
+    })
+    if (!response.ok || response.body === undefined || response.body === null) {
+      // The host answers with plain JSON when streaming is unsupported; accept it.
+      const text = await response.text()
+      try {
+        const parsed = JSON.parse(text)
+        onDone?.(parsed)
+        return { ok: true, result: parsed }
+      } catch {
+        const error = { kind: 'http', detail: `流式请求失败（HTTP ${response.status}）`, retryable: response.status >= 500 }
+        onError?.(error)
+        return { ok: false, error }
+      }
+    }
+    const reader = response.body.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    let result
+    for (;;) {
+      const { value, done } = await reader.read()
+      if (done) break
+      buffer += decoder.decode(value, { stream: true })
+      const frames = buffer.split('\n\n')
+      buffer = frames.pop() ?? ''
+      for (const frame of frames) {
+        const parsed = parseSseFrame(frame)
+        if (parsed === undefined) continue
+        if (parsed.event === 'text') onText?.(parsed.data?.text ?? '')
+        else if (parsed.event === 'done') {
+          result = parsed.data?.result
+          onDone?.(result)
+        } else if (parsed.event === 'error') onError?.({ kind: parsed.data?.kind ?? 'internal', detail: parsed.data?.detail ?? '', retryable: true })
+      }
+    }
+    return { ok: true, result }
+  } catch (error) {
+    const aborted = error?.name === 'AbortError'
+    const payload = { kind: aborted ? 'aborted' : 'network', detail: `${error?.message ?? error}`, retryable: !aborted }
+    onError?.(payload)
+    return { ok: false, error: payload }
+  }
+}
+
+/**
+ * Parse one SSE frame.
+ *
+ * @param {string} frame - frame text ('event: x\ndata: {...}').
+ * @returns {{ event: string, data: any }|undefined} parsed frame.
+ */
+export function parseSseFrame(frame) {
+  const trimmed = String(frame ?? '').trim()
+  if (trimmed === '') return undefined
+  let event = 'message'
+  const dataLines = []
+  for (const line of trimmed.split('\n')) {
+    if (line.startsWith('event:')) event = line.slice(6).trim()
+    else if (line.startsWith('data:')) dataLines.push(line.slice(5).trim())
+  }
+  if (dataLines.length === 0) return { event, data: undefined }
+  const raw = dataLines.join('\n')
+  try {
+    return { event, data: JSON.parse(raw) }
+  } catch {
+    return { event, data: raw }
+  }
+}
+
+/** The endpoints the panel uses, so no string is built ad hoc in a component. */
+export const api = {
+  /**
+   * @param {{ range?: string, groups?: string[], ids?: string[], limit?: number, force?: boolean, signal?: AbortSignal }} [options] - request.
+   * @returns {Promise<object>} response.
+   */
+  overview(options = {}) {
+    const query = []
+    if (options.range !== undefined) query.push(`range=${encodeURIComponent(options.range)}`)
+    if (options.groups !== undefined && options.groups.length > 0) query.push(`groups=${encodeURIComponent(options.groups.join(','))}`)
+    if (options.ids !== undefined && options.ids.length > 0) query.push(`ids=${encodeURIComponent(options.ids.join(','))}`)
+    if (options.limit !== undefined) query.push(`limit=${options.limit}`)
+    if (options.force === true) query.push('force=1')
+    return request(`/overview${query.length === 0 ? '' : `?${query.join('&')}`}`, { signal: options.signal })
+  },
+  /**
+   * @param {object} options - request.
+   * @returns {Promise<object>} response.
+   */
+  series(options) {
+    const query = [`indicator=${encodeURIComponent(options.indicator)}`]
+    if (options.range !== undefined) query.push(`range=${encodeURIComponent(options.range)}`)
+    if (options.transform !== undefined) query.push(`transform=${encodeURIComponent(options.transform)}`)
+    if (options.compareWith !== undefined) query.push(`compareWith=${encodeURIComponent(options.compareWith)}`)
+    if (options.freq !== undefined) query.push(`freq=${encodeURIComponent(options.freq)}`)
+    return request(`/series?${query.join('&')}`, { signal: options.signal })
+  },
+  /**
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response.
+   */
+  watchlist(signal) {
+    return request('/watchlist', { signal })
+  },
+  /**
+   * @param {object} body - action payload.
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response.
+   */
+  watchlistAction(body, signal) {
+    return request('/watchlist', { method: 'POST', body, signal })
+  },
+  /**
+   * @param {string} query - search text.
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response.
+   */
+  search(query, signal) {
+    return request(`/catalog/search?q=${encodeURIComponent(query)}`, { signal })
+  },
+  /**
+   * @param {object} body - '{ indicator, range }'.
+   * @param {object} handlers - SSE handlers.
+   * @returns {Promise<object>} completion.
+   */
+  explain(body, handlers = {}) {
+    return stream('/ai/explain', { body: { ...body, stream: true }, ...handlers })
+  },
+  /**
+   * @param {object} body - '{ range, indicators }'.
+   * @param {object} handlers - SSE handlers.
+   * @returns {Promise<object>} completion.
+   */
+  summary(body, handlers = {}) {
+    return stream('/ai/summary', { body: { ...body, stream: true }, ...handlers })
+  },
+  /**
+   * @param {object} body - '{ question, range }'.
+   * @param {object} handlers - SSE handlers.
+   * @returns {Promise<object>} completion.
+   */
+  ask(body, handlers = {}) {
+    return stream('/ai/ask', { body: { ...body, stream: true }, ...handlers })
+  },
+  /**
+   * @param {object} body - '{ text }'.
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response.
+   */
+  propose(body, signal) {
+    return request('/ai/propose', { method: 'POST', body, signal })
+  },
+  /**
+   * Open (or continue) an independent DSH session about one indicator.
+   *
+   * @param {{ indicator?: string, group?: string, noteworthy?: string[], question?: string, range?: string, mode?: 'new'|'topic', limit?: number }} body - request; exactly one of 'indicator'/'group' names the subject.
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response with `{ sessionId, reply, pending, mode }`.
+   */
+  discuss(body, signal) {
+    // `wait: false` returns as soon as the session exists and the question is
+    // queued: the answer streams in the session the GUI switches to, so the
+    // panel never blocks for the length of a model turn.
+    return request('/discuss', { method: 'POST', body: { wait: false, ...body }, signal, timeoutMs: 30_000 })
+  },
+  /**
+   * Analyse the panel as a whole, or one group of it.
+   *
+   * @param {{ range?: string, groups?: string[] }} body - request.
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response with `{ markdown, mode, scope, indicators, noteworthy }`.
+   */
+  aiOverview(body, signal) {
+    return request('/ai/overview', { method: 'POST', body, signal, timeoutMs: 120_000 })
+  },
+  /**
+   * Open a session in the plugin workspace to add a data source.
+   *
+   * @param {{ request?: string, reasons?: string[], question?: string }} body - request.
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response with `{ sessionId }`.
+   */
+  iterate(body, signal) {
+    return request('/iterate', { method: 'POST', body, signal, timeoutMs: 30_000 })
+  },
+  /**
+   * Collect the answer a discussion session produced.
+   *
+   * Opening a discussion returns before the model finishes, so the panel asks
+   * for the text on a short poll instead of leaving its block empty while the
+   * answer streams in a session the reader has to go and find.
+   *
+   * @param {string} sessionId - session id from `discuss()`.
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response with `{ status, reply?, error? }`.
+   */
+  discussAnswer(sessionId, signal) {
+    return request(`/discuss/answer?session=${encodeURIComponent(sessionId)}`, { signal, timeoutMs: 10_000 })
+  },
+  /**
+   * The mount's effective configuration, for the settings screen.
+   *
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response.
+   */
+  settings(signal) {
+    return request('/settings', { signal, timeoutMs: 10_000 })
+  },
+  /**
+   * @param {AbortSignal} [signal] - cancellation.
+   * @returns {Promise<object>} response.
+   */
+  health({ probe, ids, range } = {}, signal) {
+    const query = []
+    if (probe === true) query.push('probe=1')
+    if (Array.isArray(ids) && ids.length > 0) query.push(`ids=${encodeURIComponent(ids.join(','))}`)
+    if (range !== undefined) query.push(`range=${encodeURIComponent(range)}`)
+    // A probe re-fetches upstream series, so it needs a longer budget than a
+    // cached read.
+    return request(`/health${query.length === 0 ? '' : `?${query.join('&')}`}`, { signal, timeoutMs: probe === true ? 60_000 : REQUEST_TIMEOUT_MS })
+  },
+}