@savantoai/ai-sdk 2.1.0 → 3.1.0

package/CHANGELOG.md

@@ -0,0 +1,206 @@
+# Changelog
+
+All notable changes to `@savantoai/ai-sdk` will be documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and we follow [semantic versioning](https://semver.org/) — see _Versioning policy_
+below for the one nuance that applies to a generated SDK.
+
+## Versioning policy
+
+This SDK is fully regenerated from `cloud/openapi.json` by
+[`@hey-api/openapi-ts`](https://github.com/hey-api/openapi-ts). Generator and
+schema changes can _both_ produce TypeScript-only breaking changes (e.g. a
+field gains `| null`, a `body` shape narrows, a top-level helper type
+widens) without changing any runtime behaviour. We treat those as breaking
+under semver, meaning:
+
+- A change that **narrows** a previously-accepted type (e.g. record →
+  concrete interface) is a major version bump.
+- A change that **widens** a previously-non-nullable type to include `null`
+  is a major version bump.
+- Generator-driven changes to top-level re-exports (`Client`, `Config`,
+  `Options`, `RequestResult`, `RequestOptions`) are major version bumps.
+- Pure additions (new endpoints, new optional fields on requests,
+  newly-exported types) are minor.
+- Internal regen with no public-surface diff is patch.
+
+`@hey-api/openapi-ts` is pinned to `~0.97.x` (patch range only) in
+`package.json` so generator-driven type narrowings can't slip in via a
+caret update. Bumping that range is itself a major-version event for the
+SDK.
+
+## 3.1.0 — 2026-05-19
+
+### Added
+
+- Search responses may include `query.truncated` and `query.originalLength` on
+  product and post search when the input text was shortened server-side.
+
+### Changed
+
+- **`POST /recommendations`** response type now uses the standard
+  `{ object, requestId, data }` envelope (`object: "recommendations"`).
+  Payload fields remain under `data`.
+- **OpenAPI alignment** for non-streaming `POST /chat` and `POST /threads/search`
+  (documented envelopes; chat wire format unchanged if you already read `data`).
+- **`POST /threads/search`** list field is `data.items` in generated types (matches
+  the handler; replaces any `results` naming in older spec snapshots).
+
+### Breaking (TypeScript)
+
+- **`Product.stockStatus` and `Product.type`** are strict enums. Values outside
+  `instock | outofstock | onbackorder` and `simple | grouped | external | variable`
+  are omitted at runtime and absent from the type.
+- Any client code that assumed recommendations returned only `{ data: T }` at the
+  top level should use the generated `PostRecommendationsResponse` type (includes
+  `object` and `requestId`).
+
+## Unreleased
+
+### Breaking — streaming chat protocol
+
+> The SDK's TypeScript surface is unchanged, but the **wire protocol** for
+> the `/chat` streaming endpoint has been rewritten. Any client code that
+> switches on `chunk.type` (including code generated against earlier
+> versions of this README's example) must be migrated. The SDK is not
+> under semver for the wire protocol — see _Versioning policy_ above —
+> but we're flagging this prominently because real client switches will
+> silently stop matching after this rollout.
+
+The `/chat` streaming protocol has been rewritten to a block-based shape.
+The legacy `text_delta`, `product`, `post`, `post_delta`, and `bubble_termination`
+chunk types are gone; the new types are `block_start`, `block_delta`, `block_data`,
+`item_delta`, and `block_end`, plus existing flow-control chunks (`progress`,
+`prompts`, `metadata`, `complete`, `error`, `domain_offer`, `domain_offer_success`,
+`agent_status`, `handoff_ended`, `analytics`, `usage`).
+
+Migration cheat-sheet for code switching on `chunk.type`:
+
+| Old chunk type        | New chunk type                                                 |
+| --------------------- | -------------------------------------------------------------- |
+| `text_delta`          | `block_delta` (read `chunk.data.content`)                      |
+| `product` / `post`    | `block_data` (full payload) + `block_start` (ordering)         |
+| `post_delta`          | `item_delta` (read `chunk.data.field` + `chunk.data.delta`)    |
+| `bubble_termination`  | (removed — single message bubble per turn now)                 |
+
+The SDK's exported `ChatStreamChunk` type is intentionally unchanged
+(`{ type: string; data?: unknown }`) — no SDK regen is required. See
+the [Streaming Chat docs](https://savanto.ai/docs/developers/streaming)
+for the full chunk reference and a worked React example.
+
+The streaming `chat.message_sent` webhook payload has also picked up
+`responseMessage.respondedBy` (which domain answered) and
+`responseMessage.composedBlocks` (a tiny `{ type, ids }[]` describing
+the structured blocks the composer wove together for multi-domain answers).
+See the [Webhooks docs](https://savanto.ai/docs/developers/webhooks#chatmessage_sent).
+
+## 3.0.0 — 2026-05-12
+
+### Breaking (TypeScript)
+
+- **`POST /threads/search` `sortBy` enum renamed.** Previously the SDK
+  emitted `'timestamp' | 'message_count' | 'token_count'`, but the
+  server-side handler routed those names through to OpenSearch
+  unchanged — and OpenSearch indexes those fields as `messageCount`
+  and `tokenCount`, so the snake_case values produced an invalid
+  sort clause that callers either silently ignored or got a 500 on.
+  The schema now matches the OpenSearch field names:
+  `'timestamp' | 'messageCount' | 'tokenCount'`.
+  **Migration**: switch `sortBy: 'message_count'` →
+  `sortBy: 'messageCount'`, `'token_count'` → `'tokenCount'`.
+
+### Other
+
+- `UpdateMcpConfigRequest` body has been reopened server-side to
+  accept arbitrary string-URL fields (`catchall(z.string().url())`),
+  so the generated SDK type now allows forward-compatible MCP URI
+  keys (e.g. a future `crmUri`) without an SDK regen. This restores
+  some of the pre-2.2.0 surface flagged in the 2.2.0 section below,
+  but with per-field URL/length validation instead of `passthrough()`.
+
+## 2.2.0 — 2026-05-07
+
+This release was published as a minor bump but **contains TypeScript-level
+breaking changes** that, per the policy above, should have been a major
+(`3.0.0`). It is documented here retroactively so consumers know to add
+null-guards / update destructuring patterns when upgrading from `2.1.x`.
+The next regeneration will be released as `3.0.0`.
+
+### Breaking (TypeScript)
+
+- **~30 fields gained `| null`.** The cloud OpenAPI emitter switched from
+  3.0 (`app.doc()`) to 3.1 (`app.doc31()`), so fields whose Zod schema
+  uses `.nullable()` now serialise as `type: [..., 'null']`, and the
+  generator faithfully reflects that with `T | null`. Affected fields
+  include:
+  - `ErrorResponse.error.param` (`string` → `string | null`)
+  - `Pagination.total` / `Pagination.cursor` (`number | null`,
+    `string | null`) — note that `total` lives on every paginated list
+    response in the SDK.
+  - `Product.price`, `Product.salePrice`, `Product.priceMin`,
+    `Product.priceMax`, `Product.weight`, `Product.dimensions`,
+    `Product.image`, `Product.attributes`, `Product.rating`, and their
+    `ProductInput.*` counterparts.
+  - `Post.publishedAt`, `Post.featuredImage`, `Post.attributes`.
+  - `TenantStatus.publishableKey`.
+
+  Consumer code like `product.price.toFixed(2)` or
+  `if (pagination.total > 0)` will fail TypeScript strict-mode typecheck.
+  **Migration**: add nullish guards or use `??` defaults:
+
+  ```ts
+  product.price?.toFixed(2);
+  if ((pagination.total ?? 0) > 0) { /* … */ }
+  ```
+
+- **Five admin/tenant request bodies narrowed from open-record to concrete
+  interface.** Cloud PR #138 replaced a `genericBody` Zod schema with six
+  typed request schemas. The regenerated SDK reflects this in:
+  - `UpdateWorkspaceData.body` → `UpdateWorkspaceRequest`
+  - `GetUploadUrlData.body` → `GetUploadUrlRequest`
+  - `UpdateMcpConfigData.body` → `UpdateMcpConfigRequest` _(reopened
+    server-side after audit #153 — see Unreleased)_
+  - `StoreCredentialsData.body` → `StoreLiveAgentCredentialsRequest`
+  - `UpdateLiveAgentScheduleData.body` →
+    `UpdateLiveAgentScheduleRequest`
+
+  Callers that were passing extra forward-compatible fields will fail
+  TypeScript typecheck. **Migration**: drop the extra fields — the cloud
+  was always ignoring them; the type just no longer admits them. (The
+  one exception, `updateMcpConfig`, has been reopened server-side; see
+  _Unreleased_.)
+
+- **`RequestResult.request` / `response` made optional.** Generator bump
+  `@hey-api/openapi-ts` `0.94.x` → `0.97.x` changed the success branch of
+  `RequestResult` from `& { request: Request; response: Response }` to
+  `& { request?: Request; response?: Response }`. The change reflects
+  that `request` / `response` can be `undefined` if the failure happened
+  before the network call (DNS, request-building, etc.). Consumer code
+  like `const { data, response } = await chat(...); response.body` will
+  fail strict typecheck. **Migration** — either:
+
+  ```ts
+  // Option A — guard with `if (response)`:
+  const { data, response } = await chat({ client, body: { … } });
+  if (response) { /* response.body, response.status, etc. */ }
+
+  // Option B — opt in to `throwOnError`, which keeps response non-optional:
+  const { data, response } = await chat({
+    client,
+    body: { … },
+    throwOnError: true,
+  });
+  response.body; // typed as `Response`, not `Response | undefined`
+  ```
+
+### Other notes
+
+- `@hey-api/openapi-ts` was bumped from `^0.94.x` to `^0.97.1` as part of
+  this release. Subsequent versions pin to `~0.97.x` to avoid further
+  silent generator-driven type narrowings via caret updates.
+
+## 2.1.0 and earlier
+
+No formal changelog kept prior to 2.2.0. The git history (`sdks/javascript/`)
+is the source of truth for older releases.

package/README.md

@@ -101,6 +101,9 @@ const { data: ids } = await listProductIds({ client });
 ```typescript
 import { chat } from '@savantoai/ai-sdk';
 
+// `throwOnError: true` makes `response` non-optional so `response.body` is
+// safe to read directly. Without it (since 2.2.0) `response` is typed as
+// `Response | undefined`. See CHANGELOG.md for details.
 const { data, response } = await chat({
   client,
   body: {
@@ -108,9 +111,15 @@ const { data, response } = await chat({
     threadId: 'thread-1',
     stream: true,
   },
+  throwOnError: true,
 });
 
-// For streaming (NDJSON), read the response body directly:
+// For streaming (NDJSON), read the response body directly. The protocol is
+// block-based: text streams as `block_delta` chunks inside an active text
+// block, structured items arrive as `block_data` keyed by item id, and
+// per-field streaming (post summaries, product reasons, etc.) flows through
+// `item_delta`. See https://savanto.ai/docs/developers/streaming for the
+// full chunk-type reference.
 const reader = response.body!.getReader();
 const decoder = new TextDecoder();
 
@@ -120,7 +129,7 @@ while (true) {
   const lines = decoder.decode(value).split('\n').filter(Boolean);
   for (const line of lines) {
     const chunk = JSON.parse(line);
-    if (chunk.type === 'text_delta') process.stdout.write(chunk.data);
+    if (chunk.type === 'block_delta') process.stdout.write(chunk.data.content);
   }
 }
 ```
@@ -266,6 +275,12 @@ Full endpoint documentation with request/response schemas:
 
 **[savanto.ai/docs/api](https://savanto.ai/docs/api)**
 
+## Versioning & changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for per-version migration notes,
+including the TypeScript-level breaking changes in `2.2.0`. Type
+narrowings and generator-driven shape changes are treated as major.
+
 ## Regeneration
 
 The SDK is auto-generated from the OpenAPI spec. To regenerate after API changes: