@frontera-sdk/knowledge 0.0.0-stage → 1.53.17

package/src/wait-until-ready.ts

@@ -0,0 +1,120 @@
+import { FronteraError } from '@frontera-sdk/core/errors'
+
+import type { KnowledgeClient } from './knowledge-client'
+import { SETTLED_STATUSES, type DocumentStatus, type KnowledgeDocument, type UploadResult } from './types'
+
+export type WaitOptions = {
+  /** The first pause between polls; each later pause is half as long again, up to `maxIntervalMs`. 1,500 ms by default. */
+  intervalMs?: number
+  /** 10,000 ms by default. */
+  maxIntervalMs?: number
+  /** 10 minutes by default. Past it the wait throws `KNOWLEDGE_WAIT_TIMEOUT` and leaves the documents as they are. */
+  timeoutMs?: number
+  signal?: AbortSignal
+  /** Every poll's answer, for progress; the next poll waits for it to finish. */
+  onPoll?: (documents: readonly KnowledgeDocument[]) => void | Promise<void>
+  /**
+   * Sends one document's file again, at most once per document. The wait calls
+   * it when an upload did not get its file stored: the document vanished before
+   * its malware check finished (the earlier upload of the same bytes it was
+   * answered with failed to store them), or it failed with `errorKind`
+   * `storage` (an upload cut short). Answer what the upload answers. Without
+   * it, such a document ends as it is: missing, or failed. A document that
+   * vanishes later was removed by someone, and is never sent again.
+   */
+  resend?: (documentId: string) => Promise<UploadResult>
+}
+
+export type WaitResult = {
+  /** The settled documents in the order asked; one sent again is the document its new upload answered. */
+  documents: KnowledgeDocument[]
+  /** The asked ids that are gone or that the caller cannot see, including one whose sending again failed. */
+  missing: string[]
+}
+
+/** An upload whose file was never stored: sending the same bytes again stores them in that document. */
+const cutShort = (document: KnowledgeDocument) => document.status === 'failed' && document.errorKind === 'storage' && !document.searchable
+
+/**
+ * What one poll says about a document, given the status the wait saw last
+ * (null before the first): still on its way, settled, gone and staying gone,
+ * or worth sending again. A document gone before its malware check finished
+ * lost its file with the upload it duplicated; one gone after was removed.
+ */
+function pollVerdict(document: KnowledgeDocument | undefined, lastSeen: DocumentStatus | null): 'waiting' | 'settled' | 'gone' | 'send again' {
+  if (!document) return lastSeen === null || lastSeen === 'scanning' ? 'send again' : 'gone'
+  if (cutShort(document)) return 'send again'
+  return SETTLED_STATUSES.has(document.status) ? 'settled' : 'waiting'
+}
+
+type Slot = { asked: string; id: string; lastSeen: DocumentStatus | null; resent: boolean; end?: KnowledgeDocument | 'gone' }
+
+/**
+ * Polls `POST /documents/status`, 200 ids a request, until every document is
+ * settled (`ready`, `failed` or `blocked`) or gone. It never throws for a
+ * failed or blocked document: read each one's `status`.
+ */
+export async function waitUntilReady(knowledge: KnowledgeClient, ids: readonly string[], options: WaitOptions = {}): Promise<WaitResult> {
+  const { intervalMs = 1500, maxIntervalMs = 10_000, timeoutMs = 10 * 60_000, signal, onPoll, resend } = options
+  const slots: Slot[] = [...new Set(ids)].map((id) => ({ asked: id, id, lastSeen: null, resent: false }))
+  const deadline = Date.now() + timeoutMs
+  let pause = intervalMs
+  for (;;) {
+    throwIfAborted(signal)
+    const open = slots.filter((slot) => slot.end === undefined)
+    if (open.length === 0) break
+    const { documents } = await knowledge.documents.status(open.map((slot) => slot.id), signal)
+    await onPoll?.(documents)
+    const byId = new Map(documents.map((document) => [document.id, document]))
+    for (const slot of open) {
+      const document = byId.get(slot.id)
+      const verdict = pollVerdict(document, slot.lastSeen)
+      if (document) slot.lastSeen = document.status
+      if (verdict === 'send again' && resend && !slot.resent) {
+        slot.resent = true
+        try {
+          const again = await resend(slot.id)
+          slot.id = again.document.id
+          slot.lastSeen = again.document.status
+        } catch {
+          slot.end = 'gone'
+        }
+      } else if (verdict !== 'waiting') {
+        slot.end = document ?? 'gone'
+      }
+    }
+    if (slots.every((slot) => slot.end !== undefined)) break
+    if (Date.now() >= deadline) {
+      const waiting = slots.filter((slot) => slot.end === undefined)
+      throw new FronteraError(`${waiting.length} of ${slots.length} documents did not settle within ${timeoutMs} ms`, {
+        code: 'KNOWLEDGE_WAIT_TIMEOUT',
+        details: { waiting: waiting.map((slot) => ({ id: slot.id, status: slot.lastSeen })) },
+      })
+    }
+    await sleep(Math.min(pause, deadline - Date.now()), signal)
+    pause = Math.min(maxIntervalMs, pause * 1.5)
+  }
+  return {
+    documents: slots.flatMap((slot) => (slot.end && slot.end !== 'gone' ? [slot.end] : [])),
+    missing: slots.filter((slot) => slot.end === 'gone').map((slot) => slot.asked),
+  }
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new FronteraError('Knowledge wait was aborted', { code: 'ABORTED', details: { reason: signal.reason } })
+}
+
+/** Resolves after `ms`, or as soon as `signal` aborts. */
+export function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort)
+      resolve()
+    }, Math.max(0, ms))
+    function onAbort() {
+      clearTimeout(timer)
+      resolve()
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}

