@amjadiqbal/tanstack-ai-sdk-bridge 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-10-23
+
+### Fixed
+
+- `aiSdkSpeech`: the result's `format` and `contentType` now come from what the provider returned (its `content-type` header, else the audio bytes), then the requested format, else `unknown`. Before, it reported `mp3` whenever no format was requested.
+
+### Added
+
+- `aiSdkImage`: `modelOptions.mask` is sent to AI SDK v3/v4 image models (it was never sent before).
+
+### Documentation
+
+- README states exactly which activities can be aborted (not `embed()`), what `outputSchema` does in the bridge (one non-streaming call without tools, JSON parsing, error cases; `chat()` validates), how `dimensions` behaves on v2/v3 embedding models, which transcription options are not sent, how speech reports its format, the image options and defaults, why `@ai-sdk/provider` is a dependency, and the `@tanstack/ai/adapter-internals` import.
+- Removed the untested `deepgram` keyword.
+
 ## [0.1.0] - 2026-10-23
 
 ### Added

package/README.md

@@ -27,10 +27,10 @@ const stream = chat({
 })
 ```
 
-- **Text**: streaming chat, tool calls (TanStack's agent loop runs your tools), reasoning, structured output (`outputSchema`), token usage, abort.
+- **Text**: streaming chat, tool calls (TanStack's agent loop runs your tools), reasoning, structured output (`outputSchema`), token usage, abort (see [Abort](#abort)).
 - **Embeddings, transcription, speech, image generation, rerank**: one adapter function each.
 - **AI SDK 5, 6 and 7 providers**: provider spec v2, v3 and v4 are all read.
-- **No extra runtime code from AI SDK**: only the provider package you already use, plus `@ai-sdk/provider` types. No `ai` package needed.
+- **No AI SDK runtime code**: the built package imports only `@tanstack/ai`. `@ai-sdk/provider` is a dependency because the published type declarations use its model types; nothing from it runs. No `ai` package needed.
 
 ## Install
 
@@ -112,7 +112,13 @@ const product = await chat({
 // product: { name: string; price: number }
 ```
 
-The bridge asks the model for JSON with the schema (AI SDK `responseFormat: { type: 'json', schema }`) and TanStack AI validates the result. A JSON answer wrapped in a Markdown code fence is also accepted.
+What the bridge does for `outputSchema`, exactly:
+
+- After the agent loop, TanStack AI calls the adapter's `structuredOutput()`. The bridge makes **one non-streaming** `doGenerate` call with the conversation, **without tools**, and `responseFormat: { type: 'json', schema }` (the JSON Schema TanStack AI made from your schema). Whether the provider enforces the schema depends on the provider.
+- It joins the text parts of the answer and parses them as JSON. An answer wrapped in a Markdown code fence is accepted.
+- It throws `Structured output generation failed: ...` (original error as `cause`) when the answer was cut off at the token limit, when the text is not JSON, or when the provider call fails.
+- The bridge does not check the data against the schema; `chat()` does that with your schema after the bridge returns.
+- `structuredOutputStream` and combined tools-plus-schema in one request are not implemented, so TanStack AI uses its non-streaming path.
 
 ### Reasoning
 
