@tanstack/ai-byteplus 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @tanstack/ai-byteplus
+
+BytePlus ModelArk adapter for TanStack AI — Seed chat models, Seedance video
+generation, Seedream image generation, and Seed Speech text-to-speech and
+transcription.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-byteplus
+# or
+pnpm add @tanstack/ai-byteplus
+# or
+yarn add @tanstack/ai-byteplus
+```
+
+## Setup
+
+BytePlus splits its models across two products with **two different API keys**:
+
+```bash
+# Ark (ModelArk): chat, Seedance video, Seedream image
+export ARK_API_KEY="..."
+
+# Seed Speech: text-to-speech and transcription — a separate product key
+export BYTEPLUS_VOICE_API_KEY="..."
+```
+
+Ark keys are region-isolated. The default base URL is the Asia-Pacific
+south-east endpoint (`https://ark.ap-southeast.bytepluses.com/api/v3`); per the
+BytePlus docs the EU endpoint serves chat and image only (docs-derived — only
+the ap-southeast host was exercised live).
+
+## Why there's no Volcengine SDK dependency
+
+This package does **not** depend on `@volcengine/ark-runtime` (or any other
+first-party BytePlus/Volcengine SDK). That is deliberate:
+
+- **Chat doesn't need one.** Ark's `/chat/completions` is OpenAI-compatible, so
+  the chat adapter rides the `openai` SDK through `@tanstack/openai-base` — the
+  same path `@tanstack/ai-grok` and `@tanstack/ai-groq` take, with identical
+  dependencies. That reuses the shared streaming, tool-calling and
+  structured-output machinery instead of forking it per provider.
+- **Nothing else is OpenAI-shaped anyway.** Seedance video, Seedream image and
+  Seed Speech are bespoke endpoints on two different hosts with two different
+  auth headers. An SDK would not spare us the wire types; it would add a second
+  dependency that still had to be translated at the boundary.
+
+The cost is that the non-chat wire types are hand-written and pinned by tests
+rather than generated. That is a considered trade, not an oversight — see
+`src/video/wire-types.ts`, `src/image/wire-types.ts` and
+`src/audio/wire-types.ts`, each of which records how its shape was verified.
+
+## Usage
+
+### Chat
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { byteplusText } from '@tanstack/ai-byteplus'
+
+// The adapter carries the model — there is no separate `model` option.
+const adapter = byteplusText('seed-2-0-lite-260428')
+
+const text = await chat({
+  adapter,
+  messages: [{ role: 'user', content: 'Explain diffusion models briefly' }],
+  stream: false,
+})
+
+console.log(text)
+```
+
+Drop `stream: false` to get the default streaming form, which yields
+`StreamChunk`s you can iterate with `for await`.
+
+Seed models reason by default. Reasoning arrives as a separate stream of
+`reasoning_content` deltas and is surfaced as reasoning content, not answer
+text. Pass `thinking: { type: 'disabled' }` in provider options to turn it off.
+
+### Video (Seedance)
+
+Seedance is an async task API, so `generateVideo()` only opens the job and
+returns its `jobId`. Poll `getVideoJobStatus()` until the job settles — the
+video URL arrives with the terminal status.
+
+```typescript
+import { generateVideo, getVideoJobStatus } from '@tanstack/ai'
+import { byteplusVideo } from '@tanstack/ai-byteplus'
+
+const adapter = byteplusVideo('seedance-1-5-pro-251215')
+
+const { jobId } = await generateVideo({
+  adapter,
+  prompt: 'a guitar being played in a store',
+  size: '16:9_720p',
+  duration: 5,
+})
+
+let status = await getVideoJobStatus({ adapter, jobId })
+while (status.status === 'pending' || status.status === 'processing') {
+  await new Promise((resolve) => setTimeout(resolve, 5000))
+  status = await getVideoJobStatus({ adapter, jobId })
+}
+
+console.log(status.status === 'completed' ? status.url : status.error)
+```
+
+To let the core drive the whole lifecycle instead, pass `stream: true` and hand
+the resulting chunk stream to your transport:
+
+```typescript
+import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai'
+import { byteplusVideo } from '@tanstack/ai-byteplus'
+
+const stream = generateVideo({
+  adapter: byteplusVideo('seedance-1-5-pro-251215'),
+  prompt: 'a guitar being played in a store',
+  stream: true,
+  pollingInterval: 5000,
+})
+
+return toServerSentEventsResponse(stream)
+```
+
+**Generated video URLs expire after 24 hours** (the task record itself is kept
+for 7 days), so download anything you need to keep.
+
+### Image (Seedream)
+
+```typescript
+import { generateImage } from '@tanstack/ai'
+import { byteplusImage } from '@tanstack/ai-byteplus'
+
+const result = await generateImage({
+  adapter: byteplusImage('seedream-4-0-250828'),
+  prompt: 'a guitar being played in a store',
+  size: '2K',
+  modelOptions: { watermark: false },
+})
+
+console.log(result.images[0]?.url)
+```
+
+`size` takes either a token (`1K`, `2K`, `4K`) or explicit pixels
+(`2048x2048`) — never a mix. Pass image parts in the `prompt` array to edit or
+condition on existing images (up to 14 references, 10 on
+`dola-seedream-5-0-pro-260628`).
+
+Two behaviors surprise people:
+
+- **`watermark` defaults to `true`.** BytePlus stamps "AI generated" into the
+  bottom-right corner unless you pass `watermark: false`. The adapter never
+  sets it implicitly, so the provider default applies.
+- **`numberOfImages` is an upper bound, not a count.** Seedream has no `n`
+  parameter; asking for more than one image maps to its group-image mode
+  (`sequential_image_generation: 'auto'` with `max_images`), where the model
+  decides how many images the prompt actually warrants. A request for four can
+  return fewer, and the adapter logs a warning when it does.
+
+Result URLs expire after 24 hours; pass `response_format: 'b64_json'` in
+`modelOptions` to get bytes inline instead.
+
+## Supported models
+
+- **Chat** — `dola-seed-2-1-turbo-260628`, the `seed-2-0-*` family,
+  `seed-1-8-251228`, the `seed-1-6-*` family, plus `glm-*`, `deepseek-*` and
+  `gpt-oss-120b-250805`.
+- **Video** — `dreamina-seedance-2-0-260128` (and `-fast-`/`-mini-`),
+  `seedance-1-5-pro-251215`, `seedance-1-0-pro-250528`,
+  `seedance-1-0-pro-fast-251015`.
+- **Image** — `dola-seedream-5-0-pro-260628`, `seedream-5-0-260128`,
+  `seedream-5-0-lite-260128`, `seedream-4-5-251128`, `seedream-4-0-250828`.
+- **Speech** — `seed-audio-1.0` (TTS) and `seed-asr` (transcription).
+
+BytePlus retires model ids aggressively, so only dated ids that were verified
+live against the API are exported. (The two Seed Speech ids are the exception:
+`seed-audio-1.0` is undated, `seed-asr` is a synthetic id for an
+endpoint-addressed API that takes no `model` field, and neither could be
+verified live pending a Seed Speech key.) `BYTEPLUS_CHAT_MODELS`,
+`BYTEPLUS_VIDEO_MODELS`, `BYTEPLUS_IMAGE_MODELS`, `BYTEPLUS_TTS_MODELS` and
+`BYTEPLUS_TRANSCRIPTION_MODELS` are the authoritative lists.
+
+## Seedance: direct vs. via fal
+
+Seedance is also reachable through `@tanstack/ai-fal`, which proxies it along
+with hundreds of other models. This package talks to BytePlus directly, which
+means BytePlus billing and rate limits, the first-class Seedance request fields
+(`camera_fixed`, `generate_audio`, `watermark`, reference-image roles, …), and
+model ids in BytePlus's own naming. Use whichever fits your account; there is
+no reason to install both for Seedance alone.
+
+## Seed Speech needs its own key
+
+The TTS and transcription adapters do **not** talk to Ark. They use
+`voice.ap-southeast-1.bytepluses.com` with an `X-Api-Key` header and the
+Seed Speech product key (`BYTEPLUS_VOICE_API_KEY`). Passing an Ark key there
+fails with `45000010 Invalid X-Api-Key`.
+
+## License
+
+MIT

package/dist/esm/adapters/image.d.ts

@@ -0,0 +1,89 @@
+import { BaseImageAdapter } from '@tanstack/ai/adapters';
+import { ImageGenerationOptions, ImageGenerationResult } from '@tanstack/ai';
+import { BytePlusImageModelInputModalitiesByName, BytePlusImageModelProviderOptionsByName, BytePlusImageProviderOptions } from '../image/image-provider-options.js';
+import { BytePlusImageModel, BytePlusImageModelSizeByName } from '../model-meta.js';
+import { BytePlusArkConfig } from '../utils/client.js';
+/**
+ * Configuration for the BytePlus Seedream image adapter.
+ */
+export interface BytePlusImageConfig extends BytePlusArkConfig {
+}
+/**
+ * BytePlus Seedream image generation adapter.
+ *
+ * Drives Ark's `POST /images/generations` endpoint directly rather than
+ * through the OpenAI SDK: the endpoint takes size tokens (`2K`) as well as
+ * pixel sizes, has no `n` parameter, and carries reference images for editing
+ * in the generation request instead of a separate edits endpoint.
+ *
+ * Features:
+ * - Text-to-image and image-conditioned generation (editing, multi-reference)
+ *   from a single call, with per-model reference-count limits enforced.
+ * - Size validation across both accepted forms.
+ * - `numberOfImages` mapped onto Seedream's group-image mode.
+ *
+ * @example
+ * ```typescript
+ * const adapter = byteplusImage('seedream-4-0-250828')
+ * const result = await generateImage({
+ *   adapter,
+ *   prompt: 'A guitar in a sunlit workshop',
+ *   size: '2K',
+ *   modelOptions: { watermark: false },
+ * })
+ * ```
+ */
+export declare class BytePlusImageAdapter<TModel extends BytePlusImageModel> extends BaseImageAdapter<TModel, BytePlusImageProviderOptions, BytePlusImageModelProviderOptionsByName, BytePlusImageModelSizeByName, BytePlusImageModelInputModalitiesByName> {
+    readonly kind: "image";
+    readonly name: "byteplus";
+    /** Config with the Ark base URL resolved and trailing slashes trimmed. */
+    private readonly clientConfig;
+    constructor(model: TModel, config: BytePlusImageConfig);
+    generateImages(options: ImageGenerationOptions<BytePlusImageProviderOptions, BytePlusImageModelSizeByName[TModel]>): Promise<ImageGenerationResult>;
+    private transformResponse;
+}
+/**
+ * Creates a BytePlus Seedream image adapter with an explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @param model - The model name (e.g., 'seedream-4-0-250828')
+ * @param apiKey - Your BytePlus Ark API key
+ * @param config - Optional additional configuration
+ * @returns Configured BytePlus image adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * const adapter = createBytePlusImage('seedream-5-0-260128', 'ark-...')
+ *
+ * const result = await generateImage({
+ *   adapter,
+ *   prompt: 'A cute baby sea otter',
+ *   size: '2K',
+ * })
+ * ```
+ */
+export declare function createBytePlusImage<TModel extends BytePlusImageModel>(model: TModel, apiKey: string, config?: Omit<BytePlusImageConfig, 'apiKey'>): BytePlusImageAdapter<TModel>;
+/**
+ * Creates a BytePlus Seedream image adapter, reading `ARK_API_KEY` from the
+ * environment. Type resolution happens here at the call site.
+ *
+ * Note that Ark keys are region-isolated: a key issued for `ap-southeast`
+ * does not work against the EU host.
+ *
+ * @param model - The model name (e.g., 'seedream-4-0-250828')
+ * @param config - Optional configuration (excluding apiKey, auto-detected)
+ * @returns Configured BytePlus image adapter instance with resolved types
+ * @throws Error if ARK_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * const adapter = byteplusImage('seedream-4-0-250828')
+ *
+ * const result = await generateImage({
+ *   adapter,
+ *   prompt: 'A beautiful sunset over mountains',
+ *   modelOptions: { watermark: false },
+ * })
+ * ```
+ */
+export declare function byteplusImage<TModel extends BytePlusImageModel>(model: TModel, config?: Omit<BytePlusImageConfig, 'apiKey'>): BytePlusImageAdapter<TModel>;

