@tanstack/ai-cloudflare 0.0.0 → 0.1.0

package/src/adapters/transcription.ts

@@ -0,0 +1,227 @@
+import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'
+import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
+import { arrayBufferToBase64, generateId } from '@tanstack/ai-utils'
+import { isBindingConfig, resolveConfigFromEnv } from '../utils/config'
+import { runModel } from '../utils/run'
+import type {
+  TranscriptionOptions,
+  TranscriptionResult,
+  TranscriptionSegment,
+  TranscriptionWord,
+} from '@tanstack/ai'
+import type {
+  CloudflareConfig,
+  CloudflareConfigInput,
+  FetchLike,
+} from '../utils/config'
+import type { CloudflareTranscriptionModel } from '../utils/models'
+
+/** Extra inputs forwarded to the transcription model (model specific). */
+export type CloudflareTranscriptionProviderOptions = Record<string, unknown>
+
+interface WhisperOutput {
+  text?: string
+  transcription_info?: { language?: string; duration?: number }
+  segments?: Array<{ start: number; end: number; text: string }>
+  words?: Array<{ word?: string; start?: number; end?: number }>
+}
+
+interface NovaOutput {
+  results?: {
+    channels?: Array<{
+      alternatives?: Array<{
+        transcript?: string
+        words?: Array<{ word?: string; start?: number; end?: number }>
+      }>
+    }>
+  }
+  metadata?: { duration?: number }
+}
+
+async function toBytes(
+  audio: TranscriptionOptions['audio'],
+  fetchImpl: FetchLike,
+  signal: AbortSignal | undefined,
+): Promise<{ bytes: ArrayBuffer; contentType: string }> {
+  if (typeof audio === 'string') {
+    // Base64 (data URI or bare) or a URL to fetch.
+    if (/^https?:\/\//.test(audio)) {
+      const response = await fetchImpl(audio, { signal })
+      if (!response.ok) {
+        throw new Error(
+          `Could not fetch audio from ${audio} (${response.status})`,
+        )
+      }
+      return {
+        bytes: await response.arrayBuffer(),
+        contentType: response.headers.get('content-type') ?? 'audio/mpeg',
+      }
+    }
+    const match = /^data:([^;]+);base64,(.*)$/.exec(audio)
+    const base64 = match?.[2] ?? audio
+    const binary = atob(base64)
+    const bytes = new Uint8Array(binary.length)
+    for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i)
+    return { bytes: bytes.buffer, contentType: match?.[1] ?? 'audio/mpeg' }
+  }
+  if (audio instanceof ArrayBuffer) {
+    return { bytes: audio, contentType: 'audio/mpeg' }
+  }
+  return {
+    bytes: await audio.arrayBuffer(),
+    contentType: audio.type || 'audio/mpeg',
+  }
+}
+
+/**
+ * Cloudflare transcription adapter. Whisper models take base64 audio in the
+ * `audio` input; Deepgram Nova takes the raw bytes. Both return text plus
+ * timed words, and Whisper also returns segments.
+ */
+export class CloudflareTranscriptionAdapter<
+  TModel extends CloudflareTranscriptionModel,
+> extends BaseTranscriptionAdapter<
+  TModel,
+  CloudflareTranscriptionProviderOptions
+> {
+  readonly name = 'cloudflare' as const
+
+  constructor(
+    private readonly cfConfig: CloudflareConfig,
+    model: TModel,
+  ) {
+    super(model, {})
+  }
+
+  async transcribe(
+    options: TranscriptionOptions<CloudflareTranscriptionProviderOptions>,
+  ): Promise<TranscriptionResult> {
+    const { model, logger, language, prompt } = options
+    try {
+      logger.request(
+        `activity=transcription provider=${this.name} model=${model}`,
+        {
+          provider: this.name,
+          model,
+        },
+      )
+      const fetchImpl =
+        (isBindingConfig(this.cfConfig) ? undefined : this.cfConfig.fetch) ??
+        fetch
+      const { bytes, contentType } = await toBytes(
+        options.audio,
+        fetchImpl,
+        options.abortSignal,
+      )
+      const output = model.startsWith('@cf/deepgram/')
+        ? await this.runNova(model, bytes, contentType, options)
+        : await this.runWhisper(
+            model,
+            bytes,
+            { language, prompt, ...options.modelOptions },
+            options.abortSignal,
+          )
+      return { id: generateId(this.name), model, ...output }
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.transcribe fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.transcribe failed`),
+        source: `${this.name}.transcribe`,
+      })
+      throw error
+    }
+  }
+
+  private async runWhisper(
+    model: string,
+    bytes: ArrayBuffer,
+    inputs: { language?: string; prompt?: string } & Record<string, unknown>,
+    signal: AbortSignal | undefined,
+  ): Promise<Omit<TranscriptionResult, 'id' | 'model'>> {
+    const { language, prompt, ...rest } = inputs
+    const output = (await runModel(
+      this.cfConfig,
+      model,
+      {
+        ...(language && { language }),
+        ...(prompt && { initial_prompt: prompt }),
+        ...rest,
+        audio: arrayBufferToBase64(bytes),
+      },
+      { signal },
+    )) as WhisperOutput
+    if (typeof output.text !== 'string') {
+      throw new Error(`Workers AI ${model} returned no transcript`)
+    }
+    return {
+      text: output.text,
+      language: output.transcription_info?.language,
+      duration: output.transcription_info?.duration,
+      segments: output.segments?.map(
+        (segment, id): TranscriptionSegment => ({
+          id,
+          start: segment.start,
+          end: segment.end,
+          text: segment.text.trim(),
+        }),
+      ),
+      words: toWords(output.words),
+    }
+  }
+
+  private async runNova(
+    model: string,
+    bytes: ArrayBuffer,
+    contentType: string,
+    options: TranscriptionOptions<CloudflareTranscriptionProviderOptions>,
+  ): Promise<Omit<TranscriptionResult, 'id' | 'model'>> {
+    const output = (await runModel(
+      this.cfConfig,
+      model,
+      {
+        ...(options.language && { language: options.language }),
+        ...options.modelOptions,
+      },
+      {
+        signal: options.abortSignal,
+        binary: { field: 'audio', body: bytes, contentType },
+      },
+    )) as NovaOutput
+    const alternative = output.results?.channels?.[0]?.alternatives?.[0]
+    if (typeof alternative?.transcript !== 'string') {
+      throw new Error(`Workers AI ${model} returned no transcript`)
+    }
+    return {
+      text: alternative.transcript,
+      duration: output.metadata?.duration,
+      words: toWords(alternative?.words),
+    }
+  }
+}
+
+function toWords(
+  words: Array<{ word?: string; start?: number; end?: number }> | undefined,
+): Array<TranscriptionWord> | undefined {
+  return words?.map((w) => ({
+    word: (w.word ?? '').trim(),
+    start: w.start ?? 0,
+    end: w.end ?? 0,
+  }))
+}
+
+export function createCloudflareTranscription<
+  TModel extends CloudflareTranscriptionModel,
+>(
+  model: TModel,
+  config: CloudflareConfig,
+): CloudflareTranscriptionAdapter<TModel> {
+  return new CloudflareTranscriptionAdapter(config, model)
+}
+
+export function cloudflareTranscription<
+  TModel extends CloudflareTranscriptionModel,
+>(
+  model: TModel,
+  config?: CloudflareConfigInput,
+): CloudflareTranscriptionAdapter<TModel> {
+  return new CloudflareTranscriptionAdapter(resolveConfigFromEnv(config), model)
+}

package/src/adapters/tts.ts

@@ -0,0 +1,100 @@
+import { BaseTTSAdapter } from '@tanstack/ai/adapters'
+import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
+import { generateId } from '@tanstack/ai-utils'
+import { resolveConfigFromEnv } from '../utils/config'
+import { outputToBase64, runModel } from '../utils/run'
+import type { TTSOptions, TTSResult } from '@tanstack/ai'
+import type { CloudflareConfig, CloudflareConfigInput } from '../utils/config'
+import type { CloudflareTTSModel } from '../utils/models'
+
+/** Text-to-speech inputs forwarded to the model (Deepgram Aura fields). */
+export interface CloudflareTTSProviderOptions {
+  speaker?: string
+  encoding?: 'linear16' | 'flac' | 'mulaw' | 'alaw' | 'mp3' | 'opus' | 'aac'
+  container?: 'none' | 'wav' | 'ogg'
+  sample_rate?: number
+  bit_rate?: number
+  [key: string]: unknown
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  mp3: 'audio/mpeg',
+  opus: 'audio/opus',
+  aac: 'audio/aac',
+  flac: 'audio/flac',
+  wav: 'audio/wav',
+  pcm: 'audio/pcm',
+}
+
+/**
+ * Cloudflare text-to-speech adapter for Workers AI models such as Deepgram
+ * Aura. `voice` maps to `speaker` and `format` to `encoding`; the audio comes
+ * back base64-encoded.
+ */
+export class CloudflareTTSAdapter<
+  TModel extends CloudflareTTSModel,
+> extends BaseTTSAdapter<TModel, CloudflareTTSProviderOptions> {
+  readonly name = 'cloudflare' as const
+
+  constructor(
+    private readonly cfConfig: CloudflareConfig,
+    model: TModel,
+  ) {
+    super(model, {})
+  }
+
+  async generateSpeech(
+    options: TTSOptions<CloudflareTTSProviderOptions>,
+  ): Promise<TTSResult> {
+    const { model, logger, text, voice, format = 'mp3' } = options
+    const inputs = {
+      ...(voice && { speaker: voice }),
+      // Aura takes the codec as `encoding` and the wrapper as `container`;
+      // `wav` and `pcm` are both linear16.
+      encoding: format === 'wav' || format === 'pcm' ? 'linear16' : format,
+      ...(format === 'wav' && { container: 'wav' }),
+      ...options.modelOptions,
+      text,
+    }
+    try {
+      logger.request(
+        `activity=tts provider=${this.name} model=${model} chars=${text.length}`,
+        { provider: this.name, model },
+      )
+      const output = await runModel(this.cfConfig, model, inputs, {
+        signal: options.abortSignal,
+      })
+      const audio =
+        output && typeof output === 'object' && 'audio' in output
+          ? (output as { audio: string }).audio
+          : await outputToBase64(output)
+      return {
+        id: generateId(this.name),
+        model,
+        audio,
+        format,
+        contentType: CONTENT_TYPES[format],
+      }
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.generateSpeech fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.generateSpeech failed`),
+        source: `${this.name}.generateSpeech`,
+      })
+      throw error
+    }
+  }
+}
+
+export function createCloudflareTTS<TModel extends CloudflareTTSModel>(
+  model: TModel,
+  config: CloudflareConfig,
+): CloudflareTTSAdapter<TModel> {
+  return new CloudflareTTSAdapter(config, model)
+}
+
+export function cloudflareTTS<TModel extends CloudflareTTSModel>(
+  model: TModel,
+  config?: CloudflareConfigInput,
+): CloudflareTTSAdapter<TModel> {
+  return new CloudflareTTSAdapter(resolveConfigFromEnv(config), model)
+}

