|
1 | 1 | # @cloudflare/tanstack-ai |
2 | 2 |
|
| 3 | +## 0.1.1 |
| 4 | + |
| 5 | +### Patch Changes |
| 6 | + |
| 7 | +- [#396](https://github.com/cloudflare/ai/pull/396) [`2fb3ca8`](https://github.com/cloudflare/ai/commit/2fb3ca80542c8335fea83cac314fa52da772f38f) Thanks [@threepointone](https://github.com/threepointone)! - - Update model recommendations: Aura-2 EN for TTS, Llama 4 Scout for chat examples |
| 8 | + - Add Aura-2 EN/ES to TTS model type |
| 9 | + - Preserve image/vision content in user messages instead of stripping to text-only |
| 10 | + - Add non-streaming fallback when REST streaming fails (GPT-OSS, Kimi) |
| 11 | + - Warn on premature stream termination instead of silently reporting "stop" |
| 12 | + - Consistent console.warn prefix for SSE parse errors |
| 13 | + - Move @cloudflare/workers-types from optionalDependencies to devDependencies (types-only, no runtime use) |
| 14 | + - Fix @openrouter/sdk version mismatch type errors |
| 15 | + |
3 | 16 | ## 0.1.0 |
4 | 17 |
|
5 | 18 | ### Minor Changes |
6 | 19 |
|
7 | 20 | - [#389](https://github.com/cloudflare/ai/pull/389) [`a4b756e`](https://github.com/cloudflare/ai/commit/a4b756ebce97c4fa3e376293b0100d7784a15654) Thanks [@vaibhavshn](https://github.com/vaibhavshn)! - Add `@cloudflare/tanstack-ai` — adapters for using TanStack AI with Cloudflare Workers AI and AI Gateway. |
8 | 21 |
|
9 | | - ### Workers AI adapters |
10 | | - |
11 | | - All Workers AI adapters support four configuration modes: plain binding (`env.AI`), plain REST (account ID + API key), AI Gateway binding (`env.AI.gateway(id)`), and AI Gateway REST (account ID + gateway ID). |
12 | | - - **Chat** (`createWorkersAiChat`) — Streaming chat completions via the OpenAI-compatible API. Includes tool calling with full round-trip support, structured output via `json_schema`, and reasoning text streaming (`STEP_STARTED`/`STEP_FINISHED` AG-UI events) for models like QwQ, DeepSeek R1, and Kimi K2.5. A custom fetch shim translates OpenAI SDK calls to `env.AI.run()` for binding mode, with a stream transformer that handles both Workers AI native format and OpenAI-compatible format. |
13 | | - - **Image generation** (`createWorkersAiImage`) — Stable Diffusion and other text-to-image models. |
14 | | - - **Transcription** (`createWorkersAiTranscription`) — Speech-to-text via Whisper and Deepgram Nova-3. |
15 | | - - **Text-to-speech** (`createWorkersAiTts`) — Audio generation via Deepgram Aura-1. |
16 | | - - **Summarization** (`createWorkersAiSummarize`) — Text summarization via BART-large-CNN. |
17 | | - - **Embeddings** (`createWorkersAiEmbedding`) — Text embeddings (implemented but not yet exported, pending TanStack AI's `BaseEmbeddingAdapter`). |
18 | | - |
19 | | - ### AI Gateway adapters (third-party providers) |
20 | | - |
21 | | - Route requests through Cloudflare AI Gateway for caching, rate limiting, and unified billing. Each adapter injects a custom `fetch` (or `httpOptions` for Gemini) that handles both binding and credential-based gateway configurations. |
22 | | - - **OpenAI** — Chat, summarize, image, transcription, TTS, video (`createOpenAi*`) |
23 | | - - **Anthropic** — Chat, summarize (`createAnthropic*`) |
24 | | - - **Gemini** — Chat, summarize, image, TTS (`createGemini*`). Credentials-only (Google GenAI SDK lacks custom fetch support). |
25 | | - - **Grok** — Chat, summarize, image (`createGrok*`) |
26 | | - - **OpenRouter** — Chat, summarize, image (`createOpenRouter*`). Accepts any model string. |
27 | | - |
28 | | - ### Utilities |
29 | | - - `createGatewayFetch` — Shared fetch factory that routes requests through AI Gateway (binding or REST), with support for cache control headers (`skipCache`, `cacheTtl`, `customCacheKey`, `metadata`). |
30 | | - - `createWorkersAiBindingFetch` — Fetch shim that makes `env.AI` look like an OpenAI endpoint, including stream transformation and tool call ID sanitization for the binding's strict `[a-zA-Z0-9]{9}` validation. |
31 | | - - Config detection helpers (`isDirectBindingConfig`, `isDirectCredentialsConfig`, `isGatewayConfig`) using structural typing to discriminate `env.AI` from `env.AI.gateway(id)`. |
32 | | - - Shared binary utilities for normalizing Workers AI responses (Uint8Array, ArrayBuffer, ReadableStream, JSON wrapper) to base64. |
33 | | - |
34 | | - ### Robustness |
35 | | - - Premature stream termination detection — if Workers AI truncates a response or the connection drops (no `finish_reason`), the adapter emits proper closing events so consumers don't hang. |
36 | | - - Graceful non-streaming fallback — if a model returns a complete response despite `stream: true`, the binding shim wraps it into a valid response. |
37 | | - - Deepgram Nova-3 transcription uses raw binary audio via REST (not JSON), automatically detected by model name. |
38 | | - |
39 | | - ### Testing |
40 | | - - Comprehensive unit tests (186 tests) covering all adapters, config modes, stream transformation, message building, tool calling, reasoning events, premature termination, and public API surface. |
41 | | - - E2E integration tests against real Workers AI APIs (both binding and REST paths) across 12 chat models + 4 transcription models + image/TTS/summarize, validating chat, multi-turn, tool calling, tool round-trips, structured output, reasoning, and all non-chat capabilities. |
42 | | - - Tree-shakeable package exports with per-adapter entry points for ESM and CJS. |
| 22 | + ### Workers AI adapters |
| 23 | + |
| 24 | + All Workers AI adapters support four configuration modes: plain binding (`env.AI`), plain REST (account ID + API key), AI Gateway binding (`env.AI.gateway(id)`), and AI Gateway REST (account ID + gateway ID). |
| 25 | + |
| 26 | + - **Chat** (`createWorkersAiChat`) — Streaming chat completions via the OpenAI-compatible API. Includes tool calling with full round-trip support, structured output via `json_schema`, and reasoning text streaming (`STEP_STARTED`/`STEP_FINISHED` AG-UI events) for models like QwQ, DeepSeek R1, and Kimi K2.5. A custom fetch shim translates OpenAI SDK calls to `env.AI.run()` for binding mode, with a stream transformer that handles both Workers AI native format and OpenAI-compatible format. |
| 27 | + - **Image generation** (`createWorkersAiImage`) — Stable Diffusion and other text-to-image models. |
| 28 | + - **Transcription** (`createWorkersAiTranscription`) — Speech-to-text via Whisper and Deepgram Nova-3. |
| 29 | + - **Text-to-speech** (`createWorkersAiTts`) — Audio generation via Deepgram Aura-1. |
| 30 | + - **Summarization** (`createWorkersAiSummarize`) — Text summarization via BART-large-CNN. |
| 31 | + - **Embeddings** (`createWorkersAiEmbedding`) — Text embeddings (implemented but not yet exported, pending TanStack AI's `BaseEmbeddingAdapter`). |
| 32 | + |
| 33 | + ### AI Gateway adapters (third-party providers) |
| 34 | + |
| 35 | + Route requests through Cloudflare AI Gateway for caching, rate limiting, and unified billing. Each adapter injects a custom `fetch` (or `httpOptions` for Gemini) that handles both binding and credential-based gateway configurations. |
| 36 | + |
| 37 | + - **OpenAI** — Chat, summarize, image, transcription, TTS, video (`createOpenAi*`) |
| 38 | + - **Anthropic** — Chat, summarize (`createAnthropic*`) |
| 39 | + - **Gemini** — Chat, summarize, image, TTS (`createGemini*`). Credentials-only (Google GenAI SDK lacks custom fetch support). |
| 40 | + - **Grok** — Chat, summarize, image (`createGrok*`) |
| 41 | + - **OpenRouter** — Chat, summarize, image (`createOpenRouter*`). Accepts any model string. |
| 42 | + |
| 43 | + ### Utilities |
| 44 | + |
| 45 | + - `createGatewayFetch` — Shared fetch factory that routes requests through AI Gateway (binding or REST), with support for cache control headers (`skipCache`, `cacheTtl`, `customCacheKey`, `metadata`). |
| 46 | + - `createWorkersAiBindingFetch` — Fetch shim that makes `env.AI` look like an OpenAI endpoint, including stream transformation and tool call ID sanitization for the binding's strict `[a-zA-Z0-9]{9}` validation. |
| 47 | + - Config detection helpers (`isDirectBindingConfig`, `isDirectCredentialsConfig`, `isGatewayConfig`) using structural typing to discriminate `env.AI` from `env.AI.gateway(id)`. |
| 48 | + - Shared binary utilities for normalizing Workers AI responses (Uint8Array, ArrayBuffer, ReadableStream, JSON wrapper) to base64. |
| 49 | + |
| 50 | + ### Robustness |
| 51 | + |
| 52 | + - Premature stream termination detection — if Workers AI truncates a response or the connection drops (no `finish_reason`), the adapter emits proper closing events so consumers don't hang. |
| 53 | + - Graceful non-streaming fallback — if a model returns a complete response despite `stream: true`, the binding shim wraps it into a valid response. |
| 54 | + - Deepgram Nova-3 transcription uses raw binary audio via REST (not JSON), automatically detected by model name. |
| 55 | + |
| 56 | + ### Testing |
| 57 | + |
| 58 | + - Comprehensive unit tests (186 tests) covering all adapters, config modes, stream transformation, message building, tool calling, reasoning events, premature termination, and public API surface. |
| 59 | + - E2E integration tests against real Workers AI APIs (both binding and REST paths) across 12 chat models + 4 transcription models + image/TTS/summarize, validating chat, multi-turn, tool calling, tool round-trips, structured output, reasoning, and all non-chat capabilities. |
| 60 | + - Tree-shakeable package exports with per-adapter entry points for ESM and CJS. |
0 commit comments