npm - @frontera-sdk/chat - Versions diffs - 1.50.40 - Mend

@frontera-sdk/chat 1.50.40

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/src/callback-page.ts ADDED Viewed

@@ -0,0 +1,133 @@
+/**
+ * The OAuth callback page, as a string of HTML.
+ *
+ * The callback has to live on YOUR domain — a provider only authorises
+ * redirect URIs under a domain its project owner has verified — so this is one
+ * page every integration must host, and the only page in the whole flow they
+ * cannot get from us pre-built. What it does is small and entirely mechanical:
+ * take `code` and `state` off its own URL and hand them back to the chat.
+ *
+ * So we ship the mechanism instead of the instructions. Any JS server can
+ * serve this — a Next route handler, Express, Hono, Fastify, Workers, Bun,
+ * Deno — and a backend in another language can serve the same markup as a
+ * static file (`bunx frontera-chat-callback > callback.html`, or copy it from
+ * the docs).
+ *
+ * No import runs on the page itself: the script is inlined, because a callback
+ * page that has to load a bundle is a callback page that can fail to load one
+ * while holding an authorization code.
+ */
+export interface ConnectCallbackPageOptions {
+  /**
+   * Origin allowed to receive the code in popup mode. Defaults to the page's
+   * own origin, correct when the chat and the callback are the same app.
+   *
+   * Never `'*'`. The message carries an authorization code, and any page that
+   * can guess your callback could otherwise listen for it.
+   */
+  targetOrigin?: string
+  /** Shown while the page does its work. Replace it to match your product. */
+  message?: string
+  /** Fallback when a redirect return has no stored address. Defaults to `/`. */
+  fallbackReturnTo?: string
+}
+const DEFAULT_MESSAGE = 'Finishing up…'
+/**
+ * `JSON.stringify` also escapes `<` when we ask, which is what keeps a value
+ * from closing the script element it sits inside.
+ */
+function jsLiteral(value: string): string {
+  return JSON.stringify(value).replace(/</g, '\\u003c')
+}
+export function renderConnectCallbackPage(options: ConnectCallbackPageOptions = {}): string {
+  const targetOrigin = options.targetOrigin ? jsLiteral(options.targetOrigin) : 'location.origin'
+  const fallback = jsLiteral(options.fallbackReturnTo ?? '/')
+  const message = (options.message ?? DEFAULT_MESSAGE).replace(/[<>&]/g, (c) =>
+    c === '<' ? '&lt;' : c === '>' ? '&gt;' : '&amp;',
+  )
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>Connecting…</title>
+<style>
+  body {
+    margin: 0; min-height: 100vh;
+    display: flex; align-items: center; justify-content: center;
+    font: 15px/1.5 system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    color: #16201f; background: #fbfbfa;
+  }
+  @media (prefers-color-scheme: dark) { body { color: #e6ecea; background: #0e1413; } }
+  p { opacity: .7; }
+</style>
+</head>
+<body>
+<p>${message}</p>
+<script>
+(function () {
+  var params = new URLSearchParams(location.search);
+  var payload = {
+    type: 'frontera:oauth-callback',
+    code: params.get('code') || undefined,
+    state: params.get('state') || undefined,
+    error: params.get('error') || undefined
+  };
+  // Popup: hand the result to the window that opened us, then get out of the
+  // way. The origin is pinned — this message carries an authorization code.
+  if (window.opener) {
+    try { window.opener.postMessage(payload, ${targetOrigin}); } catch (e) {}
+    window.close();
+    return;
+  }
+  // Redirected tab — the normal path on mobile, where popups are blocked. The
+  // chat parked its return address before leaving, because the redirect URI is
+  // registered with the provider and cannot carry one.
+  var returnTo = ${fallback};
+  try {
+    var pending = JSON.parse(sessionStorage.getItem('frontera:connect-pending') || 'null');
+    if (pending && pending.returnTo) returnTo = pending.returnTo;
+  } catch (e) {}
+  var target = new URL(returnTo, location.origin);
+  if (payload.code) target.searchParams.set('frontera_code', payload.code);
+  if (payload.state) target.searchParams.set('frontera_state', payload.state);
+  if (payload.error) target.searchParams.set('frontera_error', payload.error);
+  location.replace(target.toString());
+})();
+</script>
+</body>
+</html>`
+}
+/**
+ * A `Response` carrying the page, for any runtime with the Fetch API.
+ *
+ * ```ts
+ * // Next.js — app/oauth/callback/route.ts
+ * export const GET = () => connectCallbackResponse()
+ * ```
+ *
+ * `no-store` matters: this page is only ever loaded with a single-use code in
+ * the query string, and a cached copy is a stale code waiting to confuse
+ * someone.
+ */
+export function connectCallbackResponse(options: ConnectCallbackPageOptions = {}): Response {
+  return new Response(renderConnectCallbackPage(options), {
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'cache-control': 'no-store',
+      // The page is not meant to be embedded, and framing it would put an
+      // authorization code inside someone else's document.
+      'x-frame-options': 'DENY',
+    },
+  })
+}

package/src/chat-client.ts ADDED Viewed

@@ -0,0 +1,472 @@
+import type { FronteraClient } from '@frontera-sdk/core/client'
+import { FronteraError } from '@frontera-sdk/core/errors'
+import { chatDoctor } from './doctor'
+import { resumeStream, startChat, type ChatStreamOptions } from './stream'
+import type {
+  ArtifactVersionMeta,
+  ApprovalDecision,
+  ChatAgent,
+  ChatArtifact,
+  CompleteAppConnectionRequest,
+  CompleteAppConnectionResult,
+  PendingApproval,
+  ResumeToolCallResult,
+  StartAppConnectionRequest,
+  StartAppConnectionResult,
+  UploadedFile,
+  ChatClientOptions,
+  CreateSessionRequest,
+  ListSessionsQuery,
+  Paginated,
+  Session,
+  SessionMessage,
+  StartChatRequest,
+  StartChatResult,
+  UpdateSessionRequest,
+} from './types'
+/**
+ * Domain client for the chat surface, in the mould of `BlueprintClient`: one
+ * thin method per endpoint over a `FronteraClient`.
+ *
+ * `authorizeConversation` exists because under API-key auth the SERVER SKIPS
+ * conversation ownership checks — any conversation id under the key's agent is
+ * accepted. A backend serving several of its own users must therefore gate
+ * conversation access itself; wiring that gate in here means every access path
+ * goes through it. Methods throw `FronteraError` code `FORBIDDEN_LOCAL` when
+ * the callback denies. Under an end-user `cht_` token the server enforces
+ * isolation and the callback is unnecessary.
+ */
+export class ChatClient {
+  constructor(
+    private readonly client: FronteraClient,
+    private readonly options: ChatClientOptions = {},
+  ) {}
+  private async authorize(conversationId: string): Promise<void> {
+    const gate = this.options.authorizeConversation
+    if (!gate) return
+    if (!(await gate(conversationId))) {
+      throw new FronteraError(`access to conversation ${conversationId} denied locally`, {
+        code: 'FORBIDDEN_LOCAL',
+      })
+    }
+  }
+  // --- chat runs ---
+  /** Start (or continue) a run. See `stream.ts` for stream semantics. */
+  async startChat(request: StartChatRequest, options?: ChatStreamOptions): Promise<StartChatResult> {
+    if (request.conversationId) await this.authorize(request.conversationId)
+    return startChat(this.client, request, options)
+  }
+  /**
+   * Re-attach to a run's stream. Run ids are capabilities: they only leave the
+   * server through a response the caller was already authorized to receive, so
+   * there is no conversation gate here — treat them accordingly.
+   */
+  resumeStream(
+    runId: string,
+    options?: { startIndex?: number } & ChatStreamOptions,
+  ): Promise<Response> {
+    return resumeStream(this.client, runId, options)
+  }
+  cancelRun(runId: string): Promise<{ success: true }> {
+    return this.client.request(`/v1/chat/${encodeURIComponent(runId)}/cancel`, { method: 'POST' })
+  }
+  steerRun(runId: string, message: string): Promise<{ success: true }> {
+    return this.client.request(`/v1/chat/${encodeURIComponent(runId)}/steer`, {
+      method: 'POST',
+      body: { message },
+    })
+  }
+  // --- approvals ---
+  /**
+   * The tool calls this conversation has parked, waiting on a person.
+   *
+   * Poll or call this on mount: a run blocked on an approval stays blocked
+   * across a page reload, and the `tool-approval-request` chunk that announced
+   * it is not replayed by a fresh `useChat`. Without reading them back, the
+   * conversation looks like an agent that stopped for no reason.
+   *
+   * End-user (`cht_`) tokens only — see `respondToApproval`.
+   */
+  async listPendingApprovals(conversationId: string): Promise<PendingApproval[]> {
+    // Reading the list counts as handling it: a surface that knows what is
+    // parked is a surface that can render it, and warning at one that already
+    // asked would be noise.
+    chatDoctor.resolved('approval')
+    chatDoctor.resolved('connect')
+    await this.authorize(conversationId)
+    const envelope = await this.client.requestEnvelope<{ data: PendingApproval[] }>(
+      '/v1/chat/approvals',
+      { query: { conversationId } },
+    )
+    return envelope.data
+  }
+  /**
+   * Approve or deny a parked tool call, releasing (or refusing) the run.
+   *
+   * Requires an end-user `cht_` token: the decision is recorded against the
+   * person who made it, and an `sak_` key is one credential shared by every
+   * user of your product — there is nobody it could be deciding as, so the
+   * server answers 403 (`FORBIDDEN`). An integration that wants its agent to
+   * act unattended sets the agent's approval mode to `auto` instead.
+   *
+   * Deciding twice is not an error: the first decision wins and this reports
+   * the settled status. A lapsed request answers `expired`.
+   */
+  respondToApproval(
+    approvalId: string,
+    decision: ApprovalDecision,
+  ): Promise<{ id: string; status: string }> {
+    chatDoctor.resolved('approval')
+    return this.client.request(`/v1/chat/approvals/${encodeURIComponent(approvalId)}`, {
+      method: 'POST',
+      body: { decision },
+    })
+  }
+  // --- app connections ---
+  /**
+   * Begin connecting the end user's own account for a parked `needs_connect`
+   * call, and get the URL to send them to.
+   *
+   * Three things must line up before this answers, and all three are one-time
+   * setup rather than per-user work:
+   *   1. the workspace has ITS OWN OAuth client for the provider (the
+   *      deployment-managed one cannot serve this — your users are authorising
+   *      your application, and only its owner can register your callback);
+   *   2. `redirectUri` is registered with that client AND on the workspace's
+   *      embed allowlist;
+   *   3. the install allows external users, and this user's token carries the
+   *      `plugin-connect` capability you granted when you minted it.
+   *
+   * Open the returned `authUrl` in a popup. Your callback receives `code` and
+   * `state` — hand them to `completeAppConnection`, then `resumeToolCall`.
+   */
+  startAppConnection(request: StartAppConnectionRequest): Promise<StartAppConnectionResult> {
+    chatDoctor.resolved('connect')
+    return this.client.request('/v1/chat/app-connections/start', {
+      method: 'POST',
+      body: request,
+    })
+  }
+  /**
+   * Finish a connect from the code your own callback received.
+   *
+   * `state` is signed by us and names the install, the user and the redirect
+   * URI, so none of the three can be swapped between the authorize request and
+   * this call. Pass it back exactly as it arrived.
+   */
+  completeAppConnection(
+    request: CompleteAppConnectionRequest,
+  ): Promise<CompleteAppConnectionResult> {
+    return this.client.request('/v1/chat/app-connections/exchange', {
+      method: 'POST',
+      body: request,
+    })
+  }
+  /**
+   * Re-run the tool call that was waiting on the connection.
+   *
+   * Not optional: the agent is blocked on a tool RESULT, not on an account, so
+   * a connect without this leaves the conversation exactly as stuck as before.
+   */
+  resumeToolCall(pendingToolCallId: string): Promise<ResumeToolCallResult> {
+    return this.client.request('/v1/chat/app-connections/resume', {
+      method: 'POST',
+      body: { pendingToolCallId },
+    })
+  }
+  /**
+   * The agents this credential may talk to — what an agent picker renders.
+   *
+   * Scoped to the credential, so a token bound to one agent lists exactly that
+   * agent while a workspace-wide token lists them all. The Console listing is
+   * session-only and returns configuration an end user has no business seeing,
+   * which is why this exists separately.
+   */
+  listAgents(): Promise<ChatAgent[]> {
+    return this.client.request('/v1/chat-agents')
+  }
+  /**
+   * Upload a file for this user, then reference the result in
+   * `startChat({ fileAttachments: [uploaded] })`.
+   *
+   * A chat-scoped route, not the platform's `/v1/upload`: that one authorises
+   * through workspace membership, which an end user of a customer's product
+   * does not have and should not need.
+   */
+  async upload(file: File | Blob, filename?: string): Promise<UploadedFile> {
+    const form = new FormData()
+    form.append('file', file, filename ?? (file as File).name ?? 'upload')
+    // Not through `request`: that serialises JSON and would set the wrong
+    // content type. The boundary must be chosen by FormData itself.
+    const response = await this.client.requestRaw('/v1/chat-uploads', {
+      method: 'POST',
+      body: form as unknown as undefined,
+    })
+    const payload = (await response.json()) as { data?: UploadedFile } & UploadedFile
+    return payload.data ?? payload
+  }
+  /**
+   * A live URL for a stored upload.
+   *
+   * The URL saved on a message is presigned and expires about an hour after
+   * upload, so anything rendered later re-signs from the stored path — without
+   * this, attachments in yesterday's messages become broken images.
+   */
+  async signUpload(storagePath: string): Promise<string> {
+    const { url } = await this.client.request<{ url: string }>('/v1/chat-uploads/sign', {
+      method: 'POST',
+      body: { path: storagePath },
+    })
+    return url
+  }
+  /** The artifacts this user owns — documents, decks and images the agent made. */
+  async listArtifacts(query: { search?: string; limit?: number; cursor?: string } = {}): Promise<
+    Paginated<ChatArtifact>
+  > {
+    const envelope = await this.client.requestEnvelope<{
+      data: ChatArtifact[]
+      nextCursor?: string | null
+    }>('/v1/chat-artifacts', { query })
+    return { data: envelope.data, nextCursor: envelope.nextCursor ?? undefined }
+  }
+  getArtifact(id: string): Promise<ChatArtifact> {
+    return this.client.request(`/v1/chat-artifacts/${encodeURIComponent(id)}`)
+  }
+  /**
+   * The artifact's contents as TEXT.
+   *
+   * Only for artifacts that are text — markdown, csv, code. Reading a PNG or a
+   * spreadsheet through here destroys it: `.text()` decodes the bytes as UTF-8,
+   * and every byte that is not valid UTF-8 becomes a replacement character on
+   * the way. Use `getArtifactFile` for anything binary.
+   */
+  async getArtifactContent(id: string): Promise<string> {
+    const response = await this.client.requestRaw(
+      `/v1/chat-artifacts/${encodeURIComponent(id)}/file`,
+    )
+    return response.text()
+  }
+  /**
+   * The artifact's raw bytes, with the server's own content type.
+   *
+   * The Blob carries the type the route reported rather than one guessed from
+   * the format, so an <img> or a PDF reader gets what it needs without the
+   * caller restating it — and a wrong guess here is an image that silently
+   * will not display.
+   */
+  async getArtifactFile(id: string): Promise<Blob> {
+    const response = await this.client.requestRaw(
+      `/v1/chat-artifacts/${encodeURIComponent(id)}/file`,
+    )
+    return response.blob()
+  }
+  /**
+   * A PDF rendering of an artifact a browser cannot open itself.
+   *
+   * `.docx` and `.pptx` are bytes with no source to fall back on, so the
+   * service renders a PDF beside them and this returns it — displaying one
+   * without shipping an OOXML reader.
+   *
+   * Only artifacts with `previewKey` set have one; anything else answers 404
+   * as `NOT_FOUND`. Check the field before asking, or catch it.
+   */
+  /**
+   * Save an edit made in the viewer — a sheet cell, a document's text.
+   *
+   * Produces a new REVISION rather than overwriting: the service re-renders to
+   * a versioned storage key and bumps the version, so the artifact keeps the
+   * history an edit implies.
+   */
+  async updateArtifact(
+    id: string,
+    patch: { content: string; title?: string },
+  ): Promise<ChatArtifact> {
+    return this.client.request<ChatArtifact>(
+      `/v1/chat-artifacts/${encodeURIComponent(id)}`,
+      { method: 'PATCH', body: patch },
+    )
+  }
+  /** One revision's content — what the inline "viewing v1" panel shows. */
+  async getArtifactVersion(id: string, version: number): Promise<ChatArtifact> {
+    return this.client.request<ChatArtifact>(
+      `/v1/chat-artifacts/${encodeURIComponent(id)}/versions/${encodeURIComponent(String(version))}`,
+    )
+  }
+  /**
+   * Roll back to a revision.
+   *
+   * Writes a new revision holding the old content — nothing is deleted, so a
+   * restore made in error is itself undoable.
+   */
+  async restoreArtifactVersion(id: string, version: number): Promise<ChatArtifact> {
+    return this.client.request<ChatArtifact>(
+      `/v1/chat-artifacts/${encodeURIComponent(id)}/versions/${encodeURIComponent(String(version))}/restore`,
+      { method: 'POST' },
+    )
+  }
+  /** Revisions of one artifact, newest first. Metadata only. */
+  async listArtifactVersions(id: string): Promise<ArtifactVersionMeta[]> {
+    return this.client.request<ArtifactVersionMeta[]>(
+      `/v1/chat-artifacts/${encodeURIComponent(id)}/versions`,
+    )
+  }
+  /**
+   * The rendition of a PAST version, for the viewer's version picker.
+   *
+   * Separate from `getArtifactPreview` rather than an optional argument: the
+   * current preview lives at a different path, and a version of `0` or `NaN`
+   * silently falling back to "current" is how a reader ends up looking at
+   * today's document under yesterday's heading.
+   */
+  async getArtifactVersionPreview(id: string, version: number): Promise<Blob> {
+    const response = await this.client.requestRaw(
+      `/v1/chat-artifacts/${encodeURIComponent(id)}/versions/${encodeURIComponent(String(version))}/preview`,
+    )
+    return response.blob()
+  }
+  async getArtifactPreview(id: string): Promise<Blob> {
+    const response = await this.client.requestRaw(
+      `/v1/chat-artifacts/${encodeURIComponent(id)}/preview`,
+    )
+    return response.blob()
+  }
+  // --- sessions ---
+  async listSessions(query: ListSessionsQuery = {}): Promise<Paginated<Session>> {
+    // Envelope-preserving request: `nextCursor` sits BESIDE `data` in the
+    // response envelope and the default unwrap would drop it.
+    const envelope = await this.client.requestEnvelope<{
+      data: Session[]
+      nextCursor?: string | null
+    }>('/v1/sessions', {
+      query: {
+        cursor: query.cursor,
+        limit: query.limit,
+        status: query.status,
+        label: query.label,
+        group: query.group,
+        search: query.search,
+        pinned: query.pinned,
+        source: query.source,
+        agentName: query.agentName,
+        agentId: query.agentId,
+        updatedAfter: query.updatedAfter,
+        updatedBefore: query.updatedBefore,
+        surface: query.surface,
+      },
+    })
+    return { data: envelope.data, nextCursor: envelope.nextCursor ?? undefined }
+  }
+  createSession(request: CreateSessionRequest = {}): Promise<Session> {
+    return this.client.request('/v1/sessions', { method: 'POST', body: request })
+  }
+  async getSession(id: string): Promise<Session> {
+    await this.authorize(id)
+    return this.client.request(`/v1/sessions/${encodeURIComponent(id)}`)
+  }
+  async getMessages(id: string, options: { limit?: number } = {}): Promise<SessionMessage[]> {
+    await this.authorize(id)
+    return this.client.request(`/v1/sessions/${encodeURIComponent(id)}/messages`, {
+      query: { limit: options.limit },
+    })
+  }
+  // The four below act on ONE person's own session, so they need a credential
+  // that names one: a `cht_` end-user token works, an `sak_` key answers 403
+  // (`FORBIDDEN`) because it stands for every user of your product at once.
+  //
+  // `getShare`/`createShare` are deliberately absent: a share link works with
+  // no credential at all, and whether your end users may publish a
+  // conversation is your product's decision to implement, not a default they
+  // inherit from us. Those routes are platform-only and answer 403.
+  /**
+   * Rename, pin, or restatus a conversation.
+   *
+   * Answers `{ success: true }` rather than the updated row — the service
+   * confirms the write and nothing more. Typed as what actually arrives: a
+   * `Session` here would be a promise the server never made, and the first
+   * caller to read `.title` off it would get `undefined` with no explanation.
+   * Re-read with `getSession` when you need the new state.
+   */
+  async updateSession(id: string, patch: UpdateSessionRequest): Promise<{ success: boolean }> {
+    await this.authorize(id)
+    return this.client.request(`/v1/sessions/${encodeURIComponent(id)}`, {
+      method: 'PATCH',
+      body: patch,
+    })
+  }
+  async deleteSession(id: string): Promise<void> {
+    await this.authorize(id)
+    await this.client.request(`/v1/sessions/${encodeURIComponent(id)}`, { method: 'DELETE' })
+  }
+  async forkSession(id: string, messageId: string): Promise<Session> {
+    await this.authorize(id)
+    return this.client.request(`/v1/sessions/${encodeURIComponent(id)}/fork`, {
+      method: 'POST',
+      body: { messageId },
+    })
+  }
+  /** Returns the export as a raw string — this route has no JSON envelope. */
+  async exportSession(id: string, format: string): Promise<string> {
+    await this.authorize(id)
+    const response = await this.client.requestRaw(
+      `/v1/sessions/${encodeURIComponent(id)}/export`,
+      { query: { format } },
+    )
+    return response.text()
+  }
+  // --- aux ---
+  async getFollowUps(
+    conversationId: string,
+    messageId: string,
+  ): Promise<{ suggestions: unknown[] }> {
+    await this.authorize(conversationId)
+    return this.client.request('/v1/follow-ups', { query: { conversationId, messageId } })
+  }
+  async getMessageMetadata(
+    conversationId: string,
+    messageId: string,
+  ): Promise<{ metadata: unknown }> {
+    await this.authorize(conversationId)
+    return this.client.request('/v1/message-metadata', { query: { conversationId, messageId } })
+  }
+}