Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

9.8 KB
Raw Blame
// Reads the end user's earlier conversations from the session server with the
// session token. Like the session upload, a request never goes through the
// shared API wrapper and never touches the browser's stored login token: the
// only credential is the session token, sent in a header.

export const WIDGET_SESSION_CONVERSATIONS_PATH = "/v1/external/chat/sessions/conversations"

// The upper bound on one attempt, from sending the request until its body has
// been read and has passed the shape check. It keeps a visitor from waiting
// without end; it is not a performance target.
export const HISTORY_REQUEST_TIMEOUT_MS = 20_000

// "disabled" is the server's 403 and "not_found" its 404; the response body is
// never read to tell them apart. "unauthorized" is a 401 that was not
// refreshed. Everything else is "load_failed", except a caller abort, which
// fails as an AbortError like the session upload's.
export type WidgetSessionHistoryErrorKind = "not_found" | "disabled" | "unauthorized" | "load_failed"

export class WidgetSessionHistoryError extends Error {
  readonly kind: WidgetSessionHistoryErrorKind

  constructor(kind: WidgetSessionHistoryErrorKind) {
    super(kind)
    this.name = "WidgetSessionHistoryError"
    this.kind = kind
  }
}

export interface WidgetSessionHistoryAuth {
  getToken: () => Promise<string>
  // Absent: a 401 is not refreshed and fails as "unauthorized".
  refreshToken?: (rejectedToken: string) => Promise<string>
}

export interface WidgetConversationSummary {
  taskId: number
  title: string
  createdAt: string
}

export interface WidgetConversationAttachment {
  filename: string
  fileSize: number | null
  mimeType: string | null
}

export interface WidgetConversationMessage {
  id: number
  role: "user" | "assistant"
  content: string
  createdAt: string
  attachments: WidgetConversationAttachment[]
}

export interface WidgetSessionHistoryPage {
  limit?: number
  cursor?: string | null
}

const loadFailed = () => new WidgetSessionHistoryError("load_failed")

const abortError = (): DOMException => new DOMException("The read was aborted.", "AbortError")

// Waits for `promise` unless `signal` aborts first. The abort settles only
// this caller's wait; the promise itself, which may be shared, keeps running.
const raceAbort = <T,>(promise: Promise<T>, signal?: AbortSignal): Promise<T> => {
  if (!signal) return promise
  return new Promise<T>((resolve, reject) => {
    const onAbort = () => reject(abortError())
    signal.addEventListener("abort", onAbort, { once: true })
    // Attached before the check below, so a promise that rejects after this
    // wait was aborted is still handled.
    promise.then(
      (value) => { signal.removeEventListener("abort", onAbort); resolve(value) },
      (error) => { signal.removeEventListener("abort", onAbort); reject(error) },
    )
    // The source may have aborted the signal while it was being called, which
    // is before this listener existed.
    if (signal.aborted) onAbort()
  })
}

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value)

const isPositiveInteger = (value: unknown): value is number =>
  typeof value === "number" && Number.isInteger(value) && value > 0

const isCursor = (value: unknown): value is string | null =>
  value === null || typeof value === "string"

// Each parser returns only what it has checked, or null for any other shape.
const parseConversationPage = (
  body: unknown,
): { conversations: WidgetConversationSummary[]; nextCursor: string | null } | null => {
  if (!isRecord(body) || !Array.isArray(body.conversations) || !isCursor(body.next_cursor)) return null
  const conversations: WidgetConversationSummary[] = []
  for (const entry of body.conversations) {
    if (
      !isRecord(entry)
      || !isPositiveInteger(entry.task_id)
      || typeof entry.title !== "string"
      || typeof entry.created_at !== "string"
    ) {
      return null
    }
    conversations.push({ taskId: entry.task_id, title: entry.title, createdAt: entry.created_at })
  }
  return { conversations, nextCursor: body.next_cursor }
}

const parseAttachment = (entry: unknown): WidgetConversationAttachment | null => {
  if (
    !isRecord(entry)
    || typeof entry.filename !== "string"
    || !(entry.file_size === null || typeof entry.file_size === "number")
    || !(entry.mime_type === null || typeof entry.mime_type === "string")
  ) {
    return null
  }
  return { filename: entry.filename, fileSize: entry.file_size, mimeType: entry.mime_type }
}

const parseMessagePage = (
  body: unknown,
): { messages: WidgetConversationMessage[]; nextCursor: string | null } | null => {
  if (!isRecord(body) || !Array.isArray(body.messages) || !isCursor(body.next_cursor)) return null
  const messages: WidgetConversationMessage[] = []
  for (const entry of body.messages) {
    if (
      !isRecord(entry)
      || !isPositiveInteger(entry.id)
      || (entry.role !== "user" && entry.role !== "assistant")
      || typeof entry.content !== "string"
      || typeof entry.created_at !== "string"
      || !Array.isArray(entry.attachments)
    ) {
      return null
    }
    const attachments: WidgetConversationAttachment[] = []
    for (const item of entry.attachments) {
      const attachment = parseAttachment(item)
      if (!attachment) return null
      attachments.push(attachment)
    }
    messages.push({
      id: entry.id,
      role: entry.role,
      content: entry.content,
      createdAt: entry.created_at,
      attachments,
    })
  }
  return { messages, nextCursor: body.next_cursor }
}

