@tanstack/ai-lovable 0.0.0

package/src/image/image-input-to-file.ts

@@ -0,0 +1,81 @@
+import { base64ToArrayBuffer } from '@tanstack/ai-utils'
+import type { ImagePart, MediaInputMetadata } from '@tanstack/ai'
+
+const DEFAULT_MIME = 'image/png'
+const MIME_TO_EXT: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+}
+
+function extForMime(mimeType: string): string {
+  return MIME_TO_EXT[mimeType] ?? mimeType.split('/')[1] ?? 'png'
+}
+
+function ensureFileSupport(): void {
+  if (typeof File === 'undefined') {
+    throw new Error(
+      '`File` is not available in this environment. ' +
+        'Image-conditioned generation requires Node 20+ or a browser context.',
+    )
+  }
+}
+
+/**
+ * Convert a TanStack `ImagePart` into an OpenAI-compatible `File`.
+ *
+ * HTTP(S) URLs are fetched only when `allowUrlFetch` is set. The gateway
+ * edit and `input_reference` endpoints need uploaded bytes, not a URL.
+ */
+export async function imagePartToFile(
+  part: ImagePart<MediaInputMetadata>,
+  fallbackName: string,
+  allowUrlFetch: boolean,
+  abortSignal?: AbortSignal,
+): Promise<File> {
+  ensureFileSupport()
+
+  if (part.source.type === 'data') {
+    const mimeType = part.source.mimeType || DEFAULT_MIME
+    const bytes = base64ToArrayBuffer(part.source.value)
+    return new File([bytes], `${fallbackName}.${extForMime(mimeType)}`, {
+      type: mimeType,
+    })
+  }
+
+  if (/^https?:\/\//i.test(part.source.value) && !allowUrlFetch) {
+    throw new Error(
+      `lovable: HTTP(S) URL image inputs are not fetched by default because ` +
+        `the edit / input_reference endpoints require uploaded bytes, so ` +
+        `the image would be downloaded and buffered in memory (risking OOM on ` +
+        `constrained runtimes). Pass a data: URI, or set \`allowUrlFetch: true\` ` +
+        `on the adapter config to opt into fetching. URL: ${part.source.value}`,
+    )
+  }
+
+  const response = await fetch(
+    part.source.value,
+    abortSignal ? { signal: abortSignal } : undefined,
+  )
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch image input (${response.status} ${response.statusText}): ${part.source.value}`,
+    )
+  }
+  const blob = await response.blob()
+  const mimeType =
+    part.source.mimeType || blob.type || inferMimeFromUrl(part.source.value)
+  return new File([blob], `${fallbackName}.${extForMime(mimeType)}`, {
+    type: mimeType,
+  })
+}
+
+function inferMimeFromUrl(url: string): string {
+  const match = url.match(/\.(png|jpe?g|webp|gif)(?:\?|#|$)/i)
+  if (!match || !match[1]) return DEFAULT_MIME
+  const ext = match[1].toLowerCase()
+  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg'
+  return `image/${ext}`
+}

package/src/image/image-provider-options.ts

@@ -0,0 +1,17 @@
+export type LovableImageSize = '1024x1024' | '1536x1024' | '1024x1536' | 'auto'
+
+export type LovableImageQuality = 'high' | 'medium' | 'low' | 'auto'
+
+export type LovableImageOutputFormat = 'png' | 'jpeg' | 'webp'
+
+export type LovableImageBackground = 'transparent' | 'opaque' | 'auto'
+
+export type LovableImageModeration = 'low' | 'auto'
+
+export interface LovableImageProviderOptions {
+  quality?: LovableImageQuality
+  output_format?: LovableImageOutputFormat
+  background?: LovableImageBackground
+  moderation?: LovableImageModeration
+  user?: string
+}

package/src/index.ts

@@ -0,0 +1,125 @@
+/**
+ * @module @tanstack/ai-lovable
+ *
+ * Lovable AI Gateway adapter for TanStack AI.
+ */
+
+export {
+  LovableTextAdapter,
+  type LovableTextConfig,
+  type LovableTextProviderOptions,
+} from './adapters/text'
+
+export {
+  createLovableText,
+  lovableText,
+  type LovableTextApi,
+  type LovableResponsesApiConfig,
+  type LovableChatApiConfig,
+} from './adapters/factory'
+
+export {
+  LovableResponsesTextAdapter,
+  createLovableResponsesText,
+  lovableResponsesText,
+  type LovableResponsesTextConfig,
+  type LovableResponsesTextProviderOptions,
+} from './adapters/responses-text'
+
+export {
+  createLovableSummarize,
+  lovableSummarize,
+  type LovableSummarizeConfig,
+  type LovableSummarizeModel,
+} from './adapters/summarize'
+
+export {
+  LovableEmbeddingAdapter,
+  createLovableEmbedding,
+  lovableEmbedding,
+  type LovableEmbeddingConfig,
+} from './adapters/embedding'
+export type { LovableEmbeddingProviderOptions } from './embedding/embedding-provider-options'
+
+export {
+  LovableImageAdapter,
+  createLovableImage,
+  lovableImage,
+  type LovableImageConfig,
+} from './adapters/image'
+export type { LovableImageProviderOptions } from './image/image-provider-options'
+
+/**
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export {
+  LovableVideoAdapter,
+  createLovableVideo,
+  lovableVideo,
+  type LovableVideoConfig,
+} from './adapters/video'
+export type {
+  LovableVideoProviderOptions,
+  LovableVideoSize,
+  LovableHdVideoSize,
+  Lovable4kVideoSize,
+  LovableVideoDuration,
+  LovableVideoSeconds,
+} from './video/video-provider-options'
+
+export {
+  LovableTTSAdapter,
+  createLovableSpeech,
+  lovableSpeech,
+  type LovableTTSConfig,
+} from './adapters/tts'
+export type {
+  LovableTTSProviderOptions,
+  LovableTTSVoice,
+  LovableTTSFormat,
+} from './audio/tts-provider-options'
+
+export {
+  LovableTranscriptionAdapter,
+  createLovableTranscription,
+  lovableTranscription,
+  type LovableTranscriptionConfig,
+} from './adapters/transcription'
+export type { LovableTranscriptionProviderOptions } from './audio/transcription-provider-options'
+
+export {
+  LOVABLE_CHAT_MODELS,
+  LOVABLE_IMAGE_MODELS,
+  LOVABLE_VIDEO_MODELS,
+  LOVABLE_EMBEDDING_MODELS,
+  LOVABLE_TTS_MODELS,
+  LOVABLE_TRANSCRIPTION_MODELS,
+} from './model-meta'
+export type {
+  LovableChatModel,
+  LovableModelId,
+  LovableChatModelProviderOptionsByName,
+  LovableModelInputModalitiesByName,
+  LovableImageModel,
+  LovableVideoModel,
+  LovableEmbeddingModel,
+  LovableTTSModel,
+  LovableTranscriptionModel,
+  ResolveProviderOptions,
+  ResolveInputModalities,
+} from './model-meta'
+
+export type {
+  LovableTextMetadata,
+  LovableImageMetadata,
+  LovableAudioMetadata,
+  LovableVideoMetadata,
+  LovableDocumentMetadata,
+  LovableMessageMetadataByModality,
+} from './message-types'
+
+export {
+  getLovableApiKeyFromEnv,
+  lovableGatewayHeaders,
+  type LovableClientConfig,
+} from './utils/client'

package/src/message-types.ts

@@ -0,0 +1,45 @@
+/**
+ * Metadata for Lovable AI Gateway document content parts.
+ */
+export interface LovableDocumentMetadata {}
+
+/**
+ * Metadata for Lovable AI Gateway text content parts.
+ */
+export interface LovableTextMetadata {}
+
+/**
+ * Metadata for Lovable AI Gateway image content parts.
+ */
+export interface LovableImageMetadata {
+  /**
+   * Specifies the detail level of the image.
+   * - 'auto': Let the model decide based on image size and content
+   * - 'low': Use low resolution processing (faster, cheaper, less detail)
+   * - 'high': Use high resolution processing (slower, more expensive, more detail)
+   *
+   * @default 'auto'
+   */
+  detail?: 'auto' | 'low' | 'high'
+}
+
+/**
+ * Metadata for Lovable AI Gateway audio content parts.
+ */
+export interface LovableAudioMetadata {}
+
+/**
+ * Metadata for Lovable AI Gateway video content parts.
+ */
+export interface LovableVideoMetadata {}
+
+/**
+ * Map of modality types to their Lovable AI Gateway metadata types.
+ */
+export interface LovableMessageMetadataByModality {
+  text: LovableTextMetadata
+  image: LovableImageMetadata
+  audio: LovableAudioMetadata
+  video: LovableVideoMetadata
+  document: LovableDocumentMetadata
+}

package/src/model-meta.ts

@@ -0,0 +1,161 @@
+import type { LovableEmbeddingProviderOptions } from './embedding/embedding-provider-options'
+import type {
+  LovableImageProviderOptions,
+  LovableImageSize,
+} from './image/image-provider-options'
+import type { LovableTextProviderOptions } from './text/text-provider-options'
+import type {
+  LovableHdVideoSize,
+  LovableVideoDuration,
+  LovableVideoProviderOptions,
+  LovableVideoSize,
+} from './video/video-provider-options'
+
+/**
+ * Chat models listed on https://docs.lovable.dev/features/ai.
+ * Ids use the `google/` and `openai/` form that the gateway accepts.
+ */
+export const LOVABLE_CHAT_MODELS = [
+  'google/gemini-3.7-flash',
+  'google/gemini-3.6-flash',
+  'google/gemini-3.5-flash',
+  'google/gemini-3.1-pro-preview',
+  'google/gemini-3.1-flash-lite',
+  'google/gemini-3-flash-preview',
+  'google/gemini-2.5-pro',
+  'google/gemini-2.5-flash',
+  'google/gemini-2.5-flash-lite',
+  'openai/gpt-5.6-sol',
+  'openai/gpt-5.6-terra',
+  'openai/gpt-5.6-luna',
+  'openai/gpt-5.5-pro',
+  'openai/gpt-5.5',
+  'openai/gpt-5.4-pro',
+  'openai/gpt-5.4',
+  'openai/gpt-5.4-mini',
+  'openai/gpt-5.4-nano',
+  'openai/gpt-5.2',
+  'openai/gpt-5',
+  'openai/gpt-5-mini',
+  'openai/gpt-5-nano',
+] as const
+
+export type LovableChatModel = (typeof LOVABLE_CHAT_MODELS)[number]
+
+/**
+ * A curated chat model id, or any other id the gateway accepts.
+ * Uncurated ids fall back to text-only input and the generic provider options.
+ */
+export type LovableModelId = LovableChatModel | (string & {})
+
+export type LovableChatModelProviderOptionsByName = {
+  [K in LovableChatModel]: LovableTextProviderOptions
+}
+
+export type LovableModelInputModalitiesByName = {
+  [K in LovableChatModel]: readonly ['text', 'image']
+}
+
+export type LovableChatModelToolCapabilitiesByName = {
+  [K in LovableChatModel]: readonly []
+}
+
+export type ResolveProviderOptions<TModel extends string> =
+  TModel extends keyof LovableChatModelProviderOptionsByName
+    ? LovableChatModelProviderOptionsByName[TModel]
+    : LovableTextProviderOptions
+
+export type ResolveInputModalities<TModel extends string> =
+  TModel extends keyof LovableModelInputModalitiesByName
+    ? LovableModelInputModalitiesByName[TModel]
+    : readonly ['text']
+
+export const LOVABLE_IMAGE_MODELS = [
+  'openai/gpt-image-2',
+  'openai/gpt-image-1-mini',
+  'google/gemini-3.1-flash-image',
+  'google/gemini-3.1-flash-lite-image',
+  'google/gemini-3-pro-image',
+  'google/gemini-2.5-flash-image',
+] as const
+
+export type LovableImageModel = (typeof LOVABLE_IMAGE_MODELS)[number]
+
+export type LovableImageModelProviderOptionsByName = {
+  [K in LovableImageModel]: LovableImageProviderOptions
+}
+
+export type LovableImageModelSizeByName = {
+  [K in LovableImageModel]: LovableImageSize
+}
+
+export type LovableImageModelInputModalitiesByName = {
+  [K in LovableImageModel]: readonly ['image']
+}
+
+/**
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export const LOVABLE_VIDEO_MODELS = [
+  'google/veo-3.1-lite',
+  'google/veo-3.1-fast',
+  'google/veo-3.1',
+] as const
+
+/**
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type LovableVideoModel = (typeof LOVABLE_VIDEO_MODELS)[number]
+
+export type LovableVideoModelProviderOptionsByName = {
+  [K in LovableVideoModel]: LovableVideoProviderOptions
+}
+
+export type LovableVideoModelSizeByName = {
+  'google/veo-3.1-lite': LovableHdVideoSize
+  'google/veo-3.1-fast': LovableVideoSize
+  'google/veo-3.1': LovableVideoSize
+}
+
+export type LovableVideoModelDurationByName = {
+  [K in LovableVideoModel]: LovableVideoDuration
+}
+
+export type LovableVideoModelInputModalitiesByName = {
+  [K in LovableVideoModel]: readonly ['image']
+}
+
+export const LOVABLE_EMBEDDING_MODELS = [
+  'google/gemini-embedding-2',
+  'google/gemini-embedding-001',
+  'openai/text-embedding-3-small',
+  'openai/text-embedding-3-large',
+] as const
+
+export type LovableEmbeddingModel = (typeof LOVABLE_EMBEDDING_MODELS)[number]
+
+export type LovableEmbeddingModelProviderOptionsByName = {
+  [K in LovableEmbeddingModel]: LovableEmbeddingProviderOptions
+}
+
+export type LovableEmbeddingModelInputModalitiesByName = {
+  [K in LovableEmbeddingModel]: readonly ['text']
+}
+
+export const LOVABLE_TTS_MODELS = [
+  'openai/gpt-4o-mini-tts',
+  'google/gemini-2.5-flash-tts',
+  'google/gemini-2.5-pro-tts',
+  'google/gemini-2.5-flash-lite-preview-tts',
+  'google/gemini-3.1-flash-tts-preview',
+] as const
+
+export type LovableTTSModel = (typeof LOVABLE_TTS_MODELS)[number]
+
+export const LOVABLE_TRANSCRIPTION_MODELS = [
+  'openai/gpt-4o-mini-transcribe',
+  'openai/gpt-4o-transcribe',
+] as const
+
+export type LovableTranscriptionModel =
+  (typeof LOVABLE_TRANSCRIPTION_MODELS)[number]

package/src/text/responses-provider-options.ts

@@ -0,0 +1,8 @@
+import type { LovableTextProviderOptions } from './text-provider-options'
+
+export type LovableResponsesProviderOptions = Pick<
+  LovableTextProviderOptions,
+  'temperature' | 'top_p' | 'max_output_tokens' | 'user'
+>
+
+export type ExternalResponsesProviderOptions = LovableResponsesProviderOptions

package/src/text/text-provider-options.ts

@@ -0,0 +1,18 @@
+export interface LovableTextProviderOptions {
+  temperature?: number | null
+  top_p?: number | null
+  max_tokens?: number | null
+  max_completion_tokens?: number | null
+  max_output_tokens?: number | null
+  frequency_penalty?: number | null
+  presence_penalty?: number | null
+  stop?: string | null | Array<string>
+  seed?: number | null
+  reasoning?: boolean | Record<string, unknown> | null
+  include_reasoning?: boolean | null
+  response_format?: unknown
+  structured_outputs?: boolean | null
+  user?: string | null
+}
+
+export type ExternalTextProviderOptions = LovableTextProviderOptions

package/src/utils/client.ts

@@ -0,0 +1,50 @@
+import { getApiKeyFromEnv } from '@tanstack/ai-utils'
+import type { ClientOptions } from 'openai'
+
+export const LOVABLE_DEFAULT_BASE_URL = 'https://ai.gateway.lovable.dev/v1'
+
+export interface LovableClientConfig extends Omit<ClientOptions, 'apiKey'> {
+  apiKey: string
+}
+
+export function getLovableApiKeyFromEnv(): string {
+  try {
+    return getApiKeyFromEnv('LOVABLE_API_KEY')
+  } catch (cause) {
+    throw new Error(
+      'LOVABLE_API_KEY is required. Set it in the environment or pass apiKey to the factory.',
+      { cause },
+    )
+  }
+}
+
+export function lovableGatewayHeaders(apiKey: string): {
+  'Lovable-API-Key': string
+  'X-Lovable-AIG-SDK': string
+} {
+  return {
+    'Lovable-API-Key': apiKey,
+    'X-Lovable-AIG-SDK': 'tanstack-ai',
+  }
+}
+
+export function withLovableDefaults(
+  config: LovableClientConfig,
+): ClientOptions {
+  const { defaultHeaders, ...rest } = config
+  return {
+    ...rest,
+    baseURL: config.baseURL || LOVABLE_DEFAULT_BASE_URL,
+    defaultHeaders: {
+      ...lovableGatewayHeaders(config.apiKey),
+      ...defaultHeaders,
+    },
+  }
+}
+
+export function openaiRequestOptions(
+  abortSignal?: AbortSignal,
+): { signal: AbortSignal } | undefined {
+  if (!abortSignal) return undefined
+  return { signal: abortSignal }
+}

package/src/video/video-provider-options.ts

@@ -0,0 +1,128 @@
+/**
+ * @experimental Video generation is an experimental feature and may change.
+ */
+
+export type LovableHdVideoSize =
+  | '1280x720'
+  | '720x1280'
+  | '1920x1080'
+  | '1080x1920'
+
+export type Lovable4kVideoSize = '3840x2160' | '2160x3840'
+
+export type LovableVideoSize = LovableHdVideoSize | Lovable4kVideoSize
+
+export type LovableVideoSeconds = '4' | '6' | '8'
+
+export type LovableVideoDuration = 4 | 6 | 8
+
+export interface LovableVideoProviderOptions {
+  size?: LovableVideoSize
+  seconds?: LovableVideoSeconds
+}
+
+const HD_SIZES: ReadonlyArray<LovableHdVideoSize> = [
+  '1280x720',
+  '720x1280',
+  '1920x1080',
+  '1080x1920',
+]
+
+const FOUR_K_SIZES: ReadonlyArray<Lovable4kVideoSize> = [
+  '3840x2160',
+  '2160x3840',
+]
+
+const ALL_SIZES: ReadonlyArray<LovableVideoSize> = [
+  ...HD_SIZES,
+  ...FOUR_K_SIZES,
+]
+
+const HIGH_RES_SIZES: ReadonlySet<string> = new Set([
+  '1920x1080',
+  '1080x1920',
+  '3840x2160',
+  '2160x3840',
+])
+
+const FOUR_K_MODELS: ReadonlySet<string> = new Set([
+  'google/veo-3.1-fast',
+  'google/veo-3.1',
+])
+
+export function is4kVideoSize(size: string): size is Lovable4kVideoSize {
+  return (FOUR_K_SIZES as ReadonlyArray<string>).includes(size)
+}
+
+export function isHighResVideoSize(size: string): boolean {
+  return HIGH_RES_SIZES.has(size)
+}
+
+export function supports4kVideo(model: string): boolean {
+  return FOUR_K_MODELS.has(model)
+}
+
+export function validateVideoSize(
+  model: string,
+  size?: string,
+): asserts size is LovableVideoSize | undefined {
+  if (!size) return
+
+  if (!(ALL_SIZES as ReadonlyArray<string>).includes(size)) {
+    throw new Error(
+      `Size "${size}" is not supported by model "${model}". Supported sizes: ${ALL_SIZES.join(', ')}`,
+    )
+  }
+
+  if (is4kVideoSize(size) && !supports4kVideo(model)) {
+    throw new Error(
+      `Size "${size}" is 4K. Only google/veo-3.1-fast and google/veo-3.1 support 4K.`,
+    )
+  }
+}
+
+export function validateVideoSeconds(
+  model: string,
+  seconds?: number | string,
+): asserts seconds is LovableVideoSeconds | LovableVideoDuration | undefined {
+  if (seconds === undefined) return
+
+  const isValid =
+    typeof seconds === 'string'
+      ? seconds === '4' || seconds === '6' || seconds === '8'
+      : seconds === 4 || seconds === 6 || seconds === 8
+
+  if (!isValid) {
+    throw new Error(
+      `Duration "${seconds}" is not supported by model "${model}". Supported durations: 4, 6, or 8 seconds`,
+    )
+  }
+}
+
+export function validateHighResDuration(
+  model: string,
+  size: string | undefined,
+  seconds: number | string | undefined,
+): void {
+  if (!size || !isHighResVideoSize(size)) return
+
+  const asNumber =
+    seconds === undefined
+      ? undefined
+      : typeof seconds === 'string'
+        ? Number(seconds)
+        : seconds
+
+  if (asNumber !== undefined && asNumber !== 8) {
+    throw new Error(
+      `Model "${model}" requires 8 second clips at 1080p and 4K. Received duration ${seconds}.`,
+    )
+  }
+}
+
+export function toApiSeconds(
+  seconds: number | string | undefined,
+): LovableVideoSeconds | undefined {
+  if (seconds === undefined) return undefined
+  return String(seconds) as LovableVideoSeconds
+}