package/src/byok.ts

@@ -0,0 +1,21 @@
+import { defineByokProvider } from '@tanstack/ai/byok'
+
+/** The account id that goes with {@link cloudflareByok}. */
+export const cloudflareAccountByok = defineByokProvider({
+  id: 'cloudflare-account',
+  label: 'Cloudflare account ID',
+  env: 'CLOUDFLARE_ACCOUNT_ID',
+})
+
+/**
+ * BYOK descriptor for a user-supplied Cloudflare API token. A user who brings
+ * a token brings the account it belongs to, so {@link cloudflareAccountByok}
+ * rides along: register both with `defineByok({ providers })` and a send for
+ * `cloudflare` carries both headers.
+ */
+export const cloudflareByok = defineByokProvider({
+  id: 'cloudflare',
+  label: 'Cloudflare API token',
+  env: 'CLOUDFLARE_API_TOKEN',
+  with: [cloudflareAccountByok],
+})

package/src/gateway.ts

@@ -0,0 +1,57 @@
+import { gatewayHeaders } from './utils/config'
+import type { AIGatewayProviders } from '@cloudflare/workers-types'
+import type { CloudflareGatewayOptions } from './utils/config'
+
+export interface CloudflareGatewayTarget extends Omit<
+  CloudflareGatewayOptions,
+  'id'
+> {
+  accountId: string
+  gatewayId: string
+  /** Cloudflare API token, needed when the gateway has authentication on. */
+  cfApiKey?: string
+}
+
+/**
+ * Gateway endpoints mirror each vendor's own path after the host, and most
+ * vendor SDKs already append their version segment (Anthropic `/v1/messages`,
+ * Mistral `/v1/...`, Cohere `/v1/chat`). OpenAI-style SDKs append only
+ * `/chat/completions`, which matches Cloudflare's `openai`, `groq`,
+ * `perplexity-ai`, `deepseek`, and `cerebras` endpoints. xAI is the exception:
+ * Cloudflare serves it at `/grok/v1/...`, so its base URL keeps the `/v1`.
+ */
+const PROVIDER_PATH_SUFFIX: Record<string, string> = { grok: '/v1' }
+
+/**
+ * Builds the `baseURL` and headers that point any provider adapter at that
+ * provider's endpoint on your AI Gateway. Pass them through the adapter's
+ * client options (`baseURL` + `defaultHeaders` for OpenAI-style SDKs).
+ *
+ * The headers carry the per-request `cf-aig-*` options plus
+ * `cf-aig-authorization: Bearer <cfApiKey>` when `cfApiKey` is set. The
+ * gateway id lives in the URL, so no `cf-aig-gateway-id` header is sent.
+ *
+ * @example
+ * ```typescript
+ * const gateway = cloudflareGateway('openai', { accountId, gatewayId: 'prod' })
+ * const adapter = createOpenaiChat('gpt-5.5', process.env.OPENAI_API_KEY!, {
+ *   baseURL: gateway.baseURL,
+ *   defaultHeaders: gateway.headers,
+ * })
+ * ```
+ */
+export function cloudflareGateway(
+  provider: AIGatewayProviders | 'compat' | (string & {}),
+  target: CloudflareGatewayTarget,
+): { baseURL: string; headers: Record<string, string> } {
+  const { accountId, gatewayId, cfApiKey, ...options } = target
+  const { 'cf-aig-gateway-id': _id, ...headers } = gatewayHeaders({
+    id: gatewayId,
+    ...options,
+  })
+  if (cfApiKey) headers['cf-aig-authorization'] = `Bearer ${cfApiKey}`
+  return {
+    baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/${provider}${PROVIDER_PATH_SUFFIX[provider] ?? ''}`,
+    headers,
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * @module @tanstack/ai-cloudflare
+ *
+ * Cloudflare provider adapter for TanStack AI: Workers AI chat, embeddings,
+ * images, speech and transcription over the `env.AI` binding or the REST
+ * API, plus AI Gateway routing for any provider.
+ */
+
+export {
+  CloudflareTextAdapter,
+  createCloudflareText,
+  cloudflareText,
+  type CloudflareTextProviderOptions,
+} from './adapters/text'
+
+export {
+  createCloudflareSummarize,
+  cloudflareSummarize,
+  type CloudflareSummarizeModel,
+} from './adapters/summarize'
+
+export {
+  CloudflareEmbeddingAdapter,
+  createCloudflareEmbedding,
+  cloudflareEmbedding,
+  type CloudflareEmbeddingProviderOptions,
+} from './adapters/embedding'
+
+export {
+  CloudflareImageAdapter,
+  createCloudflareImage,
+  cloudflareImage,
+  type CloudflareImageProviderOptions,
+} from './adapters/image'
+
+export {
+  CloudflareTTSAdapter,
+  createCloudflareTTS,
+  cloudflareTTS,
+  type CloudflareTTSProviderOptions,
+} from './adapters/tts'
+
+export {
+  CloudflareTranscriptionAdapter,
+  createCloudflareTranscription,
+  cloudflareTranscription,
+  type CloudflareTranscriptionProviderOptions,
+} from './adapters/transcription'
+
+export { cloudflareGateway, type CloudflareGatewayTarget } from './gateway'
+
+export type {
+  CloudflareBindingConfig,
+  CloudflareConfig,
+  CloudflareConfigInput,
+  CloudflareGatewayOptions,
+  CloudflareRestConfig,
+  CloudflareTextConfig,
+  CloudflareTextRestConfig,
+} from './utils/config'
+
+export type {
+  CloudflareEmbeddingModel,
+  CloudflareImageModel,
+  CloudflareTextModel,
+  CloudflareTranscriptionModel,
+  CloudflareTTSModel,
+} from './utils/models'

package/src/utils/config.ts

@@ -0,0 +1,129 @@
+import { getApiKeyFromEnv } from '@tanstack/ai-utils'
+import type { Ai, GatewayOptions } from '@cloudflare/workers-types'
+import type { ClientOptions } from 'openai'
+
+/**
+ * AI Gateway routing options. `id` is the gateway id (use `"default"` for the
+ * account's auto-created gateway). The remaining fields are per-request
+ * gateway controls (cache, logging, retries) and map to `cf-aig-*` headers on
+ * the REST path or to the `gateway` run option on the binding path.
+ */
+export type CloudflareGatewayOptions = GatewayOptions
+
+export type FetchLike = NonNullable<ClientOptions['fetch']>
+
+/**
+ * Run through the Workers AI binding (`env.AI`) inside a Cloudflare Worker.
+ * No API token is needed.
+ */
+export interface CloudflareBindingConfig {
+  binding: Ai
+  gateway?: CloudflareGatewayOptions
+  accountId?: never
+  apiKey?: never
+}
+
+/** Run through the Cloudflare REST API from any runtime. */
+export interface CloudflareRestConfig {
+  accountId: string
+  apiKey: string
+  gateway?: CloudflareGatewayOptions
+  /** Custom fetch for every request. */
+  fetch?: FetchLike
+  binding?: never
+}
+
+/**
+ * REST config for the chat surface. Also accepts the OpenAI SDK client
+ * options (`baseURL`, `defaultHeaders`, `timeout`, `maxRetries`, ...), which
+ * only the text and summarize adapters read.
+ */
+export interface CloudflareTextRestConfig
+  extends CloudflareRestConfig, Omit<ClientOptions, 'apiKey' | 'fetch'> {}
+
+export type CloudflareConfig = CloudflareBindingConfig | CloudflareRestConfig
+
+export type CloudflareTextConfig =
+  | CloudflareBindingConfig
+  | CloudflareTextRestConfig
+
+/**
+ * What the env-reading factories accept: a binding, or REST fields with any
+ * missing ones read from `CLOUDFLARE_ACCOUNT_ID` and `CLOUDFLARE_API_TOKEN`.
+ */
+export type CloudflareConfigInput<
+  TRest extends CloudflareRestConfig = CloudflareRestConfig,
+> = CloudflareBindingConfig | Partial<TRest>
+
+export const CLOUDFLARE_API_BASE = 'https://api.cloudflare.com/client/v4'
+
+export function isBindingConfig(config: {
+  binding?: Ai
+}): config is CloudflareBindingConfig {
+  return config.binding !== undefined
+}
+
+/** Base URL for the OpenAI-compatible chat surface of an account. */
+export function restChatBaseURL(config: CloudflareTextRestConfig): string {
+  return (
+    config.baseURL ||
+    `${CLOUDFLARE_API_BASE}/accounts/${config.accountId}/ai/v1`
+  )
+}
+
+/**
+ * Translates gateway options into the `cf-aig-*` request headers the REST
+ * API reads. Retries are not mapped: set them on the gateway itself.
+ */
+export function gatewayHeaders(
+  gateway: CloudflareGatewayOptions | undefined,
+): Record<string, string> {
+  if (!gateway) return {}
+  const headers: Record<string, string> = { 'cf-aig-gateway-id': gateway.id }
+  if (gateway.skipCache !== undefined) {
+    headers['cf-aig-skip-cache'] = String(gateway.skipCache)
+  }
+  if (gateway.cacheTtl !== undefined) {
+    headers['cf-aig-cache-ttl'] = String(gateway.cacheTtl)
+  }
+  if (gateway.cacheKey !== undefined) {
+    headers['cf-aig-cache-key'] = gateway.cacheKey
+  }
+  if (gateway.collectLog !== undefined) {
+    headers['cf-aig-collect-log'] = String(gateway.collectLog)
+  }
+  if (gateway.eventId !== undefined) {
+    headers['cf-aig-event-id'] = gateway.eventId
+  }
+  if (gateway.requestTimeoutMs !== undefined) {
+    headers['cf-aig-request-timeout'] = String(gateway.requestTimeoutMs)
+  }
+  if (gateway.metadata !== undefined) {
+    headers['cf-aig-metadata'] = JSON.stringify(gateway.metadata)
+  }
+  return headers
+}
+
+/**
+ * Resolves a config for the env-reading factories: a binding config passes
+ * through, anything else is filled from `CLOUDFLARE_ACCOUNT_ID` and
+ * `CLOUDFLARE_API_TOKEN`.
+ */
+export function resolveConfigFromEnv<TRest extends CloudflareRestConfig>(
+  config: CloudflareConfigInput<TRest> | undefined,
+): CloudflareBindingConfig | (Partial<TRest> & CloudflareRestConfig) {
+  if (config && isBindingConfig(config)) return config
+  const rest: Partial<TRest> = config ?? {}
+  try {
+    return {
+      ...rest,
+      accountId: rest.accountId ?? getApiKeyFromEnv('CLOUDFLARE_ACCOUNT_ID'),
+      apiKey: rest.apiKey ?? getApiKeyFromEnv('CLOUDFLARE_API_TOKEN'),
+    }
+  } catch (cause) {
+    throw new Error(
+      'CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN are required. Set them in your environment, pass { accountId, apiKey }, or pass { binding: env.AI } inside a Worker.',
+      { cause },
+    )
+  }
+}