@frontera-sdk/chat 1.50.40

package/src/connect-popup.ts

@@ -0,0 +1,352 @@
+/**
+ * The browser half of connecting an end user's own account.
+ *
+ * The server side of this flow is three calls (`startAppConnection`,
+ * `completeAppConnection`, `resumeToolCall`) with a consent screen in the
+ * middle. What is fiddly is not the calls — it is the middle: opening a popup,
+ * knowing when it came back, telling "the user finished" apart from "the user
+ * closed the window", and not leaving a listener attached forever when neither
+ * happens.
+ *
+ * That is what lives here. It is deliberately not part of `ChatClient`: the
+ * client is transport, and this touches `window`.
+ */
+
+import type { ChatClient } from './chat-client'
+import type { ResumeToolCallResult } from './types'
+
+/** What a callback page sends back to the window that opened it. */
+export const CONNECT_MESSAGE_TYPE = 'frontera:oauth-callback'
+
+export interface ConnectCallbackMessage {
+  type: typeof CONNECT_MESSAGE_TYPE
+  code?: string
+  state?: string
+  /** The provider's own refusal — the user pressed Cancel, typically. */
+  error?: string
+}
+
+/** Where a redirect-mode connect parked what it needs to finish. */
+const PENDING_KEY = 'frontera:connect-pending'
+/** Query parameters the callback adds when returning a whole tab. */
+const RETURN_CODE = 'frontera_code'
+const RETURN_STATE = 'frontera_state'
+const RETURN_ERROR = 'frontera_error'
+
+/**
+ * Call this FROM YOUR CALLBACK PAGE — the one you registered as the OAuth
+ * redirect URI. It is the page's entire implementation:
+ *
+ * ```ts
+ * // app/frontera/oauth/callback/page.tsx
+ * import { postConnectResultToOpener } from '@frontera-sdk/chat/connect-popup'
+ * postConnectResultToOpener(window.location.search)
+ * ```
+ *
+ * It handles both ways a connect can arrive back. In a popup it posts to the
+ * opener and closes. In a redirected tab — which is what mobile gets, because
+ * popups are blocked or mangled in iOS Safari and in-app browsers — there is no
+ * opener, so it navigates back to where the chat was with the result attached.
+ *
+ * `targetOrigin` defaults to this page's own origin, correct when the chat and
+ * the callback are the same app. Never `'*'`: the message carries an
+ * authorization code.
+ */
+export function postConnectResultToOpener(search: string, targetOrigin?: string): void {
+  const params = new URLSearchParams(search)
+  const code = params.get('code') ?? undefined
+  const state = params.get('state') ?? undefined
+  const error = params.get('error') ?? undefined
+
+  if (window.opener) {
+    const message: ConnectCallbackMessage = { type: CONNECT_MESSAGE_TYPE, code, state, error }
+    window.opener.postMessage(message, targetOrigin ?? window.location.origin)
+    window.close()
+    return
+  }
+
+  // Redirect mode: the chat is not open behind us — it was this tab. The
+  // return address was stored before we left, because the redirect URI is
+  // fixed at the provider and cannot carry it.
+  const pending = readPending()
+  const target = new URL(pending?.returnTo ?? window.location.origin)
+  if (code) target.searchParams.set(RETURN_CODE, code)
+  if (state) target.searchParams.set(RETURN_STATE, state)
+  if (error) target.searchParams.set(RETURN_ERROR, error)
+  window.location.replace(target.toString())
+}
+
+interface PendingConnect {
+  /** Null for a voluntary connect — see `RunAppConnectionOptions`. */
+  pendingToolCallId: string | null
+  returnTo: string
+}
+
+function readPending(): PendingConnect | null {
+  try {
+    const raw = window.sessionStorage.getItem(PENDING_KEY)
+    return raw ? (JSON.parse(raw) as PendingConnect) : null
+  } catch {
+    // Private mode, a blocked storage partition, a corrupt value — none of
+    // which should throw out of a callback page whose only job is to forward.
+    return null
+  }
+}
+
+function writePending(value: PendingConnect | null): void {
+  try {
+    if (value) window.sessionStorage.setItem(PENDING_KEY, JSON.stringify(value))
+    else window.sessionStorage.removeItem(PENDING_KEY)
+  } catch {
+    /* see readPending */
+  }
+}
+
+export interface RunAppConnectionOptions {
+  /**
+   * The parked call's id — what gets resumed once the account exists.
+   *
+   * Omit for a VOLUNTARY connect: someone connecting an account from the
+   * composer before asking anything has no parked call, and there is nothing
+   * to resume. The account still lands the same way; only the last step
+   * differs.
+   */
+  pendingToolCallId?: string
+  /** Which app. Take `installId` from the parked call. */
+  installId?: string
+  catalogKind?: string
+  /** Your callback page, registered with your OAuth client AND allowlisted. */
+  redirectUri: string
+  /**
+   * Origin the callback message must come from. Defaults to `redirectUri`'s
+   * origin, which is where your callback page runs.
+   */
+  expectedOrigin?: string
+  /** How long to wait for the user before giving up. Default 5 minutes. */
+  timeoutMs?: number
+  /** Popup geometry, if the defaults do not suit your layout. */
+  features?: string
+  /**
+   * How to send the person to the provider.
+   *
+   * `auto` (default) tries a popup and falls back to redirecting this tab when
+   * the browser refuses one — which is the normal case on mobile: iOS Safari
+   * and in-app browsers (Instagram, LinkedIn, Slack) block or mangle
+   * `window.open`. A popup-only integration has a dead Connect button for
+   * every one of those users.
+   *
+   * `redirect` always navigates. `popup` never does, and reports the block.
+   */
+  mode?: 'auto' | 'popup' | 'redirect'
+  /**
+   * Where to come back to after a redirect. Defaults to the current URL, so
+   * the person lands where they left. Its ORIGIN must be on the workspace's
+   * embed allowlist.
+   */
+  returnTo?: string
+}
+
+export type RunAppConnectionResult =
+  /**
+   * The popup path completed here.
+   *
+   * `resume` is absent when nothing was parked — the plugins button connects
+   * an account with no tool call waiting on it, and the connect was the whole
+   * errand. Present only when a parked call was released by this connection.
+   */
+  | { status: 'connected'; resume?: ResumeToolCallResult }
+  | { status: 'cancelled'; reason: 'closed' | 'denied' | 'timeout'; error?: string }
+  /**
+   * The tab is navigating to the provider. Nothing after this call runs — the
+   * flow continues in `completeRedirectedConnection` when the person comes
+   * back.
+   */
+  | { status: 'redirecting' }
+
+const DEFAULT_TIMEOUT_MS = 5 * 60_000
+const DEFAULT_FEATURES = 'width=520,height=680,menubar=no,toolbar=no'
+
+/**
+ * Run the whole thing: open the consent popup, wait for your callback to post
+ * the code back, exchange it, and re-run the parked tool call.
+ *
+ * Resolves rather than throwing when the person simply declines — a closed
+ * popup is an ordinary outcome and reads badly as an exception. Genuine
+ * failures (a refused start, a rejected exchange) still throw `FronteraError`
+ * with the server's code.
+ *
+ * The resume is included on purpose. Connecting without it leaves the agent
+ * exactly as blocked as before: it is waiting on a tool RESULT, not on an
+ * account.
+ */
+export async function runAppConnection(
+  chat: ChatClient,
+  options: RunAppConnectionOptions,
+): Promise<RunAppConnectionResult> {
+  const mode = options.mode ?? 'auto'
+  const returnTo = options.returnTo ?? window.location.href
+
+  const { authUrl } = await chat.startAppConnection({
+    installId: options.installId,
+    catalogKind: options.catalogKind,
+    redirectUri: options.redirectUri,
+    returnTo,
+  })
+
+  const expectedOrigin = options.expectedOrigin ?? new URL(options.redirectUri).origin
+
+  const goByRedirect = (): RunAppConnectionResult => {
+    // Parked before navigating, because this tab is about to be replaced: the
+    // callback page reads it to find the way back, and the chat reads it on
+    // return to know which call to resume. The provider's redirect URI is
+    // fixed and cannot carry either.
+    writePending({ pendingToolCallId: options.pendingToolCallId ?? null, returnTo })
+    window.location.assign(authUrl)
+    return { status: 'redirecting' }
+  }
+
+  if (mode === 'redirect') return goByRedirect()
+
+  // Popup blockers judge by user gesture, and the awaited start call above may
+  // already have cost us that association. That is not a failure to report on
+  // mobile — it is the norm — so `auto` simply takes the other road.
+  const popup = window.open(authUrl, 'frontera-connect', options.features ?? DEFAULT_FEATURES)
+  if (!popup) {
+    if (mode === 'auto') return goByRedirect()
+    throw new Error(
+      'The connection window was blocked. Open it from a direct click, or allow popups for this site.',
+    )
+  }
+
+  const outcome = await waitForCallback(popup, expectedOrigin, options.timeoutMs ?? DEFAULT_TIMEOUT_MS)
+  if (outcome.status !== 'received') return { status: 'cancelled', reason: outcome.reason, error: outcome.error }
+
+  await chat.completeAppConnection({ code: outcome.code, state: outcome.state })
+  // Nothing parked, nothing to resume — the connect WAS the whole errand.
+  if (!options.pendingToolCallId) return { status: 'connected' }
+  const resume = await chat.resumeToolCall(options.pendingToolCallId)
+  return { status: 'connected', resume }
+}
+
+/**
+ * Finish a connect that came back as a page load rather than a popup message.
+ *
+ * Call it once when your chat mounts. It does nothing — cheaply, synchronously
+ * — unless this page load is a return from a provider, so it is safe to call
+ * unconditionally:
+ *
+ * ```ts
+ * useEffect(() => { void completeRedirectedConnection(chat) }, [chat])
+ * ```
+ *
+ * Without it the redirect path stops one step short: the account gets
+ * connected and the parked tool call is never re-run, which looks exactly like
+ * the freeze the whole flow exists to prevent. It also tidies the query string,
+ * so a refresh does not try to redeem a code that is already spent.
+ */
+export async function completeRedirectedConnection(
+  chat: ChatClient,
+  options: { search?: string } = {},
+): Promise<RunAppConnectionResult | null> {
+  if (typeof window === 'undefined') return null
+
+  const params = new URLSearchParams(options.search ?? window.location.search)
+  const code = params.get(RETURN_CODE)
+  const state = params.get(RETURN_STATE)
+  const error = params.get(RETURN_ERROR)
+  if (!code && !state && !error) return null
+
+  const pending = readPending()
+  writePending(null)
+  clearReturnParams(params)
+
+  if (error || !code || !state) {
+    return { status: 'cancelled', reason: 'denied', error: error ?? 'callback carried no code' }
+  }
+  if (!pending) {
+    // The code is real but we no longer know which call it was for — a tab
+    // restored from history, or storage cleared mid-flow. The connection can
+    // still be completed; only the resume is lost, and the next attempt at the
+    // tool will find an account waiting.
+    await chat.completeAppConnection({ code, state })
+    return { status: 'connected', resume: { ok: true } }
+  }
+
+  await chat.completeAppConnection({ code, state })
+  // A voluntary connect parks nothing, so returning from one has nothing to
+  // resume — the account is the outcome.
+  if (!pending.pendingToolCallId) return { status: 'connected' }
+  const resume = await chat.resumeToolCall(pending.pendingToolCallId)
+  return { status: 'connected', resume }
+}
+
+/** Strip our parameters from the address bar without reloading or losing theirs. */
+function clearReturnParams(params: URLSearchParams): void {
+  params.delete(RETURN_CODE)
+  params.delete(RETURN_STATE)
+  params.delete(RETURN_ERROR)
+  const query = params.toString()
+  window.history.replaceState(
+    window.history.state,
+    '',
+    `${window.location.pathname}${query ? `?${query}` : ''}${window.location.hash}`,
+  )
+}
+
+type CallbackOutcome =
+  | { status: 'received'; code: string; state: string }
+  | { status: 'cancelled'; reason: 'closed' | 'denied' | 'timeout'; error?: string }
+
+/**
+ * Wait for whichever comes first: the callback message, the popup closing, or
+ * the timeout.
+ *
+ * The poll for `popup.closed` is what makes "the user gave up" a real outcome
+ * instead of a promise that never settles — there is no close event across
+ * windows. Every path runs the same teardown, because a listener left on
+ * `window` after a cancelled connect will happily act on the NEXT one.
+ */
+function waitForCallback(
+  popup: Window,
+  expectedOrigin: string,
+  timeoutMs: number,
+): Promise<CallbackOutcome> {
+  return new Promise<CallbackOutcome>((resolve) => {
+    let settled = false
+
+    const finish = (outcome: CallbackOutcome) => {
+      if (settled) return
+      settled = true
+      window.removeEventListener('message', onMessage)
+      clearInterval(closeTimer)
+      clearTimeout(timeoutTimer)
+      resolve(outcome)
+    }
+
+    const onMessage = (event: MessageEvent) => {
+      // The origin check is the security boundary: this message carries an
+      // authorization code, and any page may post to an opener.
+      if (event.origin !== expectedOrigin) return
+      const data = event.data as ConnectCallbackMessage | undefined
+      if (!data || data.type !== CONNECT_MESSAGE_TYPE) return
+
+      if (data.error) return finish({ status: 'cancelled', reason: 'denied', error: data.error })
+      if (!data.code || !data.state) {
+        return finish({ status: 'cancelled', reason: 'denied', error: 'callback carried no code' })
+      }
+      finish({ status: 'received', code: data.code, state: data.state })
+    }
+
+    window.addEventListener('message', onMessage)
+
+    const closeTimer = setInterval(() => {
+      // A small grace period is unnecessary: the callback page posts BEFORE it
+      // closes, and `message` is delivered in order.
+      if (popup.closed) finish({ status: 'cancelled', reason: 'closed' })
+    }, 400)
+
+    const timeoutTimer = setTimeout(() => {
+      finish({ status: 'cancelled', reason: 'timeout' })
+    }, timeoutMs)
+  })
+}