package/dist/esm/adapters/image.js

@@ -0,0 +1,229 @@
+import { bytePlusArkError, bytePlusArkHeaders, bytePlusTimeoutSignal, describeBody, getBytePlusArkApiKeyFromEnv, readJsonBody, toHeaderRecord, withBytePlusArkDefaults } from "../utils/client.js";
+import { resolveBytePlusImageSize, resolveBytePlusSequentialImages, validateBytePlusImagePrompt, validateBytePlusReferenceImages } from "../image/image-provider-options.js";
+import { resolveMediaPrompt } from "@tanstack/ai";
+import { BaseImageAdapter } from "@tanstack/ai/adapters";
+import { toRunErrorPayload } from "@tanstack/ai/adapter-internals";
+import { generateId } from "@tanstack/ai-utils";
+//#region src/adapters/image.ts
+/**
+* Roles Seedream can honour. Every input image is a reference — there is no
+* inpainting mask, control-image or frame channel — so this is an allow-list
+* rather than a deny-list: a role added to the core union later (or a
+* video-oriented one like `start_frame`) fails loudly here instead of being
+* silently flattened into a plain reference.
+*/
+var SUPPORTED_INPUT_ROLES = /* @__PURE__ */ new Set(["reference", "character"]);
+/**
+* Converts a prompt image part to the string Seedream's `image` field takes:
+* URLs pass through (BytePlus fetches them server-side), data sources become
+* data URIs. BytePlus requires the format in `data:image/<format>;base64,` to
+* be lowercase, so the mime type is lowercased on the way out.
+*/
+function imagePartToImageRef(part) {
+	const { source } = part;
+	if (source.type === "url") return source.value;
+	if (source.value.startsWith("data:")) return source.value;
+	return `data:${source.mimeType.toLowerCase()};base64,${source.value}`;
+}
+/**
+* Renders provider error objects as `code: message` pairs for a log line or
+* an error message.
+*/
+function describeFailures(failures) {
+	return failures.map((failure) => [failure.code, failure.message].filter(Boolean).join(": ")).filter((text) => text.length > 0).join("; ");
+}
+/**
+* Maps Seedream's usage block onto `TokenUsage`.
+*
+* BytePlus bills per generated image and does not count input tokens, so
+* `promptTokens` is always 0 and `generated_images` is surfaced as
+* `unitsBilled` — the count the price is applied to.
+*/
+function buildBytePlusImageUsage(usage) {
+	if (!usage) return void 0;
+	const completionTokens = usage.output_tokens ?? 0;
+	return {
+		promptTokens: 0,
+		completionTokens,
+		totalTokens: usage.total_tokens ?? completionTokens,
+		...usage.generated_images !== void 0 && { unitsBilled: usage.generated_images }
+	};
+}
+/**
+* BytePlus Seedream image generation adapter.
+*
+* Drives Ark's `POST /images/generations` endpoint directly rather than
+* through the OpenAI SDK: the endpoint takes size tokens (`2K`) as well as
+* pixel sizes, has no `n` parameter, and carries reference images for editing
+* in the generation request instead of a separate edits endpoint.
+*
+* Features:
+* - Text-to-image and image-conditioned generation (editing, multi-reference)
+*   from a single call, with per-model reference-count limits enforced.
+* - Size validation across both accepted forms.
+* - `numberOfImages` mapped onto Seedream's group-image mode.
+*
+* @example
+* ```typescript
+* const adapter = byteplusImage('seedream-4-0-250828')
+* const result = await generateImage({
+*   adapter,
+*   prompt: 'A guitar in a sunlit workshop',
+*   size: '2K',
+*   modelOptions: { watermark: false },
+* })
+* ```
+*/
+var BytePlusImageAdapter = class extends BaseImageAdapter {
+	kind = "image";
+	name = "byteplus";
+	/** Config with the Ark base URL resolved and trailing slashes trimmed. */
+	clientConfig;
+	constructor(model, config) {
+		super(model, {});
+		this.clientConfig = withBytePlusArkDefaults(config);
+	}
+	async generateImages(options) {
+		const { numberOfImages, size, modelOptions, logger } = options;
+		const model = this.model;
+		const resolved = resolveMediaPrompt(options.prompt);
+		if (resolved.videos.length > 0 || resolved.audios.length > 0) throw new Error(`byteplus.generateImages does not support video / audio prompt parts on model ${model}.`);
+		const unsupportedRole = resolved.images.find((part) => part.metadata?.role !== void 0 && !SUPPORTED_INPUT_ROLES.has(part.metadata.role));
+		if (unsupportedRole) throw new Error(`byteplus: Seedream has no ${unsupportedRole.metadata?.role} input; it accepts reference images only (${[...SUPPORTED_INPUT_ROLES].join(", ")}).`);
+		validateBytePlusImagePrompt(model, resolved.text);
+		validateBytePlusReferenceImages(model, resolved.images.length);
+		const imageRefs = resolved.images.map(imagePartToImageRef);
+		const request = {
+			...imageRefs.length > 0 && { image: imageRefs },
+			...size !== void 0 && { size: resolveBytePlusImageSize(size) },
+			...resolveBytePlusSequentialImages(model, numberOfImages),
+			...modelOptions,
+			model,
+			prompt: resolved.text
+		};
+		try {
+			logger.request(`activity=image provider=${this.name} model=${model} size=${request.size ?? "default"} refs=${imageRefs.length}`, {
+				provider: this.name,
+				model
+			});
+			const fetchImpl = this.clientConfig.fetch ?? fetch;
+			const signal = bytePlusTimeoutSignal(this.clientConfig.timeout);
+			const response = await fetchImpl(`${this.clientConfig.baseURL}/images/generations`, {
+				method: "POST",
+				...signal && { signal },
+				headers: bytePlusArkHeaders(this.clientConfig.apiKey, toHeaderRecord(this.clientConfig.defaultHeaders)),
+				body: JSON.stringify(request)
+			});
+			const body = await readJsonBody(response);
+			if (!response.ok) throw bytePlusArkError(response.status, body, "image generation");
+			return this.transformResponse(body, logger, numberOfImages);
+		} catch (error) {
+			logger.errors(`${this.name}.generateImages fatal`, {
+				error: toRunErrorPayload(error, `${this.name}.generateImages failed`),
+				source: `${this.name}.generateImages`
+			});
+			throw error;
+		}
+	}
+	transformResponse(body, logger, numberOfImages) {
+		if (typeof body !== "object" || body === null) throw bytePlusArkError(200, body, "image generation returned a non-object body");
+		const payload = body;
+		const images = [];
+		const failures = [];
+		let unrecognized = 0;
+		for (const item of payload.data ?? []) if (item.b64_json) images.push({ b64Json: item.b64_json });
+		else if (item.url) images.push({ url: item.url });
+		else if (item.error) failures.push(item.error);
+		else unrecognized += 1;
+		if (payload.error) failures.push(payload.error);
+		if (unrecognized > 0) logger.errors(`${this.name}.generateImages: ${unrecognized} response item(s) matched none of b64_json / url / error — the response shape may have changed.`, {
+			source: `${this.name}.generateImages`,
+			provider: this.name,
+			model: this.model,
+			body
+		});
+		if (images.length === 0) {
+			const detail = describeFailures(failures) || (unrecognized > 0 ? `${unrecognized} unrecognized response item(s): ${describeBody(body) ?? ""}` : "");
+			throw new Error(`byteplus: image generation returned no images` + (detail ? `: ${detail}` : "."));
+		}
+		if (failures.length > 0) {
+			logger.errors(`${this.name}.generateImages dropped ${failures.length} failed image(s): ${describeFailures(failures)}`, {
+				source: `${this.name}.generateImages`,
+				provider: this.name,
+				model: this.model,
+				failures
+			});
+			logger.warn(`byteplus: ${failures.length} of ${failures.length + images.length} images failed to generate; returning ${images.length}.`, {
+				provider: this.name,
+				model: this.model
+			});
+		}
+		if (numberOfImages !== void 0 && images.length < numberOfImages) logger.warn(`byteplus: requested ${numberOfImages} images, received ${images.length}. Seedream has no exact count — sequential_image_generation.max_images is an upper bound and the model decides how many the prompt warrants.`, {
+			provider: this.name,
+			model: this.model
+		});
+		const usage = buildBytePlusImageUsage(payload.usage);
+		return {
+			id: generateId(this.name),
+			model: this.model,
+			images,
+			...usage ? { usage } : {}
+		};
+	}
+};
+/**
+* Creates a BytePlus Seedream image adapter with an explicit API key.
+* Type resolution happens here at the call site.
+*
+* @param model - The model name (e.g., 'seedream-4-0-250828')
+* @param apiKey - Your BytePlus Ark API key
+* @param config - Optional additional configuration
+* @returns Configured BytePlus image adapter instance with resolved types
+*
+* @example
+* ```typescript
+* const adapter = createBytePlusImage('seedream-5-0-260128', 'ark-...')
+*
+* const result = await generateImage({
+*   adapter,
+*   prompt: 'A cute baby sea otter',
+*   size: '2K',
+* })
+* ```
+*/
+function createBytePlusImage(model, apiKey, config) {
+	return new BytePlusImageAdapter(model, {
+		apiKey,
+		...config
+	});
+}
+/**
+* Creates a BytePlus Seedream image adapter, reading `ARK_API_KEY` from the
+* environment. Type resolution happens here at the call site.
+*
+* Note that Ark keys are region-isolated: a key issued for `ap-southeast`
+* does not work against the EU host.
+*
+* @param model - The model name (e.g., 'seedream-4-0-250828')
+* @param config - Optional configuration (excluding apiKey, auto-detected)
+* @returns Configured BytePlus image adapter instance with resolved types
+* @throws Error if ARK_API_KEY is not found in environment
+*
+* @example
+* ```typescript
+* const adapter = byteplusImage('seedream-4-0-250828')
+*
+* const result = await generateImage({
+*   adapter,
+*   prompt: 'A beautiful sunset over mountains',
+*   modelOptions: { watermark: false },
+* })
+* ```
+*/
+function byteplusImage(model, config) {
+	return createBytePlusImage(model, getBytePlusArkApiKeyFromEnv(), config);
+}
+//#endregion
+export { BytePlusImageAdapter, byteplusImage, createBytePlusImage };
+
+//# sourceMappingURL=image.js.map