@@ -141,7 +147,7 @@ const { embeddings } = await embed({
 })
 ```
 
-Large inputs are split by the model's `maxEmbeddingsPerCall`. `dimensions` works with AI SDK 7 models; older ones take it through `modelOptions.providerOptions`.
+Large inputs are split by the model's `maxEmbeddingsPerCall`. `dimensions` is sent to AI SDK 7 (spec v4) embedding models. On spec v2/v3 models the bridge throws if `dimensions` is set, because their spec has no such field: leave it unset and pass the provider's own option instead, for example `modelOptions: { providerOptions: { openai: { dimensions: 512 } } }`.
 
 ### Transcription, speech, image, rerank
 
@@ -168,8 +174,24 @@ await rerank({ adapter: aiSdkRerank(cohere.reranking('rerank-v3.5')), query: 're
 | `generateImage()` | `aiSdkImage(model)` | `ImageModel` | v2, v3, v4 |
 | `rerank()` | `aiSdkRerank(model)` | `RerankingModel` | v3, v4 |
 
+Activity-specific `modelOptions`, on top of `providerOptions` and `headers`:
+
+| Adapter | `modelOptions` | Notes |
+|---|---|---|
+| `aiSdkTranscription` | `mediaType` | Media type of the audio when it can't be read from a `Blob`/`File` type or a data URL. Default `audio/mpeg`. `language`, `prompt` and `responseFormat` are not sent (the AI SDK spec has no such fields); the result has `text`, plus `segments`, `language` and `duration` when the provider returns them. An `http(s)` URL as `audio` is downloaded with the global `fetch`, not the provider's `fetch`. |
+| `aiSdkSpeech` | `instructions`, `language` | Sent as the AI SDK `instructions` and `language` call options. The result's `format` and `contentType` come from the provider's `content-type` header, else from the audio bytes (MP3, WAV, Ogg, FLAC, AAC), else the `format` you asked for, else `unknown`. |
+| `aiSdkImage` | `aspectRatio`, `seed`, `mask` | Sent as the AI SDK call options. `mask` is an AI SDK image file (`{ type: 'file', mediaType, data }` or `{ type: 'url', url }`). Image parts in the prompt become input `files`. Input images and masks need a spec v3/v4 model; v2 models throw. When the model does not report `maxImagesPerCall`, one image is requested per call (the AI SDK's own default) until `numberOfImages` is reached. |
+
 Every function takes an optional second argument `{ name }`, the adapter name TanStack AI shows in devtools and usage. It defaults to the provider id before the first dot (`deepseek.chat` becomes `deepseek`).
 
+### Abort
+
+| Activity | How to cancel | Passed to the AI SDK model |
+|---|---|---|
+| `chat()` | `abortController` (or the `request` signal) | yes: `abortSignal`, and the stream is cancelled |
+| `generateTranscription()`, `generateSpeech()`, `generateImage()`, `rerank()` | `abortSignal` | yes |
+| `embed()` | none: TanStack AI's `embed()` takes no signal | no |
+
 ## Migrating from the Vercel AI SDK
 
 TanStack's own [migration guide](https://tanstack.com/ai/latest/docs/migration/migration-from-vercel-ai) swaps your provider packages for TanStack adapters. With the bridge you can skip that step, and keep providers that have no TanStack adapter:
@@ -215,7 +237,9 @@ Everything below ran on 2026-10-23 with `@tanstack/ai` 1.0.0. **No live provider
 - **Reasoning signatures** are not sent back, so providers that need signed thinking blocks in later turns (Anthropic extended thinking with tools) receive the reasoning as plain text or drop it.
 - `chat({ wrapFetch })` is not applied; pass a custom `fetch` to the provider factory (`createDeepSeek({ fetch })`).
 - Provider file handles (`{ type: 'file' }` sources) are rejected; send images and documents as data or URLs.
-- Transcription `language` and `prompt` have no AI SDK equivalent; pass them in `modelOptions.providerOptions`.
+- Transcription `language`, `prompt` and `responseFormat` are not sent; see the options table.
+- Embeddings cannot be aborted (TanStack AI's `embed()` has no signal).
+- **TanStack AI internals:** like TanStack's own adapters, the bridge imports helpers (`transformMessagesForReplay`, `tanstackMetadata`, `toRunErrorPayload`) from `@tanstack/ai/adapter-internals`, the subpath TanStack's [community adapter guide](https://tanstack.com/ai/latest/docs/community-adapters/guide) points adapters to. It is not covered by the same stability promise as the main entry. Tested with `@tanstack/ai` 1.0.0; the peer range is `^1.0.0`. If a 1.x release breaks it, please open an issue.
 - AI SDK reranking models report no token usage, so `rerank()` usage is zero.
 - Video, audio generation and realtime models are not bridged yet.
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AdapterYieldChunk, EmbeddingOptions, EmbeddingResult, ImageGenerationOptions, ImageGenerationResult, ReasoningLevel, RerankAdapterResult, RerankOptions, TTSOptions, TTSResult, TextOptions, TranscriptionOptions, TranscriptionResult } from "@tanstack/ai";
 import { BaseEmbeddingAdapter, BaseImageAdapter, BaseRerankAdapter, BaseTTSAdapter, BaseTextAdapter, BaseTranscriptionAdapter, StructuredOutputOptions, StructuredOutputResult } from "@tanstack/ai/adapters";
-import { EmbeddingModelV2, EmbeddingModelV3, EmbeddingModelV4, ImageModelV2, ImageModelV3, ImageModelV4, LanguageModelV2, LanguageModelV3, LanguageModelV4, RerankingModelV3, RerankingModelV4, SpeechModelV2, SpeechModelV3, SpeechModelV4, TranscriptionModelV2, TranscriptionModelV3, TranscriptionModelV4 } from "@ai-sdk/provider";
+import { EmbeddingModelV2, EmbeddingModelV3, EmbeddingModelV4, ImageModelV2, ImageModelV3, ImageModelV4, ImageModelV4File, LanguageModelV2, LanguageModelV3, LanguageModelV4, RerankingModelV3, RerankingModelV4, SpeechModelV2, SpeechModelV3, SpeechModelV4, TranscriptionModelV2, TranscriptionModelV3, TranscriptionModelV4 } from "@ai-sdk/provider";
 /** AI SDK provider spec versions this package reads. */
 type SpecVersion = 'v2' | 'v3' | 'v4';
 /** Options every bridge adapter takes besides the model. */
@@ -45,7 +45,10 @@ type AiSdkImageModel = ImageModelV2 | ImageModelV3 | ImageModelV4;
 interface AiSdkImageModelOptions extends AiSdkCallOptions {
   /** Aspect ratio such as `16:9`, for models that take one instead of a size. */
   aspectRatio?: `${number}:${number}`;
+  /** Seed, for models that take one. */
   seed?: number;
+  /** Mask for inpainting (AI SDK v3/v4 image models that support masks), as an AI SDK image file. */
+  mask?: ImageModelV4File;
 }
 /**
  * TanStack AI image adapter around an AI SDK image model.
@@ -98,7 +101,11 @@ interface AiSdkSpeechModelOptions extends AiSdkCallOptions {
   /** Language of the text, e.g. `en`. */
   language?: string;
 }
-/** TanStack AI text-to-speech adapter around an AI SDK speech model. */
+/**
+ * TanStack AI text-to-speech adapter around an AI SDK speech model.
+ * `format` in the result is what the provider returned (content-type header or audio bytes),
+ * falling back to the requested format, else `unknown`.
+ */
 export declare class AiSdkSpeechAdapter<TModel extends string = string> extends BaseTTSAdapter<TModel, AiSdkSpeechModelOptions> {
   readonly name: string;
   readonly speechModel: AiSdkSpeechModel;
@@ -177,7 +184,9 @@ interface AiSdkTranscriptionModelOptions extends AiSdkCallOptions {
 }
 /**
  * TanStack AI transcription adapter around an AI SDK transcription model.
- * `language` and `prompt` have no AI SDK equivalent: pass them in `modelOptions.providerOptions`.
+ * `language`, `prompt` and `responseFormat` have no AI SDK equivalent and are not sent: pass the provider's own
+ * options in `modelOptions.providerOptions`. The result always has `text`, plus `segments`, `language` and `duration`
+ * when the provider returns them. An `http(s)` URL as `audio` is downloaded with the global `fetch`, not the provider's.
  */
 export declare class AiSdkTranscriptionAdapter<TModel extends string = string> extends BaseTranscriptionAdapter<TModel, AiSdkTranscriptionModelOptions> {
   readonly name: string;

package/dist/index.js

@@ -177,6 +177,7 @@ var AiSdkImageAdapter = class extends BaseImageAdapter {
 		const wanted = options.numberOfImages ?? 1;
 		try {
 			const { text, files } = this.promptOf(options.prompt);
+			if (modelOptions?.mask && this.specificationVersion === "v2") throw new Error(`${this.name}: a mask needs an AI SDK v3 or v4 image model`);
 			const maxSetting = this.imageModel.maxImagesPerCall;
 			const max = (typeof maxSetting === "function" ? await maxSetting({ modelId: this.imageModel.modelId }) : maxSetting) ?? 1;
 			logger.request(`activity=image provider=${this.name} model=${model} n=${wanted} size=${size ?? "default"}`, {
@@ -196,7 +197,7 @@ var AiSdkImageAdapter = class extends BaseImageAdapter {
 					aspectRatio: modelOptions?.aspectRatio,
 					seed: modelOptions?.seed,
 					files: files.length > 0 ? files : void 0,
-					mask: void 0,
+					mask: modelOptions?.mask,
 					providerOptions: modelOptions?.providerOptions ?? {},
 					...modelOptions?.headers && { headers: modelOptions.headers },
 					...abortSignal && { abortSignal }
@@ -306,7 +307,43 @@ const CONTENT_TYPES = {
 	wav: "audio/wav",
 	pcm: "audio/pcm"
 };
-/** TanStack AI text-to-speech adapter around an AI SDK speech model. */
+const FORMATS_BY_TYPE = {
+	"audio/mpeg": "mp3",
+	"audio/mp3": "mp3",
+	"audio/wav": "wav",
+	"audio/x-wav": "wav",
+	"audio/wave": "wav",
+	"audio/opus": "opus",
+	"audio/ogg": "opus",
+	"audio/aac": "aac",
+	"audio/flac": "flac",
+	"audio/x-flac": "flac",
+	"audio/pcm": "pcm",
+	"audio/l16": "pcm"
+};
+function headerValue(headers, name) {
+	if (!headers || typeof headers !== "object") return void 0;
+	for (const [key, value] of Object.entries(headers)) if (key.toLowerCase() === name && typeof value === "string") return value;
+}
+function formatFromContentType(type) {
+	return type ? FORMATS_BY_TYPE[type.toLowerCase()] : void 0;
+}
+/** Recognises MP3, WAV, Ogg/Opus, FLAC and ADTS AAC from their first bytes. */
+function formatFromBytes(bytes) {
+	const ascii = (start, text) => [...text].every((char, i) => bytes[start + i] === char.charCodeAt(0));
+	if (ascii(0, "RIFF") && ascii(8, "WAVE")) return "wav";
+	if (ascii(0, "OggS")) return "opus";
+	if (ascii(0, "fLaC")) return "flac";
+	if (ascii(0, "ID3")) return "mp3";
+	const b0 = bytes[0] ?? 0;
+	const b1 = bytes[1] ?? 0;
+	if (b0 === 255 && (b1 & 224) === 224) return (b1 & 6) === 0 ? "aac" : "mp3";
+}
+/**
+* TanStack AI text-to-speech adapter around an AI SDK speech model.
+* `format` in the result is what the provider returned (content-type header or audio bytes),
+* falling back to the requested format, else `unknown`.
+*/
 var AiSdkSpeechAdapter = class extends BaseTTSAdapter {
 	name;
 	speechModel;
@@ -333,15 +370,16 @@ var AiSdkSpeechAdapter = class extends BaseTTSAdapter {
 				...modelOptions?.language !== void 0 && { language: modelOptions.language },
 				...callExtras(modelOptions, abortSignal)
 			});
+			const bytes = typeof result.audio === "string" ? base64ToBytes(result.audio) : result.audio;
 			const audio = typeof result.audio === "string" ? result.audio : bytesToBase64(result.audio);
-			const outputFormat = format ?? "mp3";
-			const headerType = (result.response?.headers)?.["content-type"];
+			const headerType = headerValue(result.response?.headers, "content-type")?.split(";")[0]?.trim();
+			const outputFormat = formatFromContentType(headerType) ?? formatFromBytes(bytes) ?? format ?? "unknown";
 			return {
 				id: randomId(this.name),
 				model: result.response?.modelId ?? model,
 				audio,
 				format: outputFormat,
-				contentType: headerType?.split(";")[0] || CONTENT_TYPES[outputFormat] || "application/octet-stream"
+				contentType: headerType || CONTENT_TYPES[outputFormat] || "application/octet-stream"
 			};
 		} catch (error) {
 			logger.errors(`${this.name}.generateSpeech fatal`, {
@@ -1050,7 +1088,9 @@ async function toAudio(audio, fallbackType, signal) {
 }
 /**
 * TanStack AI transcription adapter around an AI SDK transcription model.
-* `language` and `prompt` have no AI SDK equivalent: pass them in `modelOptions.providerOptions`.
+* `language`, `prompt` and `responseFormat` have no AI SDK equivalent and are not sent: pass the provider's own
+* options in `modelOptions.providerOptions`. The result always has `text`, plus `segments`, `language` and `duration`
+* when the provider returns them. An `http(s)` URL as `audio` is downloaded with the global `fetch`, not the provider's.
 */
 var AiSdkTranscriptionAdapter = class extends BaseTranscriptionAdapter {
 	name;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amjadiqbal/tanstack-ai-sdk-bridge",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Use any Vercel AI SDK provider (@ai-sdk/* and community providers) as a TanStack AI adapter: streaming chat with tools, reasoning and structured output, plus embeddings, transcription, speech, image generation and rerank. Supports AI SDK provider spec v2, v3 and v4.",
   "keywords": [
     "tanstack",
@@ -13,7 +13,6 @@
     "cerebras",
     "togetherai",
     "fireworks",
-    "deepgram",
     "embeddings",
     "tool-calling",
     "migration"