package/src/doctor.ts

@@ -0,0 +1,176 @@
+/**
+ * A development-time watchdog for the ways a chat goes quiet.
+ *
+ * The failure this exists for looks like nothing at all: the agent stops
+ * mid-turn because it is waiting for a person, the integration does not render
+ * the card that would let them answer, and the run sits there until it lapses.
+ * No error, no rejected promise, no failed request — which is precisely why it
+ * reaches production. The first anyone hears of it is a user saying "it froze".
+ *
+ * So the SDK watches its own stream in development. When something parks and
+ * nothing settles it within a grace period, this says so, in the integrator's
+ * console, naming the call they are missing. Silence becomes a message at the
+ * moment it happens rather than a support ticket a week later.
+ *
+ * Off in production, always: it tees the response body to read it, and that is
+ * a cost worth paying for a warning nobody in production would see.
+ */
+
+export type DoctorConcern = 'approval' | 'connect' | 'unauthorized'
+
+export interface ChatDoctorOptions {
+  /** Force on or off. Defaults to on outside production. */
+  enabled?: boolean
+  /**
+   * How long a parked run may go unanswered before it is worth mentioning.
+   *
+   * Long enough that a UI fetching its pending list on the next tick is never
+   * scolded; short enough to land while the developer is still looking at the
+   * screen that caused it.
+   */
+  graceMs?: number
+  /** Where warnings go. Defaults to `console.warn`. */
+  onWarn?: (concern: DoctorConcern, message: string) => void
+}
+
+const DEFAULT_GRACE_MS = 10_000
+
+function defaultEnabled(): boolean {
+  // `process` is absent in a browser bundle that did not shim it; absent means
+  // we cannot prove production, and a dev warning is the safer default.
+  const mode =
+    typeof process !== 'undefined' ? (process.env?.NODE_ENV ?? undefined) : undefined
+  return mode !== 'production'
+}
+
+const ADVICE: Record<DoctorConcern, string> = {
+  approval: [
+    'A tool call is parked waiting for a person to approve it, and nothing has answered.',
+    'The run is alive and BLOCKED — it will not continue until it is settled or expires.',
+    '',
+    '  const pending = await chat.listPendingApprovals(conversationId)',
+    "  await chat.respondToApproval(pending[0].id, 'approve')",
+    '',
+    'Using @frontera-sdk/chat-ui, render <PendingCards conversationId={…} />.',
+    'Read the pending list on mount too: a reload loses the stream chunk, not the block.',
+  ].join('\n'),
+  connect: [
+    "A tool needs this user's own account and returned `needs_connect`; nothing has started a connection.",
+    'The agent has been told NOT to ask in prose, so if your UI stays silent, nothing is said.',
+    '',
+    '  await runAppConnection(chat, { pendingToolCallId, installId, redirectUri })',
+    '',
+    'Using @frontera-sdk/chat-ui, pass `connectRedirectUri` to <FronteraChat>.',
+  ].join('\n'),
+  unauthorized: [
+    'A request was refused with UNAUTHORIZED and no refresh is wired, so the next send will fail too.',
+    '',
+    '  const session = createTokenSession({ apiBaseUrl, getToken })',
+    '  createChatTransport(session.getClient, { onUnauthorized: session.refresh })',
+  ].join('\n'),
+}
+
+class ChatDoctor {
+  private options: ChatDoctorOptions = {}
+  private timers = new Map<DoctorConcern, ReturnType<typeof setTimeout>>()
+
+  configure(options: ChatDoctorOptions): void {
+    this.options = { ...this.options, ...options }
+  }
+
+  get enabled(): boolean {
+    return this.options.enabled ?? defaultEnabled()
+  }
+
+  private warn(concern: DoctorConcern): void {
+    const message = `[frontera-chat] ${ADVICE[concern]}`
+    if (this.options.onWarn) this.options.onWarn(concern, message)
+    else console.warn(message)
+  }
+
+  /**
+   * Something parked. Start counting; `resolved` before the grace period ends
+   * cancels it.
+   */
+  parked(concern: DoctorConcern): void {
+    if (!this.enabled || this.timers.has(concern)) return
+    const timer = setTimeout(() => {
+      this.timers.delete(concern)
+      this.warn(concern)
+    }, this.options.graceMs ?? DEFAULT_GRACE_MS)
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+    this.timers.set(concern, timer)
+  }
+
+  /** The integration did the thing. Nothing to warn about. */
+  resolved(concern: DoctorConcern): void {
+    const timer = this.timers.get(concern)
+    if (!timer) return
+    clearTimeout(timer)
+    this.timers.delete(concern)
+  }
+
+  /** Immediate, not timed: nothing about a missing refresh improves by waiting. */
+  noticed(concern: DoctorConcern): void {
+    if (this.enabled) this.warn(concern)
+  }
+
+  /** For tests, and for a host that unmounts a chat mid-run. */
+  reset(): void {
+    for (const timer of this.timers.values()) clearTimeout(timer)
+    this.timers.clear()
+  }
+
+  /**
+   * Watch a chat stream for the two things that park a run.
+   *
+   * The body is teed rather than parsed: this reads a copy as text and matches
+   * two markers, leaving the real stream untouched for the AI SDK. A full parse
+   * here would be a second implementation of the protocol, kept in step with
+   * the first by hope.
+   */
+  observe(response: Response): Response {
+    if (!this.enabled || !response.body) return response
+
+    const [forCaller, forDoctor] = response.body.tee()
+    void this.scan(forDoctor)
+
+    // Headers and status are carried over: callers read the conversation and
+    // run ids off them, and a Response rebuilt without them breaks everything
+    // downstream of a warning that was supposed to be passive.
+    return new Response(forCaller, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    })
+  }
+
+  private async scan(stream: ReadableStream<Uint8Array>): Promise<void> {
+    const reader = stream.getReader()
+    const decoder = new TextDecoder()
+    try {
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        const text = decoder.decode(value, { stream: true })
+        if (text.includes('tool-approval-request')) this.parked('approval')
+        if (text.includes('needs_connect')) this.parked('connect')
+      }
+    } catch {
+      // A cancelled or broken stream is not a diagnostic finding. The caller's
+      // copy reports the failure through its own path.
+    } finally {
+      reader.releaseLock()
+    }
+  }
+}
+
+/**
+ * The instance the SDK reports into. Exported so a host can quieten it, widen
+ * the grace period, or route warnings into their own logger:
+ *
+ * ```ts
+ * chatDoctor.configure({ enabled: false })
+ * ```
+ */
+export const chatDoctor = new ChatDoctor()