@frontera-sdk/chat 1.50.40

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sebati
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,215 @@
+# @frontera-sdk/chat
+
+Typed client and React hooks for chatting with a Frontera agent from your own application. This package is the chat **API** — you bring the UI.
+
+```bash
+bun add @frontera-sdk/chat @frontera-sdk/core ai
+```
+
+## Credentials
+
+Two kinds, both carried by `FronteraClient`:
+
+- **Agent API key (`sak_…`)** — minted in Console → Agents → API keys. Bound to one agent and its workspace. **A server-side secret: never ship it to a browser.**
+- **End-user chat token (`cht_…`)** — obtained by your backend via `exchangeChatToken` (requires a deployment with the `/v1/chat-tokens` endpoint). Short-lived, scoped to one agent and one of *your* users, safe to use from your frontend. Sebati enforces per-user session isolation for these.
+
+## Server-side quickstart
+
+```ts
+import { FronteraClient } from '@frontera-sdk/core/client'
+import { ChatClient } from '@frontera-sdk/chat/chat-client'
+import { readChatStream } from '@frontera-sdk/chat/ui-stream'
+
+const client = new FronteraClient({
+  apiBaseUrl: 'https://api.your-deployment.example',
+  credential: { kind: 'apiKey', key: process.env.SEBATI_AGENT_KEY! },
+})
+const chat = new ChatClient(client)
+
+const session = await chat.createSession()
+const run = await chat.startChat({
+  conversationId: session.id,
+  messages: [{ id: crypto.randomUUID(), role: 'user', parts: [{ type: 'text', text: 'Halo!' }] }],
+})
+
+for await (const message of readChatStream(run.response)) {
+  // message.parts grows as the agent streams
+}
+
+const history = await chat.getMessages(run.conversationId)
+```
+
+## React quickstart
+
+```tsx
+import { useChat } from '@ai-sdk/react'
+import { createChatTransport } from '@frontera-sdk/chat/transport'
+
+const transport = createChatTransport(client, {
+  onStart: ({ runId }) => setRunId(runId), // for cancel/steer/reconnect
+})
+
+function Chat() {
+  const { messages, sendMessage, status } = useChat({ transport })
+  // render messages, call sendMessage({ text }) from your composer
+}
+```
+
+Persisted state (session lists, history) has TanStack Query hooks in `@frontera-sdk/chat/hooks` behind `FronteraChatContext.Provider`.
+
+## Deployment patterns
+
+1. **Proxy (works everywhere today).** Your frontend talks to your backend; your backend holds the `sak_` key and forwards `/v1/*` to Sebati (`apiBaseUrl` can simply point at your proxy). All of your users share one principal, so **you** must enforce which user may touch which conversation — wire `authorizeConversation` to your own user↔conversation store:
+
+   ```ts
+   const chat = new ChatClient(client, {
+     authorizeConversation: async (conversationId) =>
+       (await myDb.conversationOwner(conversationId)) === currentUser.id,
+   })
+   ```
+
+   Under API-key auth the server accepts any conversation id belonging to the key's agent — this callback is the only barrier between your users. Run ids are capabilities: hand them only to the user whose send produced them.
+
+2. **Token exchange (deployments with `/v1/chat-tokens`).** Your backend exchanges the key for a per-user token; your frontend talks to Sebati directly and Sebati enforces isolation:
+
+   ```ts
+   import { exchangeChatToken, withChatToken } from '@frontera-sdk/chat/auth'
+   const token = await exchangeChatToken(client, { externalUserId: user.id, name: user.name })
+   // send `token` to the frontend; there:
+   const userClient = withChatToken(client, token)
+   ```
+
+## Staying signed in
+
+Mint once per user session; the SDK keeps it alive against the platform, so your backend is
+not called again on a timer:
+
+```ts
+import { createTokenSession } from '@frontera-sdk/chat/token-session'
+
+const session = createTokenSession({
+  apiBaseUrl: 'https://api.your-deployment.example',
+  getToken: () => fetch('/api/chat-token').then((r) => r.json()),
+})
+const chat = new ChatClient(session.getClient())
+
+// and so a token that expired while the tab slept costs a retry, not a failure:
+const transport = createChatTransport(session.getClient, { onUnauthorized: session.refresh })
+```
+
+Renews at 80% of each token's life against `POST /v1/chat-tokens/renew`, falls back to
+`getToken` when the session hits its 12-hour ceiling, and shares one in-flight refresh
+between concurrent callers. Revocation does not depend on any of this: disabling an external
+user takes effect on their next request.
+
+## Approvals
+
+An agent in `ask` approval mode parks a tool call and **waits**: the stream
+emits `{ type: 'tool-approval-request', approvalId, toolCallId }` and then goes
+quiet until someone answers. Ignore it and the conversation looks stalled.
+
+```ts
+const pending = await chat.listPendingApprovals(conversationId)  // also on mount
+await chat.respondToApproval(pending[0].id, 'approve')           // or 'deny'
+```
+
+React: `usePendingApprovals(conversationId)` / `useRespondToApproval(conversationId)`.
+
+Requires an end-user `cht_` token — a decision belongs to a person, and an
+`sak_` key stands for all of your users at once (403). For unattended
+operation, set the agent's approval mode to `auto` instead.
+
+## Connecting your user's own accounts
+
+A tool needing the end user's own Google/Microsoft/Slack account parks with
+`pauseReason: 'needs_connect'` and an `installId`:
+
+```ts
+const conn = await chat.startAppConnection({
+  installId: parked.installId,
+  redirectUri: 'https://app.yourproduct.example/frontera/oauth/callback',
+})
+window.open(conn.authUrl, 'connect', 'width=520,height=640')
+// your callback → your page:
+await chat.completeAppConnection({ code, state })
+await chat.resumeToolCall(parked.id)
+```
+
+Or let `runAppConnection` do all of it — popup, origin check, exchange, resume, the "they
+closed the window" case, and the mobile fallback where popups are blocked and the flow
+becomes a full-page redirect:
+
+```ts
+import { runAppConnection, completeRedirectedConnection } from '@frontera-sdk/chat/connect-popup'
+
+const result = await runAppConnection(chat, {
+  pendingToolCallId: parked.id,
+  installId: parked.installId,
+  redirectUri: 'https://app.yourproduct.example/frontera/oauth/callback',
+})
+// 'connected' | 'cancelled' | 'redirecting'  (redirecting = mobile; finishes on return)
+
+// once, when your chat mounts:
+useEffect(() => { void completeRedirectedConnection(chat) }, [chat])
+```
+
+Your callback page, in whichever form fits: `<FronteraOAuthCallback />` from
+`@frontera-sdk/chat-ui/oauth-callback`, `connectCallbackResponse()` from
+`@frontera-sdk/chat/callback-page` for any JS server, or the same HTML served statically by a
+backend in another language.
+
+The callback must be on **your** domain — a provider only authorises redirect
+URIs under a domain the OAuth project's owner has verified, and you cannot
+verify ours. So this needs your own OAuth client, which is also the honest
+answer to whose name appears on the consent screen.
+
+Setup, once: register the redirect URI with your OAuth client and on the
+workspace embed allowlist, add your client under Settings → Secrets, turn on
+*allow external users* for the install, and mint tokens with
+`capabilities: ['plugin-connect']`. The last two are the two halves of the
+authorization — we decide whether an install is reachable by external users at
+all, you decide which of your users may do it, against your own roles. We never
+model or store those roles; your decision expires with the token.
+
+## Development doctor
+
+The SDK watches its own stream in development. When a run parks and nothing
+settles it within 10 seconds, it says so in your console, naming the call you
+are missing:
+
+```
+[frontera-chat] 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')
+```
+
+It covers the three silent failures: an unhandled approval, an unhandled
+`needs_connect`, and a `401` with no refresh wired. Off in production, where it
+would cost a stream tee for a warning nobody reads.
+
+```ts
+import { chatDoctor } from '@frontera-sdk/chat/doctor'
+chatDoctor.configure({ enabled: false })          // or: graceMs, onWarn
+```
+
+## Errors
+
+Failures — including ones that end a `useChat` send — surface as
+`FronteraError` with the service's `code` and `status`, so `UNAUTHORIZED`
+(refresh the token), `QUOTA_EXCEEDED`, `RATE_LIMITED` and `FORBIDDEN` are
+distinguishable rather than one opaque string. Don't switch exhaustively: the
+service adds codes.
+
+## Scope and limitations
+
+- One `sak_` key = one agent. Multiple agents = one client per key. Per-user agent permissions are your mint/routing decision.
+- The credential's agent always wins; `agentName` in requests is ignored.
+- No file upload endpoint under key auth: `fileAttachments[].url` must be a URL you host.
+- Artifacts/docs the agent creates surface as ids in message parts; their bytes are not fetchable under key auth.
+- `updateSession` / `deleteSession` / `forkSession` / `exportSession` need a credential that names one person: they work under a `cht_` end-user token, and answer 403 under an `sak_` key.
+- Sharing a conversation is platform-only under both credentials — a share link needs no credential at all, so publishing is your product's decision to implement.
+- App tools bound to an END USER's own account (`accountMode: end_user`) need the connect flow above, which requires your own OAuth client and a callback on your domain. Workspace- and agent-owned accounts need none of that.
+- `POST /v1/chat-tokens` is rate limited per credential (120/min by default, `429 RATE_LIMITED`). Exchange once per end-user session — the token is valid for its whole TTL.
+- The stream carries `: ping` SSE keepalive comments every 15s; AI SDK parsers ignore them — don't hand-parse the stream.

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@frontera-sdk/chat",
+  "version": "1.50.40",
+  "description": "Typed client and React hooks for chatting with a Frontera agent from your own application.",
+  "keywords": [
+    "frontera",
+    "chat",
+    "agent",
+    "react",
+    "hooks"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "src",
+    "!src/__tests__",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./types": {
+      "types": "./src/types.ts",
+      "import": "./src/types.ts"
+    },
+    "./chat-client": {
+      "types": "./src/chat-client.ts",
+      "import": "./src/chat-client.ts"
+    },
+    "./auth": {
+      "types": "./src/auth.ts",
+      "import": "./src/auth.ts"
+    },
+    "./stream": {
+      "types": "./src/stream.ts",
+      "import": "./src/stream.ts"
+    },
+    "./ui-stream": {
+      "types": "./src/ui-stream.ts",
+      "import": "./src/ui-stream.ts"
+    },
+    "./doctor": {
+      "types": "./src/doctor.ts",
+      "import": "./src/doctor.ts"
+    },
+    "./token-session": {
+      "types": "./src/token-session.ts",
+      "import": "./src/token-session.ts"
+    },
+    "./callback-page": {
+      "types": "./src/callback-page.ts",
+      "import": "./src/callback-page.ts"
+    },
+    "./connect-popup": {
+      "types": "./src/connect-popup.ts",
+      "import": "./src/connect-popup.ts"
+    },
+    "./transport": {
+      "types": "./src/transport.ts",
+      "import": "./src/transport.ts"
+    },
+    "./hooks": {
+      "types": "./src/hooks.ts",
+      "import": "./src/hooks.ts"
+    },
+    "./provider": {
+      "types": "./src/provider.tsx",
+      "import": "./src/provider.tsx"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "smoke": "bun run scripts/smoke.ts"
+  },
+  "dependencies": {
+    "@frontera-sdk/core": "1.50.40"
+  },
+  "peerDependencies": {
+    "@ai-sdk/react": "^3.0.0",
+    "@tanstack/react-query": "^5.90.21",
+    "ai": "^6.0.116",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/react": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.90.21",
+    "@types/bun": "^1.3.14",
+    "@types/react": "^19",
+    "ai": "^6.0.116",
+    "react": "19.2.5",
+    "typescript": "^5.9.3"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,27 @@
+import type { FronteraClient } from '@frontera-sdk/core/client'
+
+import type { ChatToken, ExchangeTokenRequest } from './types'
+
+/**
+ * Exchange an agent API key (`sak_`) plus your user's identity for a
+ * short-lived scoped chat token (`cht_`). Server-side only: the client passed
+ * here must carry the `sak_` credential, which must never reach a browser.
+ *
+ * The token is safe to hand to your frontend — it is scoped to one workspace,
+ * one agent and one external user, and Sebati enforces session isolation per
+ * external user.
+ *
+ * Requires a deployment with the `/v1/chat-tokens` endpoint; older deployments
+ * answer 404, surfaced as a `FronteraError` with code `NOT_FOUND`.
+ */
+export function exchangeChatToken(
+  client: FronteraClient,
+  request: ExchangeTokenRequest,
+): Promise<ChatToken> {
+  return client.request<ChatToken>('/v1/chat-tokens', { method: 'POST', body: request })
+}
+
+/** A client that authenticates with the exchanged end-user token. */
+export function withChatToken(client: FronteraClient, token: ChatToken): FronteraClient {
+  return client.withCredential({ kind: 'token', token: token.token })
+}