package/dist/esm/adapters/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","names":[],"sources":["../../../src/adapters/image.ts"],"sourcesContent":["import { resolveMediaPrompt } from '@tanstack/ai'\nimport { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { toRunErrorPayload } from '@tanstack/ai/adapter-internals'\nimport { generateId } from '@tanstack/ai-utils'\nimport {\n  bytePlusArkError,\n  bytePlusArkHeaders,\n  bytePlusTimeoutSignal,\n  describeBody,\n  getBytePlusArkApiKeyFromEnv,\n  readJsonBody,\n  toHeaderRecord,\n  withBytePlusArkDefaults,\n} from '../utils/client'\nimport {\n  resolveBytePlusImageSize,\n  resolveBytePlusSequentialImages,\n  validateBytePlusImagePrompt,\n  validateBytePlusReferenceImages,\n} from '../image/image-provider-options'\nimport type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResult,\n  ImagePart,\n  MediaInputMetadata,\n  TokenUsage,\n} from '@tanstack/ai'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\nimport type {\n  BytePlusImageErrorObject,\n  BytePlusImageGenerationRequest,\n  BytePlusImageGenerationResponse,\n  BytePlusImageUsage,\n} from '../image/wire-types'\nimport type {\n  BytePlusImageModelInputModalitiesByName,\n  BytePlusImageModelProviderOptionsByName,\n  BytePlusImageProviderOptions,\n} from '../image/image-provider-options'\nimport type {\n  BytePlusImageModel,\n  BytePlusImageModelSizeByName,\n} from '../model-meta'\nimport type { BytePlusArkConfig } from '../utils/client'\n\n/**\n * Configuration for the BytePlus Seedream image adapter.\n */\nexport interface BytePlusImageConfig extends BytePlusArkConfig {}\n\n/**\n * Roles Seedream can honour. Every input image is a reference — there is no\n * inpainting mask, control-image or frame channel — so this is an allow-list\n * rather than a deny-list: a role added to the core union later (or a\n * video-oriented one like `start_frame`) fails loudly here instead of being\n * silently flattened into a plain reference.\n */\nconst SUPPORTED_INPUT_ROLES: ReadonlySet<string> = new Set([\n  'reference',\n  'character',\n])\n\n/**\n * Converts a prompt image part to the string Seedream's `image` field takes:\n * URLs pass through (BytePlus fetches them server-side), data sources become\n * data URIs. BytePlus requires the format in `data:image/<format>;base64,` to\n * be lowercase, so the mime type is lowercased on the way out.\n */\nfunction imagePartToImageRef(part: ImagePart<MediaInputMetadata>): string {\n  const { source } = part\n  if (source.type === 'url') return source.value\n  if (source.value.startsWith('data:')) return source.value\n  return `data:${source.mimeType.toLowerCase()};base64,${source.value}`\n}\n\n/**\n * Renders provider error objects as `code: message` pairs for a log line or\n * an error message.\n */\nfunction describeFailures(\n  failures: ReadonlyArray<BytePlusImageErrorObject>,\n): string {\n  return failures\n    .map((failure) =>\n      [failure.code, failure.message].filter(Boolean).join(': '),\n    )\n    .filter((text) => text.length > 0)\n    .join('; ')\n}\n\n/**\n * Maps Seedream's usage block onto `TokenUsage`.\n *\n * BytePlus bills per generated image and does not count input tokens, so\n * `promptTokens` is always 0 and `generated_images` is surfaced as\n * `unitsBilled` — the count the price is applied to.\n */\nfunction buildBytePlusImageUsage(\n  usage: BytePlusImageUsage | undefined,\n): TokenUsage | undefined {\n  if (!usage) return undefined\n\n  const completionTokens = usage.output_tokens ?? 0\n  return {\n    promptTokens: 0,\n    completionTokens,\n    totalTokens: usage.total_tokens ?? completionTokens,\n    ...(usage.generated_images !== undefined && {\n      unitsBilled: usage.generated_images,\n    }),\n  }\n}\n\n/**\n * BytePlus Seedream image generation adapter.\n *\n * Drives Ark's `POST /images/generations` endpoint directly rather than\n * through the OpenAI SDK: the endpoint takes size tokens (`2K`) as well as\n * pixel sizes, has no `n` parameter, and carries reference images for editing\n * in the generation request instead of a separate edits endpoint.\n *\n * Features:\n * - Text-to-image and image-conditioned generation (editing, multi-reference)\n *   from a single call, with per-model reference-count limits enforced.\n * - Size validation across both accepted forms.\n * - `numberOfImages` mapped onto Seedream's group-image mode.\n *\n * @example\n * ```typescript\n * const adapter = byteplusImage('seedream-4-0-250828')\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A guitar in a sunlit workshop',\n *   size: '2K',\n *   modelOptions: { watermark: false },\n * })\n * ```\n */\nexport class BytePlusImageAdapter<\n  TModel extends BytePlusImageModel,\n> extends BaseImageAdapter<\n  TModel,\n  BytePlusImageProviderOptions,\n  BytePlusImageModelProviderOptionsByName,\n  BytePlusImageModelSizeByName,\n  BytePlusImageModelInputModalitiesByName\n> {\n  override readonly kind = 'image' as const\n  readonly name = 'byteplus' as const\n\n  /** Config with the Ark base URL resolved and trailing slashes trimmed. */\n  private readonly clientConfig: Omit<BytePlusImageConfig, 'baseURL'> & {\n    baseURL: string\n  }\n\n  constructor(model: TModel, config: BytePlusImageConfig) {\n    super(model, {})\n    this.clientConfig = withBytePlusArkDefaults(config)\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<\n      BytePlusImageProviderOptions,\n      BytePlusImageModelSizeByName[TModel]\n    >,\n  ): Promise<ImageGenerationResult> {\n    const { numberOfImages, size, modelOptions, logger } = options\n    const model = this.model\n\n    const resolved = resolveMediaPrompt(options.prompt)\n\n    if (resolved.videos.length > 0 || resolved.audios.length > 0) {\n      throw new Error(\n        `byteplus.generateImages does not support video / audio prompt parts on model ${model}.`,\n      )\n    }\n\n    const unsupportedRole = resolved.images.find(\n      (part) =>\n        part.metadata?.role !== undefined &&\n        !SUPPORTED_INPUT_ROLES.has(part.metadata.role),\n    )\n    if (unsupportedRole) {\n      throw new Error(\n        `byteplus: Seedream has no ${unsupportedRole.metadata?.role} input; ` +\n          `it accepts reference images only (${[...SUPPORTED_INPUT_ROLES].join(', ')}).`,\n      )\n    }\n\n    validateBytePlusImagePrompt(model, resolved.text)\n    validateBytePlusReferenceImages(model, resolved.images.length)\n\n    const imageRefs = resolved.images.map(imagePartToImageRef)\n    const request: BytePlusImageGenerationRequest = {\n      ...(imageRefs.length > 0 && { image: imageRefs }),\n      ...(size !== undefined && {\n        size: resolveBytePlusImageSize(size),\n      }),\n      ...resolveBytePlusSequentialImages(model, numberOfImages),\n      // Explicit provider options win over the values derived from the\n      // generic options above (e.g. forcing `sequential_image_generation`).\n      ...modelOptions,\n      model,\n      prompt: resolved.text,\n    }\n\n    try {\n      logger.request(\n        `activity=image provider=${this.name} model=${model} size=${request.size ?? 'default'} refs=${imageRefs.length}`,\n        { provider: this.name, model },\n      )\n\n      const fetchImpl = this.clientConfig.fetch ?? fetch\n      const signal = bytePlusTimeoutSignal(this.clientConfig.timeout)\n      const response = await fetchImpl(\n        `${this.clientConfig.baseURL}/images/generations`,\n        {\n          method: 'POST',\n          ...(signal && { signal }),\n          headers: bytePlusArkHeaders(\n            this.clientConfig.apiKey,\n            toHeaderRecord(this.clientConfig.defaultHeaders),\n          ),\n          body: JSON.stringify(request),\n        },\n      )\n\n      const body = await readJsonBody(response)\n      if (!response.ok) {\n        throw bytePlusArkError(response.status, body, 'image generation')\n      }\n\n      return this.transformResponse(body, logger, numberOfImages)\n    } catch (error: unknown) {\n      logger.errors(`${this.name}.generateImages fatal`, {\n        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),\n        source: `${this.name}.generateImages`,\n      })\n      throw error\n    }\n  }\n\n  private transformResponse(\n    body: unknown,\n    logger: InternalLogger,\n    numberOfImages: number | undefined,\n  ): ImageGenerationResult {\n    // Shape pinned by a live seedream-4-0-250828 call and the Ark OpenAPI\n    // document. Validate rather than cast: `readJsonBody` returns `undefined`\n    // for an empty body and the raw text for a non-JSON one (an HTML error\n    // page from a proxy in front of the API), and casting either would report\n    // \"returned no images\" with the body — the only evidence of what actually\n    // happened — thrown away.\n    if (typeof body !== 'object' || body === null) {\n      throw bytePlusArkError(\n        200,\n        body,\n        'image generation returned a non-object body',\n      )\n    }\n    const payload = body as BytePlusImageGenerationResponse\n\n    const images: Array<GeneratedImage> = []\n    const failures: Array<BytePlusImageErrorObject> = []\n    // Items matching none of the three known shapes. Ark's OpenAPI document\n    // describes a second, nested item form, so this is a live possibility\n    // rather than a defensive branch — and an unrecognized item that is\n    // neither counted nor reported turns provider drift into an\n    // \"returned no images\" with no attribution at all.\n    let unrecognized = 0\n    for (const item of payload.data ?? []) {\n      if (item.b64_json) {\n        images.push({ b64Json: item.b64_json })\n      } else if (item.url) {\n        images.push({ url: item.url })\n      } else if (item.error) {\n        // Group-image mode reports per-image failures alongside successes;\n        // dropping them silently would make a short result look complete.\n        failures.push(item.error)\n      } else {\n        unrecognized += 1\n      }\n    }\n    if (payload.error) failures.push(payload.error)\n\n    if (unrecognized > 0) {\n      logger.errors(\n        `${this.name}.generateImages: ${unrecognized} response item(s) matched ` +\n          `none of b64_json / url / error — the response shape may have changed.`,\n        {\n          source: `${this.name}.generateImages`,\n          provider: this.name,\n          model: this.model,\n          body,\n        },\n      )\n    }\n\n    if (images.length === 0) {\n      const detail =\n        describeFailures(failures) ||\n        (unrecognized > 0\n          ? `${unrecognized} unrecognized response item(s): ${describeBody(body) ?? ''}`\n          : '')\n      throw new Error(\n        `byteplus: image generation returned no images` +\n          (detail ? `: ${detail}` : '.'),\n      )\n    }\n\n    if (failures.length > 0) {\n      logger.errors(\n        `${this.name}.generateImages dropped ${failures.length} failed image(s): ${describeFailures(failures)}`,\n        {\n          source: `${this.name}.generateImages`,\n          provider: this.name,\n          model: this.model,\n          failures,\n        },\n      )\n      // The caller asked for a group and is getting a short array. Warn\n      // unconditionally: the `numberOfImages` warning below only fires when\n      // the count was set explicitly, so a partial failure would otherwise\n      // return successfully with no signal at all.\n      logger.warn(\n        `byteplus: ${failures.length} of ${failures.length + images.length} ` +\n          `images failed to generate; returning ${images.length}.`,\n        { provider: this.name, model: this.model },\n      )\n    }\n\n    if (numberOfImages !== undefined && images.length < numberOfImages) {\n      logger.warn(\n        `byteplus: requested ${numberOfImages} images, received ${images.length}. ` +\n          `Seedream has no exact count — sequential_image_generation.max_images is ` +\n          `an upper bound and the model decides how many the prompt warrants.`,\n        { provider: this.name, model: this.model },\n      )\n    }\n\n    const usage = buildBytePlusImageUsage(payload.usage)\n\n    return {\n      id: generateId(this.name),\n      model: this.model,\n      images,\n      ...(usage ? { usage } : {}),\n    }\n  }\n}\n\n/**\n * Creates a BytePlus Seedream image adapter with an explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'seedream-4-0-250828')\n * @param apiKey - Your BytePlus Ark API key\n * @param config - Optional additional configuration\n * @returns Configured BytePlus image adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createBytePlusImage('seedream-5-0-260128', 'ark-...')\n *\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A cute baby sea otter',\n *   size: '2K',\n * })\n * ```\n */\nexport function createBytePlusImage<TModel extends BytePlusImageModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<BytePlusImageConfig, 'apiKey'>,\n): BytePlusImageAdapter<TModel> {\n  return new BytePlusImageAdapter(model, { apiKey, ...config })\n}\n\n/**\n * Creates a BytePlus Seedream image adapter, reading `ARK_API_KEY` from the\n * environment. Type resolution happens here at the call site.\n *\n * Note that Ark keys are region-isolated: a key issued for `ap-southeast`\n * does not work against the EU host.\n *\n * @param model - The model name (e.g., 'seedream-4-0-250828')\n * @param config - Optional configuration (excluding apiKey, auto-detected)\n * @returns Configured BytePlus image adapter instance with resolved types\n * @throws Error if ARK_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * const adapter = byteplusImage('seedream-4-0-250828')\n *\n * const result = await generateImage({\n *   adapter,\n *   prompt: 'A beautiful sunset over mountains',\n *   modelOptions: { watermark: false },\n * })\n * ```\n */\nexport function byteplusImage<TModel extends BytePlusImageModel>(\n  model: TModel,\n  config?: Omit<BytePlusImageConfig, 'apiKey'>,\n): BytePlusImageAdapter<TModel> {\n  return createBytePlusImage(model, getBytePlusArkApiKeyFromEnv(), config)\n}\n"],"mappings":"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"}