@cosmoops/connect-sdk 0.6.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,171 @@
 `@cosmoops/connect-sdk` follows semver, with the 0.x convention that **minor
 versions may carry breaking changes** and patch versions never do.
 
+## 0.9.0
+
+### Added
+
+- **`user.workspaceType`** on `exchangeCode()` and `getUser()` - `"individual"`
+  (a one-seat personal account, KYC) or `"business"` (a team, KYB). The one
+  fact about the signed-in workspace a partner could not look up on its own:
+  the application API has no workspace read, so an application serving both
+  audiences had to render one UI for everybody. An `"individual"` workspace
+  has exactly one seat and can never gain another, so a members table, an
+  invite button and a seat meter are all dead controls there.
+
+  Re-read it rather than caching it past sign-in: an individual workspace can
+  convert to a business one under a live session (the reverse never happens).
+
+- **`audience`** on the same two responses - what your application is *sold*
+  to, joined with the account in front of you:
+
+  ```ts
+  const { user, audience } = await connect.identity.exchangeCode({ code, redirectUri });
+  // user.workspaceType    -> "individual"
+  // audience.application  -> "b2b"
+  // audience.matches      -> false
+  ```
+
+  `matches: false` is a hard block, not a hint: readiness reports an
+  `audience_mismatch` blocker and any attempt to subscribe is refused. It ships
+  alongside `workspaceType` so the check stays `!audience.matches` instead of a
+  hardcoded audience constant in your own code that goes stale the moment the
+  catalogue entry changes. `audience.enforcedAtSignIn` tells you whether
+  Connect refuses the sign-in itself, in which case a mismatch can only reach
+  you on a session minted before that setting was turned on.
+
+- **`<ConnectWorkspaceTypeGate>`**, plus `useConnectWorkspaceType()` and
+  `useConnectAudience()`:
+
+  ```tsx
+  <ConnectWorkspaceTypeGate type="business">
+    <TeamMembersTable />
+  </ConnectWorkspaceTypeGate>
+  ```
+
+  This is *not* the audience gate - it does not know what your application is
+  sold to, and is for varying what each account type sees *inside* an
+  application both audiences can reach. `<ConnectAccessGate>` remains the one
+  that blocks a mismatched account outright, and already did.
+
+  Like every gate in this package: a UX gate, not a security boundary.
+
+- **`<ConnectAskAi>`**, and `askAi` on `AppShell` - a chat panel grounded in
+  the signed-in workspace's Context Index. **On by default**, like `gate`:
+
+  ```tsx
+  <AppShell name="Dispatch" nav={nav}>
+    {children}
+  </AppShell>
+  ```
+
+  It stays inert until it can work - nothing renders for a signed-out visitor,
+  and a workspace whose Context Index is off gets a message in the panel rather
+  than a broken answer. Pass `askAi={false}` for an application that should not
+  offer it, or an object to override the heading, copy or markdown plugins.
+
+  It holds no credential, like everything else in `./client`: it POSTs to
+  `${basePath}/ai/chat`, a new bridge route on `createConnectHandler` that
+  resolves the workspace from the caller's own session and streams Connect's
+  answer straight through. A browser-supplied `workspaceId` would be another
+  tenant's documents delivered as a chat reply, so there isn't one.
+
+  The panel parses the server-sent event stream itself rather than pulling in
+  `ai`/`@ai-sdk/react`.
+
+- **Answers that draw, not just write.** Connect's Ask AI can call a small set
+  of *presentation tools*, and this panel renders each one natively:
+
+  | Tool | Rendered as |
+  |---|---|
+  | `showTable` | a sortable table with a CSV download |
+  | `showChart` | a bar / line / area chart (inline SVG), or a labelled proportion list for `pie` |
+  | `showMetrics` | up to six metric tiles with period-over-period deltas |
+  | `showTimeline` | dated events on a rail |
+  | `showDetails` | one entity's fields as a fact sheet |
+  | `showSteps` | a numbered procedure |
+  | `showSources` | the documents a grounded answer rested on |
+
+  Every value arrives **raw with a format tag** - a currency is the number
+  `12500`, never the string `"₹12,500"` - so it is formatted in the viewer's
+  locale here, and a column still sorts numerically. The seven widgets and
+  `formatAiValue` are exported for a partner rendering Connect's chat somewhere
+  other than this panel.
+
+  No charting library ships in this package: the chart is hand-drawn SVG. A
+  400px side panel does not need pan, zoom or brushes, and a charting
+  dependency is not a reasonable thing to make every platform install.
+
+- **Markdown, via `streamdown`** - tables, fenced code, task lists, and a
+  word-by-word `blurIn` reveal with a caret while the answer streams. Three
+  host steps, all one-time:
+
+  1. `npm i streamdown` (a new **optional** peer dependency - the panel is the
+     only thing that uses it).
+  2. `@source "…/node_modules/streamdown/dist/*.js";` in your Tailwind CSS, so
+     its utility classes are generated.
+  3. `import "streamdown/styles.css";` for the streaming animation.
+
+  The colour tokens Streamdown expects (it paints with shadcn/ui's names) are
+  mapped onto HeroUI's in this SDK's `theme.css`, which you already import - so
+  answers inherit your platform's theme with no further work.
+
+  Syntax highlighting, KaTeX, Mermaid and CJK typography are Streamdown plugin
+  packages, off unless you pass them - several are large, and prose, tables and
+  plain code fences render without any of them:
+
+  ```tsx
+  import { code } from "@streamdown/code";
+  const PLUGINS = { code };   // module scope: Streamdown compares this by reference
+
+  <AppShell name="Dispatch" nav={nav} askAi={{ markdownPlugins: PLUGINS }}>
+  ```
+
+- `streamResource()` on `useConnect()` - POST through the bridge and get the
+  raw `Response` back, unread and uncached. The seam `<ConnectAskAi>` streams
+  over, and the one to use for any future streaming route.
+
+### Changed
+
+- `ConnectSession` (the value behind `useConnect()`) carries `audience`,
+  `null` when signed out alongside the three fields that already were.
+
+### Known gaps
+
+- No SDK methods for the channel and call endpoints (`GET /channels`,
+  `GET`/`PUT`/`DELETE /channels/{channelId}/routing`, `GET /calls`,
+  `GET /calls/{callId}`). They are documented in the partner API and callable
+  over HTTP; they just have no typed wrapper here yet. The conformance suite
+  names them, and stays red until they land.
+
+### Fixed
+
+- `ai.chat()` no longer has its stream cut off mid-answer. The transport's
+  `timeoutMs` (20s by default) was handed to `fetch` as an `AbortSignal`, and a
+  `fetch` signal keeps governing the *body* long after the headers arrive - so
+  any conversation that took longer than the timeout to finish generating was
+  torn down. The timeout is now cleared once an attempt is done reading, which
+  for a `raw` (streaming) request means once the headers land. Pass your own
+  `signal` to bound the stream itself.
+
+## 0.8.0
+
+*Never published - `0.9.0` is the first release carrying these changes.*
+
+### Changed (breaking)
+
+- **`ConnectAppShell` renamed to `AppShell`.** No other change - same props,
+  same behaviour. Every other component in `/client` keeps its `Connect`
+  prefix; this is the one exception, by request. Update the import:
+
+  ```diff
+  - import { ConnectAppShell, type ConnectAppShellProps } from "@cosmoops/connect-sdk/client";
+  + import { AppShell, type AppShellProps } from "@cosmoops/connect-sdk/client";
+  ```
+
+  If your own layout component is also called `AppShell` (a common name for
+  one), alias the import: `import { AppShell as ConnectAppShell } from "..."`.
+
 ## 0.6.0
 
 ### Added