@frontera-sdk/chat 1.50.40

package/src/types.ts

@@ -0,0 +1,370 @@
+/**
+ * Request/response shapes for the chat surface, mirrored from the service's
+ * TypeBox schemas (chat-router.ts, session-router.ts). Mirrored by hand rather
+ * than imported: the SDK publishes source and must not depend on the service
+ * package.
+ */
+
+export type ChatRole = 'user' | 'assistant' | 'system'
+
+/**
+ * A message as `POST /v1/chat` accepts it. `parts` is deliberately untyped:
+ * the server persists parts opaquely (a narrow schema on the wire stripped
+ * part fields once — see the comment in chat-router.ts), and the SDK follows.
+ */
+export interface ChatInputMessage {
+  id: string
+  role: ChatRole
+  content?: string
+  parts: unknown[]
+}
+
+export interface ContextAttachment {
+  type: string
+  id: string
+  name?: string
+  meta?: Record<string, unknown>
+}
+
+export interface FileAttachment {
+  /** Publicly reachable URL — under API-key auth there is no upload endpoint. */
+  url: string
+  storagePath?: string
+  filename: string
+  mediaType: string
+  size: number
+  pageCount?: number
+  isScanned?: boolean
+}
+
+export type ReasoningEffort = 'max' | 'xhigh' | 'high' | 'medium' | 'low' | 'minimal' | 'none'
+
+export interface StartChatRequest {
+  /** 1–5 messages; the server rehydrates earlier history from the conversation. */
+  messages: ChatInputMessage[]
+  conversationId?: string
+  editMessageId?: string
+  contextAttachments?: ContextAttachment[]
+  fileAttachments?: FileAttachment[]
+  analysisMode?: string
+  webSearchAugment?: boolean
+  modelMode?: string | null
+  thinkingEnabled?: boolean
+  reasoningEffort?: ReasoningEffort
+  /** Ignored under sak_/cht_ auth — the credential's agent always wins. */
+  agentName?: string
+  surface?: 'web' | 'mobile' | 'console'
+}
+
+/** What `startChat` extracts from the response before handing over the stream. */
+export interface StartChatResult {
+  conversationId: string
+  runId: string
+  runtime: string
+  quotaWarning?: string
+  /** The raw response; `response.body` is the AI SDK v6 UI-message SSE stream. */
+  response: Response
+}
+
+// --- auth ---
+
+export interface ExchangeTokenRequest {
+  externalUserId: string
+  name?: string
+  metadata?: Record<string, unknown>
+  ttlSeconds?: number
+  /**
+   * Which agent the token reaches. Accepted when minting with a workspace key
+   * scoped for chat; an agent key is fixed to its own agent and refuses a
+   * different one. Omit with a workspace key for a token that reaches every
+   * agent, the way a platform user does.
+   */
+  agentId?: string
+  agentName?: string
+  /**
+   * Limit this token to a SUBSET of the workspace's agents — ids or slugs.
+   *
+   * Omit and it reaches every agent the minting credential can (an agent key
+   * always fixes exactly one). Naming a subset is how a product that exposes
+   * two of five agents stops the other three from being reachable by a guessed
+   * id, not merely hidden from the picker.
+   */
+  agentIds?: string[]
+  /**
+   * What YOUR product authorises this person to do beyond chatting. Everything
+   * here is DENIED unless asked for:
+   *
+   * - `plugin-connect` — connect their own account (Gmail, Drive, …) for a plugin
+   *   that needs one. All-or-nothing across the plugins the workspace has
+   *   opened to external users; a per-plugin scope is planned (see the TODO in
+   *   the service's `chat-token.ts`).
+   * - `schedule` — read and manage the agent's scheduled tasks.
+   * - `agent-mode` — agent work items, exchanges, handoffs, agent conversations.
+   *
+   * The base token chats and nothing more: it sends, reads its own history and
+   * answers what the agent parks. Decide the rest against your own roles — we
+   * never model them. The decision rides on the token and expires with it, so
+   * withdrawing it on your side takes effect with nothing to synchronise.
+   */
+  capabilities?: string[]
+}
+
+export interface ChatToken {
+  token: string
+  expiresAt: string
+}
+
+/** What an upload returns — the shape `fileAttachments` expects. */
+export interface UploadedFile {
+  url: string
+  storagePath?: string
+  filename: string
+  mediaType: string
+  size: number
+  pageCount?: number
+  isScanned?: boolean
+}
+
+/**
+ * A document, image or deck the agent produced.
+ *
+ * The named fields are the ones a viewer reads; the index signature carries
+ * whatever else the deployment returns. Naming them matters — under an index
+ * signature alone every read is `unknown`, and a renderer cannot tell a title
+ * from a MIME type.
+ */
+/**
+ * One revision of an artifact, as the version picker needs it.
+ *
+ * Metadata only — no `content`, no `storageKey`. Drawing a menu does not
+ * require every revision's bytes, and the preview route serves them when a
+ * revision is actually opened.
+ */
+export interface ArtifactVersionMeta {
+  version: number
+  createdAt?: string
+  title?: string | null
+  /** Who saved it — an agent turn, or the person editing in the viewer. */
+  createdBy?: string | null
+  sizeBytes?: number | null
+}
+
+export interface ChatArtifact {
+  id: string
+  title?: string | null
+  kind?: string | null
+  /** Rendered format: markdown, csv, sheet, pdf, image, htmldeck, canvas. */
+  format?: string | null
+  mimeType?: string | null
+  /** The artifact's text, when it has one. */
+  content?: string | null
+  /** Source language for a code artifact, used to pick a subtitle and lexer. */
+  language?: string | null
+  conversationId?: string | null
+  /** Where the bytes live, for artifacts stored as files rather than text. */
+  storageKey?: string | null
+  /**
+   * A rendered PDF of this artifact, when the format needs one to be shown.
+   *
+   * Set for `.docx`/`.pptx` and anything else a browser cannot open. Present
+   * means `getArtifactPreview(id)` will answer; absent means it will not.
+   */
+  previewKey?: string | null
+  createdAt?: string
+  updatedAt?: string
+  [key: string]: unknown
+}
+
+/** An agent the current credential may talk to — enough to draw a picker. */
+export interface ChatAgent {
+  id: string
+  agentId: string
+  name: string
+  description?: string | null
+  avatarConfig?: unknown
+}
+
+// --- approvals ---
+
+/**
+ * A tool call the agent has parked, waiting for a person to decide.
+ *
+ * The run is BLOCKED while this exists: an agent whose approval mode is `ask`
+ * (or whose tool the safety reviewer would not clear on its own) streams a
+ * `tool-approval-request` chunk carrying `approvalId` and then stops until
+ * `respondToApproval` settles it or `expiresAt` passes. An integration that
+ * never answers looks like an agent that silently stopped mid-sentence.
+ *
+ * Named fields are what a card needs to render; the index signature carries
+ * whatever else the deployment reports.
+ */
+export interface PendingApproval {
+  id: string
+  /** `pending` while it waits; then `approved`, `denied` or `expired`. */
+  status: string
+  /** `needs_approval` for a human gate; `needs_connect` for a missing account. */
+  pauseReason: string
+  /** Which app the agent was reaching for — pass it to `startAppConnection`. */
+  installId?: string | null
+  toolCallId?: string | null
+  toolName?: string | null
+  /** Where the tool came from: an app, an MCP server, the platform. */
+  toolSource?: string | null
+  risk?: string | null
+  /** A short, secret-safe description of what the tool is about to do. */
+  actionSummary?: unknown
+  /** Why the policy asked rather than allowing. */
+  policyReason?: string | null
+  expiresAt?: string
+  [key: string]: unknown
+}
+
+export type ApprovalDecision = 'approve' | 'deny'
+
+// --- app connections ---
+
+/**
+ * Starting a connect for a tool that needs the END USER's own account.
+ *
+ * `redirectUri` is a callback on YOUR domain, registered both with your OAuth
+ * client and on the workspace's embed allowlist. It has to be yours: a
+ * provider only authorises redirect URIs under a domain the OAuth project's
+ * owner has verified, and you cannot verify ours.
+ */
+export interface StartAppConnectionRequest {
+  /** From the parked call's `installId`; or name the app with `catalogKind`. */
+  installId?: string
+  catalogKind?: string
+  redirectUri: string
+  /** Where your page sends the user afterwards — origin must be allowlisted. */
+  returnTo?: string
+}
+
+export interface StartAppConnectionResult {
+  /** Open this in a popup or a full-page redirect. */
+  authUrl: string
+  installId: string
+}
+
+/** What your callback forwards to us: the provider's `code` and our `state`. */
+export interface CompleteAppConnectionRequest {
+  code: string
+  state: string
+}
+
+export interface CompleteAppConnectionResult {
+  installId: string
+  /** The account's email, when the provider reports one. */
+  email: string | null
+}
+
+/**
+ * The re-run of a parked call. `ok: false` with `reason: 'no_account'` means
+ * the connection still is not usable — the row stays parked, so the same card
+ * can retry.
+ */
+export type ResumeToolCallResult =
+  | { ok: true; [key: string]: unknown }
+  | { ok: false; reason: string; error?: string }
+
+/**
+ * The chunk that announces a parked tool call, as it arrives on the stream.
+ *
+ * Not exported by the AI SDK's own chunk union, so it is declared here for
+ * consumers switching on chunk types from `chatChunkStream`.
+ */
+export interface ToolApprovalRequestChunk {
+  type: 'tool-approval-request'
+  approvalId: string
+  toolCallId: string
+}
+
+// --- sessions ---
+
+export interface CreateSessionRequest {
+  agentName?: string
+  modelMode?: string | null
+  approvalMode?: 'ask' | 'auto' | 'full'
+  workspaceId?: string
+}
+
+export interface UpdateSessionRequest {
+  title?: string
+  status?: string
+  pinned?: boolean
+  group?: string | null
+  modelMode?: string | null
+  approvalMode?: 'ask' | 'auto' | 'full'
+}
+
+export interface ListSessionsQuery {
+  cursor?: string
+  limit?: number
+  status?: string
+  label?: string
+  group?: string
+  search?: string
+  pinned?: boolean
+  source?: 'chat' | 'automation' | 'all'
+  agentName?: string
+  agentId?: string
+  updatedAfter?: string
+  updatedBefore?: string
+  surface?: string
+}
+
+export interface Paginated<T> {
+  data: T[]
+  nextCursor?: string
+}
+
+/**
+ * Loose by design: these are the fields the server guarantees today; anything
+ * else rides in the index signature until the service exposes a shared
+ * contract.
+ */
+export interface Session {
+  id: string
+  title?: string | null
+  status?: string
+  agentName?: string | null
+  pinned?: boolean
+  createdAt?: string
+  updatedAt?: string
+  [key: string]: unknown
+}
+
+/** UIMessage-shaped: feed straight into `useChat({ messages })`. */
+export interface SessionMessage {
+  id: string
+  role: ChatRole
+  parts: unknown[]
+  metadata?: Record<string, unknown>
+  createdAt: string
+}
+
+/**
+ * Custom data parts the server streams alongside text. Payloads are `unknown`
+ * in v1; the names are stable and safe to switch on in `onData`.
+ */
+export type ChatDataPartName =
+  | 'data-context'
+  | 'data-context-estimate'
+  | 'data-context-observed'
+  | 'data-context-maintenance'
+  | 'data-compaction'
+  | 'data-work-queued'
+  | 'data-desktop'
+
+/**
+ * Called before any method that touches an existing conversation. Under
+ * API-key auth the server skips conversation ownership checks entirely, so a
+ * consumer serving multiple end-users MUST decide here whether the current
+ * user may touch `conversationId` — typically a lookup in their own
+ * user↔conversation store.
+ */
+export type AuthorizeConversation = (conversationId: string) => boolean | Promise<boolean>
+
+export interface ChatClientOptions {
+  authorizeConversation?: AuthorizeConversation
+}