package/src/wire-types.ts

@@ -0,0 +1,588 @@
+/**
+ * Generated from the service's Knowledge schemas by `bun run sdk:knowledge-wire`.
+ * Do not edit: a service test fails while this file differs from what the
+ * generator writes. Each `…Answer` is what one route answers; a date is its
+ * ISO string.
+ */
+
+export type CapabilitiesAnswer = {
+  steward: boolean
+  canAssignStewards: boolean
+  canCreate: boolean
+}
+
+export type BasesAnswer = {
+  bases: Array<{
+    id: string
+    orgId: string
+    ownerWorkspaceId: string | null
+    name: string
+    description: string | null
+    createdBy: string
+    createdAt: string
+    updatedAt: string
+    canManage: boolean
+    sharing: {
+      allWorkspaces: boolean
+      workspaceIds: string[]
+    } | null
+  }>
+}
+
+export type BaseAnswer = {
+  base: {
+    id: string
+    orgId: string
+    ownerWorkspaceId: string | null
+    name: string
+    description: string | null
+    createdBy: string
+    createdAt: string
+    updatedAt: string
+    canManage: boolean
+    sharing: {
+      allWorkspaces: boolean
+      workspaceIds: string[]
+    } | null
+  }
+}
+
+export type CreatedBaseAnswer = {
+  base: {
+    id: string
+    orgId: string
+    ownerWorkspaceId: string | null
+    name: string
+    description: string | null
+    createdBy: string
+    createdAt: string
+    updatedAt: string
+    canManage: boolean
+    sharing: {
+      allWorkspaces: boolean
+      workspaceIds: string[]
+    } | null
+  }
+}
+
+export type DeletedBaseAnswer = {
+  base: {
+    id: string
+    documents: number
+  }
+}
+
+export type DocumentsAnswer = {
+  documents: Array<{
+    id: string
+    orgId: string
+    knowledgeBaseId: string | null
+    title: string
+    fileName: string | null
+    mimeType: string | null
+    byteSize: number | null
+    status: 'scanning' | 'pending' | 'processing' | 'ready' | 'failed' | 'blocked'
+    searchable: boolean
+    error: string | null
+    errorKind: string | null
+    viewUrl: string | null
+    createdBy: string | null
+    addedByKey: {
+      name: string | null
+    } | null
+    source: {
+      id: string
+      name: string
+      url: string | null
+    } | null
+    createdAt: string
+    updatedAt: string
+  }>
+  nextCursor: string | null
+}
+
+export type DocumentAnswer = {
+  document: {
+    id: string
+    orgId: string
+    knowledgeBaseId: string | null
+    title: string
+    fileName: string | null
+    mimeType: string | null
+    byteSize: number | null
+    status: 'scanning' | 'pending' | 'processing' | 'ready' | 'failed' | 'blocked'
+    searchable: boolean
+    error: string | null
+    errorKind: string | null
+    viewUrl: string | null
+    createdBy: string | null
+    addedByKey: {
+      name: string | null
+    } | null
+    source: {
+      id: string
+      name: string
+      url: string | null
+    } | null
+    createdAt: string
+    updatedAt: string
+  }
+}
+
+export type UploadedAnswer = {
+  document: {
+    id: string
+    orgId: string
+    knowledgeBaseId: string | null
+    title: string
+    fileName: string | null
+    mimeType: string | null
+    byteSize: number | null
+    status: 'scanning' | 'pending' | 'processing' | 'ready' | 'failed' | 'blocked'
+    searchable: boolean
+    error: string | null
+    errorKind: string | null
+    viewUrl: string | null
+    createdBy: string | null
+    addedByKey: {
+      name: string | null
+    } | null
+    source: {
+      id: string
+      name: string
+      url: string | null
+    } | null
+    createdAt: string
+    updatedAt: string
+  }
+  duplicate: boolean
+}
+
+export type DocumentDetailsAnswer = {
+  document: {
+    id: string
+    orgId: string
+    knowledgeBaseId: string | null
+    title: string
+    fileName: string | null
+    mimeType: string | null
+    byteSize: number | null
+    status: 'scanning' | 'pending' | 'processing' | 'ready' | 'failed' | 'blocked'
+    searchable: boolean
+    error: string | null
+    errorKind: string | null
+    viewUrl: string | null
+    createdBy: string | null
+    addedByKey: {
+      name: string | null
+    } | null
+    source: {
+      id: string
+      name: string
+      url: string | null
+    } | null
+    createdAt: string
+    updatedAt: string
+    knowledgeBase: {
+      id: string
+      name: string
+    } | null
+  }
+}
+
+export type StatusesAnswer = {
+  documents: Array<{
+    id: string
+    orgId: string
+    knowledgeBaseId: string | null
+    title: string
+    fileName: string | null
+    mimeType: string | null
+    byteSize: number | null
+    status: 'scanning' | 'pending' | 'processing' | 'ready' | 'failed' | 'blocked'
+    searchable: boolean
+    error: string | null
+    errorKind: string | null
+    viewUrl: string | null
+    createdBy: string | null
+    addedByKey: {
+      name: string | null
+    } | null
+    source: {
+      id: string
+      name: string
+      url: string | null
+    } | null
+    createdAt: string
+    updatedAt: string
+  }>
+  missing: string[]
+}
+
+export type DocumentTextAnswer = {
+  id: string
+  title: string
+  knowledgeBase: {
+    id: string
+    name: string
+  }
+  pageCount: number | null
+  pages: Array<{
+    page: number | null
+    text: string
+  }>
+  nextPage: number | null
+  cut: boolean
+}
+
+export type SearchAnswer = {
+  results: Array<{
+    documentId: string
+    title: string
+    knowledgeBase: {
+      id: string
+      name: string
+    } | null
+    page: number | null
+    snippet: string
+    score: number
+    viewUrl: string
+    openUrl: string
+    fileName: string | null
+    mimeType: string | null
+    updatedAt: string
+    documentUpdatedAt: string | null
+    addedBy: string | null
+    addedByKey: {
+      name: string | null
+    } | null
+    text?: string
+    passageId?: string
+  }>
+  total: number
+  facets: {
+    knowledgeBases: Array<{
+      id: string
+      name: string
+      count: number
+    }>
+    types: Array<{
+      type: string
+      count: number
+    }>
+    addedBy: Array<{
+      userId: string
+      count: number
+    }>
+    updated: Array<{
+      range: string
+      count: number
+    }>
+  }
+  mode: 'hybrid' | 'text'
+  correctedQuery?: string
+  timing: {
+    totalMs: number
+    embedMs: number
+    engineMs: number
+    recheckMs: number
+    queryVectorCached: boolean
+  }
+}
+
+export type AgentBasesAnswer = {
+  bases: Array<{
+    id: string
+    name: string
+    layer: 'workspace' | 'organization'
+    files: number
+    picked: boolean
+    unavailable: 'not_shared' | 'other_workspace' | null
+  }>
+  canChange: boolean
+  customerFacing: {
+    setUpForCustomers: boolean
+    channels: string[]
+    publicChat: boolean
+    embeddedChat: boolean
+    apps: string[]
+    voice: boolean
+  } | null
+}
+
+/** A source as a file or an API call carries it, and as whoever manages its base reads it back. */
+export type SourceSpec = {
+  kind: 'api_pull'
+  name: string
+  schedule: 'manual' | 'hourly' | 'every_6_hours' | 'daily'
+  keepRemovedDays: 1 | 7 | 30
+  config: {
+    listUrl: string
+    itemsAt: string
+    paging: {
+      kind: 'link_header'
+    } | {
+      kind: 'next_url'
+      at: string
+    } | {
+      kind: 'page'
+      param: string
+      first: number
+    } | {
+      kind: 'cursor'
+      param: string
+      at: string
+    }
+    changes: {
+      kind: 'updated_since'
+      param: string
+      format: 'iso' | 'unix'
+    } | {
+      kind: 'newest_first'
+    } | {
+      kind: 'full'
+    }
+    fields: {
+      id: string
+      title: string
+      updatedAt: string
+      link?: string
+      content: {
+        kind: 'inline'
+        at: string
+        format: 'html' | 'markdown' | 'text'
+      } | {
+        kind: 'file'
+        at: string
+      }
+      deletedWhen?: {
+        at: string
+        equals: string | boolean
+      }
+    }
+    requestsPerSecond?: number
+  }
+  auth: {
+    kind: 'none'
+  } | {
+    kind: 'bearer'
+  } | {
+    kind: 'header'
+    name: string
+  } | {
+    kind: 'basic'
+    username: string
+  } | {
+    kind: 'oauth_client_credentials'
+    tokenUrl: string
+    clientId: string
+    scope?: string
+  }
+}
+
+/** What adding a source, or testing one, sends: its shape, with the schedule and retention optional, and the credential its sign-in needs. */
+export type SourceInput = {
+  kind: 'api_pull'
+  name: string
+  schedule?: 'manual' | 'hourly' | 'every_6_hours' | 'daily'
+  keepRemovedDays?: 1 | 7 | 30
+  config: {
+    listUrl: string
+    itemsAt: string
+    paging: {
+      kind: 'link_header'
+    } | {
+      kind: 'next_url'
+      at: string
+    } | {
+      kind: 'page'
+      param: string
+      first: number
+    } | {
+      kind: 'cursor'
+      param: string
+      at: string
+    }
+    changes: {
+      kind: 'updated_since'
+      param: string
+      format: 'iso' | 'unix'
+    } | {
+      kind: 'newest_first'
+    } | {
+      kind: 'full'
+    }
+    fields: {
+      id: string
+      title: string
+      updatedAt: string
+      link?: string
+      content: {
+        kind: 'inline'
+        at: string
+        format: 'html' | 'markdown' | 'text'
+      } | {
+        kind: 'file'
+        at: string
+      }
+      deletedWhen?: {
+        at: string
+        equals: string | boolean
+      }
+    }
+    requestsPerSecond?: number
+  }
+  auth: {
+    kind: 'none'
+  } | {
+    kind: 'bearer'
+  } | {
+    kind: 'header'
+    name: string
+  } | {
+    kind: 'basic'
+    username: string
+  } | {
+    kind: 'oauth_client_credentials'
+    tokenUrl: string
+    clientId: string
+    scope?: string
+  }
+  credential?: string
+}
+
+/** A change to a source: only the parts given change. */
+export type SourcePatch = {
+  name?: string
+  schedule?: 'manual' | 'hourly' | 'every_6_hours' | 'daily'
+  keepRemovedDays?: 1 | 7 | 30
+  config?: {
+    listUrl: string
+    itemsAt: string
+    paging: {
+      kind: 'link_header'
+    } | {
+      kind: 'next_url'
+      at: string
+    } | {
+      kind: 'page'
+      param: string
+      first: number
+    } | {
+      kind: 'cursor'
+      param: string
+      at: string
+    }
+    changes: {
+      kind: 'updated_since'
+      param: string
+      format: 'iso' | 'unix'
+    } | {
+      kind: 'newest_first'
+    } | {
+      kind: 'full'
+    }
+    fields: {
+      id: string
+      title: string
+      updatedAt: string
+      link?: string
+      content: {
+        kind: 'inline'
+        at: string
+        format: 'html' | 'markdown' | 'text'
+      } | {
+        kind: 'file'
+        at: string
+      }
+      deletedWhen?: {
+        at: string
+        equals: string | boolean
+      }
+    }
+    requestsPerSecond?: number
+  }
+  auth?: {
+    kind: 'none'
+  } | {
+    kind: 'bearer'
+  } | {
+    kind: 'header'
+    name: string
+  } | {
+    kind: 'basic'
+    username: string
+  } | {
+    kind: 'oauth_client_credentials'
+    tokenUrl: string
+    clientId: string
+    scope?: string
+  }
+  credential?: string
+}
+
+/** Where a source's list is, how to page and follow changes, and which field of an item holds what. */
+export type PullConfig = {
+  listUrl: string
+  itemsAt: string
+  paging: {
+    kind: 'link_header'
+  } | {
+    kind: 'next_url'
+    at: string
+  } | {
+    kind: 'page'
+    param: string
+    first: number
+  } | {
+    kind: 'cursor'
+    param: string
+    at: string
+  }
+  changes: {
+    kind: 'updated_since'
+    param: string
+    format: 'iso' | 'unix'
+  } | {
+    kind: 'newest_first'
+  } | {
+    kind: 'full'
+  }
+  fields: {
+    id: string
+    title: string
+    updatedAt: string
+    link?: string
+    content: {
+      kind: 'inline'
+      at: string
+      format: 'html' | 'markdown' | 'text'
+    } | {
+      kind: 'file'
+      at: string
+    }
+    deletedWhen?: {
+      at: string
+      equals: string | boolean
+    }
+  }
+  requestsPerSecond?: number
+}
+
+/** How the platform signs in to a source; the credential itself travels beside it and is never read back. */
+export type SourceAuth = {
+  kind: 'none'
+} | {
+  kind: 'bearer'
+} | {
+  kind: 'header'
+  name: string
+} | {
+  kind: 'basic'
+  username: string
+} | {
+  kind: 'oauth_client_credentials'
+  tokenUrl: string
+  clientId: string
+  scope?: string
+}