From fa3381c79db59a3d8ebd2f3e71c2028524fdf189 Mon Sep 17 00:00:00 2001 From: anurag629 Date: Thu, 29 Oct 2026 23:45:17 +0530 Subject: [PATCH] docs: keep the 0.5 stream format through 1.x, and say so --- .changeset/legacy-format-through-1x.md | 5 +++++ packages/server/src/handler.ts | 2 +- website/src/content/docs/getting-started/upgrading-to-1.mdx | 2 ++ website/src/content/docs/getting-started/upgrading.mdx | 2 +- website/src/content/docs/server/setup.mdx | 2 +- 5 files changed, 10 insertions(+), 3 deletions(-) create mode 100644 .changeset/legacy-format-through-1x.md diff --git a/.changeset/legacy-format-through-1x.md b/.changeset/legacy-format-through-1x.md new file mode 100644 index 00000000..a885157c --- /dev/null +++ b/.changeset/legacy-format-through-1x.md @@ -0,0 +1,5 @@ +--- +"@chatcops/server": patch +--- + +The 0.5 stream format, for widgets older than 0.6 and clients that don't send `protocol: 1`, stays through 1.x and goes away in 2.0. The startup note and the docs said 1.0. diff --git a/packages/server/src/handler.ts b/packages/server/src/handler.ts index 353a305a..1d04c6e2 100644 --- a/packages/server/src/handler.ts +++ b/packages/server/src/handler.ts @@ -146,7 +146,7 @@ export function createChatHandler(config: ChatCopsServerConfig) { loggedLegacyFormat = true; log.info( 'legacy_stream_format', - 'Answered a request in the 0.5 stream format, from a widget older than 0.6 or a client that doesn\'t send `protocol: 1`. That format keeps working until 1.0.' + 'Answered a request in the 0.5 stream format, from a widget older than 0.6 or a client that doesn\'t send `protocol: 1`. That format keeps working through 1.x and goes away in 2.0.' ); } diff --git a/website/src/content/docs/getting-started/upgrading-to-1.mdx b/website/src/content/docs/getting-started/upgrading-to-1.mdx index 404c1810..69d9cab9 100644 --- a/website/src/content/docs/getting-started/upgrading-to-1.mdx +++ b/website/src/content/docs/getting-started/upgrading-to-1.mdx @@ -5,6 +5,8 @@ description: What 1.0 removed, and what to change in your config or code, one st 1.0 removes the options and methods that 0.6 to 0.8 marked as deprecated. Each one now fails at startup with a message that names what to use instead and links here, so an upgrade can't quietly change how your chat behaves. After 1.0, ChatCops follows semver strictly: a breaking change waits for 2.0. +The one thing 1.0 keeps from 0.x on purpose is the 0.5 stream format. A widget older than 0.6, or a client that doesn't send `"protocol": 1`, still gets it, so pages with an old widget cached or pinned on a CDN keep working. It, and `regenerate: true` in requests (what those widgets send), go away in 2.0. The server logs `legacy_stream_format` the first time it answers in it, so you can tell when it's safe to stop caring. + Go through the sections for the packages you use. If you're on 0.5 or earlier, read [Upgrading from 0.5](/getting-started/upgrading/) first. ## `@chatcops/server` diff --git a/website/src/content/docs/getting-started/upgrading.mdx b/website/src/content/docs/getting-started/upgrading.mdx index 6a60cb86..410097ac 100644 --- a/website/src/content/docs/getting-started/upgrading.mdx +++ b/website/src/content/docs/getting-started/upgrading.mdx @@ -9,7 +9,7 @@ The versions are `@chatcops/server` 0.6, `@chatcops/widget` 0.6 and `@chatcops/c ## Upgrade the server first -Upgrade the server, deploy it, then update the widget. A widget from 0.5 or earlier sends requests without `"protocol": 1`, and the new server answers those in the exact 0.5 format until 1.0. The server logs one line the first time it does, so you can tell when old widgets are still around (cached pages, a pinned CDN version). +Upgrade the server, deploy it, then update the widget. A widget from 0.5 or earlier sends requests without `"protocol": 1`, and the new server answers those in the exact 0.5 format, through 1.x. The server logs one line the first time it does, so you can tell when old widgets are still around (cached pages, a pinned CDN version). The 0.6 widget also works against a 0.5 server, so the order isn't critical. It just gets more from a 0.6 one: reply ids that regenerate can name, and a clear "cut off" state when a stream ends early. diff --git a/website/src/content/docs/server/setup.mdx b/website/src/content/docs/server/setup.mdx index 7c3f721b..83446be2 100644 --- a/website/src/content/docs/server/setup.mdx +++ b/website/src/content/docs/server/setup.mdx @@ -437,7 +437,7 @@ The widget sends pre-chat answers in `userData`. See the [pre-chat form guide](/ ## Response format -The server answers in one of two formats. The widget from 0.6 on sends `"protocol": 1` in the request body and gets protocol v1. Requests without it, from widgets before 0.6 or older custom clients, get the 0.5 format, which keeps working until 1.0. A client can also ask for v1 with an `x-chatcops-protocol: 1` header. The server logs one line the first time it answers in the 0.5 format, so you can tell when old widgets are still around. `chatcopsAiSdkHandler` answers in a third format, the AI SDK's, for apps built on `useChat` (see [AI SDK](/server/ai-sdk/)). +The server answers in one of two formats. The widget from 0.6 on sends `"protocol": 1` in the request body and gets protocol v1. Requests without it, from widgets before 0.6 or older custom clients, get the 0.5 format, which keeps working through 1.x and goes away in 2.0. A client can also ask for v1 with an `x-chatcops-protocol: 1` header. The server logs one line the first time it answers in the 0.5 format, so you can tell when old widgets are still around. `chatcopsAiSdkHandler` answers in a third format, the AI SDK's, for apps built on `useChat` (see [AI SDK](/server/ai-sdk/)). The server writes one reply per conversation at a time, so a second message sent while a reply is streaming is refused instead of answering the same history twice. The widget doesn't let visitors send while a reply streams, so this only shows up with custom clients.