package/src/ui-stream.ts

@@ -0,0 +1,49 @@
+import {
+  parseJsonEventStream,
+  readUIMessageStream,
+  type UIMessage,
+  type UIMessageChunk,
+} from 'ai'
+
+/**
+ * Decode a chat SSE `Response` into the AI SDK's typed chunk stream.
+ *
+ * `readUIMessageStream` consumes chunks, not responses, so this is the bridge
+ * for server-side consumers holding the raw `Response` from `startChat`/
+ * `resumeStream`. The SSE layer (including the server's `: ping` keepalive
+ * comments and the `[DONE]` terminator) is handled by the AI SDK's own parser
+ * — the SDK never hand-parses SSE.
+ */
+export function chatChunkStream(response: Response): ReadableStream<UIMessageChunk> {
+  if (!response.body) {
+    throw new Error('chat response has no body to stream')
+  }
+  // No schema: chunk validation happens in readUIMessageStream's own state
+  // machine, and the service can add new data-part chunk types without the SDK
+  // rejecting them at the parse layer.
+  return parseJsonEventStream({
+    stream: response.body,
+    schema: undefined,
+  } as unknown as Parameters<typeof parseJsonEventStream>[0]).pipeThrough(
+    new TransformStream({
+      transform(result, controller) {
+        if (!result.success) throw result.error
+        controller.enqueue(result.value as UIMessageChunk)
+      },
+    }),
+  )
+}
+
+/**
+ * Iterate assembled `UIMessage` snapshots from a chat response:
+ *
+ * ```ts
+ * const run = await chat.startChat({ messages: [...] })
+ * for await (const message of readChatStream(run.response)) {
+ *   // message.parts grows as the agent streams
+ * }
+ * ```
+ */
+export function readChatStream(response: Response): AsyncIterable<UIMessage> {
+  return readUIMessageStream({ stream: chatChunkStream(response) })
+}