type AttemptResult<T> = { kind: "ok"; value: T } | { kind: "unauthorized" }

// One request under its own deadline, which covers the body read and the shape
// check. A caller abort or the deadline aborts the request.
const attempt = async <T,>(
  url: string,
  token: string,
  parse: (body: unknown) => T | null,
  signal: AbortSignal | undefined,
): Promise<AttemptResult<T>> => {
  const controller = new AbortController()
  const abort = () => controller.abort()
  signal?.addEventListener("abort", abort, { once: true })
  let timer: ReturnType<typeof setTimeout> | undefined
  const deadline = new Promise<never>((_resolve, reject) => {
    timer = setTimeout(() => {
      controller.abort()
      reject(loadFailed())
    }, HISTORY_REQUEST_TIMEOUT_MS)
  })
  const run = async (): Promise<AttemptResult<T>> => {
    let response: Response
    try {
      response = await fetch(url, {
        method: "GET",
        headers: { Authorization: `Bearer ${token}` },
        credentials: "omit",
        signal: controller.signal,
      })
    } catch {
      throw loadFailed()
    }
    if (response.status === 401) return { kind: "unauthorized" }
    if (response.status === 403) throw new WidgetSessionHistoryError("disabled")
    if (response.status === 404) throw new WidgetSessionHistoryError("not_found")
    if (response.status !== 200) throw loadFailed()
    let body: unknown
    try {
      body = await response.json()
    } catch {
      throw loadFailed()
    }
    const value = parse(body)
    if (value === null) throw loadFailed()
    return { kind: "ok", value }
  }
  try {
    return await Promise.race([run(), deadline])
  } finally {
    clearTimeout(timer)
    signal?.removeEventListener("abort", abort)
  }
}

const request = async <T,>(
  origin: string,
  path: string,
  auth: WidgetSessionHistoryAuth,
  page: WidgetSessionHistoryPage,
  parse: (body: unknown) => T | null,
  signal: AbortSignal | undefined,
): Promise<T> => {
  // Only the page options go into the query string; the token never does.
  const query = new URLSearchParams()
  if (page.limit !== undefined) query.set("limit", String(page.limit))
  if (page.cursor !== undefined && page.cursor !== null) query.set("cursor", page.cursor)
  const search = query.toString()
  const url = `${origin}${path}${search ? `?${search}` : ""}`

  // Checked after every wait, so an aborted read neither sends a request nor
  // asks for a refreshed token.
  const ensureActive = () => {
    if (signal?.aborted) throw abortError()
  }
  // A token wait is not covered by the request deadline, so it is raced
  // against the caller's signal: an abort ends the read even while a token is
  // still pending.
  const obtain = async (source: () => Promise<string>): Promise<string> => {
    let token: string
    try {
      token = await raceAbort(source(), signal)
    } catch {
      throw loadFailed()
    }
    ensureActive()
    return token
  }

  try {
    ensureActive()
    const token = await obtain(auth.getToken)
    const first = await attempt(url, token, parse, signal)
    ensureActive()
    if (first.kind === "ok") return first.value
    const refreshToken = auth.refreshToken
    if (!refreshToken) throw new WidgetSessionHistoryError("unauthorized")
    const refreshed = await obtain(() => refreshToken(token))
    const retry = await attempt(url, refreshed, parse, signal)
    ensureActive()
    if (retry.kind === "ok") return retry.value
    throw loadFailed()
  } catch (error) {
    // Whatever the request ran into, a read the caller aborted fails as
    // aborted.
    ensureActive()
    throw error
  }
}

export function listWidgetConversations(
  origin: string,
  auth: WidgetSessionHistoryAuth,
  page: WidgetSessionHistoryPage,
  signal?: AbortSignal,
): Promise<{ conversations: WidgetConversationSummary[]; nextCursor: string | null }> {
  return request(origin, WIDGET_SESSION_CONVERSATIONS_PATH, auth, page, parseConversationPage, signal)
}

export function readWidgetConversation(
  origin: string,
  auth: WidgetSessionHistoryAuth,
  taskId: number,
  page: WidgetSessionHistoryPage,
  signal?: AbortSignal,
): Promise<{ messages: WidgetConversationMessage[]; nextCursor: string | null }> {
  return request(
    origin,
    `${WIDGET_SESSION_CONVERSATIONS_PATH}/${taskId}/messages`,
    auth,
    page,
    parseMessagePage,
    signal,
  )
}