Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

server-fns.ts

493 lines15.0 KB

1import { createServerFn } from '@tanstack/react-start'
2import { z } from 'zod'
3import {
4 chat,
5 generateAudio,
6 generateImage,
7 generateSpeech,
8 generateTranscription,
9 generateVideo,
10 getVideoJobStatus,
11 memoryStream,
12 replayRunStream,
13 summarize,
14 toServerSentEventsResponse,
15} from '@tanstack/ai'
16import {
17 getGenerationHydration,
18 withGenerationPersistence,
19} from '@tanstack/ai-persistence'
20import { openaiSummarize, openaiText } from '@tanstack/ai-openai'
21import { grokImage, grokVideo } from '@tanstack/ai-grok'
22import type { UIMessage } from '@tanstack/ai'
23import {
24 InvalidModelOverrideError,
25 UnknownProviderError,
26 buildAudioAdapter,
27 buildSpeechAdapter,
28 buildTranscriptionAdapter,
29} from './server-audio-adapters'
30import {
31 artifactServeUrl,
32 generationServerPersistence,
33} from './generation-server-store'
34​
35/**
36 * Server-fn error with a stable `code` property clients can switch on.
37 *
38 * TanStack Start's `createServerFn` surfaces thrown errors as a generic 500
39 * without a structured payload. We can't influence the status code from here,
40 * so we attach a `code` field the client can read to distinguish well-known
41 * failure modes (invalid_model_override, unknown_provider) from truly
42 * unexpected errors.
43 */
44class ServerFnError extends Error {
45 readonly code: string
46 readonly details?: Record<string, unknown>
47​
48 constructor(
49 code: string,
50 message: string,
51 details?: Record<string, unknown>,
52 ) {
53 super(message)
54 this.name = 'ServerFnError'
55 this.code = code
56 this.details = details
57 }
59​
60/**
61 * Translate the typed audio-adapter errors into a `ServerFnError` with a stable
62 * `code`. Any other error is re-thrown untouched so the framework's default
63 * 500 path handles it.
64 */
65function rethrowAudioAdapterError(err: unknown): never {
66 if (err instanceof InvalidModelOverrideError) {
67 throw new ServerFnError('invalid_model_override', err.message, {
68 providerId: err.providerId,
69 requestedModel: err.requestedModel,
70 allowedModels: err.allowedModels,
71 })
72 }
73 if (err instanceof UnknownProviderError) {
74 throw new ServerFnError('unknown_provider', err.message, {
75 providerId: err.providerId,
76 allowedProviders: err.allowedProviders,
77 })
78 }
79 throw err
81​
82const SPEECH_PROVIDER_SCHEMA = z
83 .enum(['openai', 'gemini', 'fal', 'grok', 'elevenlabs', 'byteplus'])
84 .optional()
85​
86const TRANSCRIPTION_PROVIDER_SCHEMA = z
87 .enum(['openai', 'openai-diarize', 'fal', 'grok', 'elevenlabs', 'byteplus'])
88 .optional()
89​
90const TRANSCRIPTION_RESPONSE_FORMAT_SCHEMA = z
91 .enum(['json', 'text', 'srt', 'verbose_json', 'vtt'])
92 .optional()
93​
94const AUDIO_PROVIDER_SCHEMA = z
95 .enum([
96 'gemini-lyria',
97 'fal-audio',
98 'fal-sfx',
99 'elevenlabs-music',
100 'elevenlabs-sfx',
101 ])
102 .optional()
103​
104// =============================================================================
105// Image generation — server-driven persistence (direct + streaming server fns)
106// =============================================================================
107//
108// Same stores as `/api/generate/image` (`generationServerPersistence` +
109// `/api/artifacts`). Direct and streaming server-fn modes have no GET route, so
110// the client supplies `hydrateGeneration` / `joinRun` via the companion
111// functions below. See docs/persistence/generation-persistence.md.
112​
113const imageGenerateInputSchema = z.object({
114 prompt: z.string(),
115 numberOfImages: z.number().optional(),
116 size: z.string().optional(),
117 // Required: the slot successive runs are filed under for hydration.
118 threadId: z.string().min(1),
119})
120​
121function imagePersistenceMiddleware() {
122 return withGenerationPersistence(generationServerPersistence(), {
123 artifactUrl: (ref) => artifactServeUrl(ref.artifactId),
124 })
126​
127// =============================================================================
128// Direct server functions (non-streaming, return the result directly)
129// =============================================================================
130​
131export const generateImageFn = createServerFn({ method: 'POST' })
132 .inputValidator(imageGenerateInputSchema)
133 .handler(async ({ data }) => {
134 return generateImage({
135 adapter: grokImage('grok-imagine-image'),
136 prompt: data.prompt,
137 numberOfImages: data.numberOfImages,
138 size: data.size as any,
139 threadId: data.threadId,
140 middleware: [imagePersistenceMiddleware()],
141 })
142 })
143​
144export const generateSpeechFn = createServerFn({ method: 'POST' })
145 .inputValidator(
146 z.object({
147 text: z.string(),
148 voice: z.string().optional(),
149 format: z.enum(['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm']).optional(),
150 provider: SPEECH_PROVIDER_SCHEMA,
151 }),
152 )
153 .handler(async ({ data }) => {
154 // `buildSpeechAdapter` can throw `UnknownProviderError` (defense-in-depth;
155 // Zod should catch this first). Translate into a `ServerFnError` so
156 // clients can distinguish it from a generic failure via the stable `code`.
157 let adapter
158 try {
159 adapter = buildSpeechAdapter(data.provider ?? 'openai')
160 } catch (err) {
161 rethrowAudioAdapterError(err)
162 }
163 return generateSpeech({
164 adapter,
165 text: data.text,
166 voice: data.voice,
167 format: data.format,
168 })
169 })
170​
171export const transcribeFn = createServerFn({ method: 'POST' })
172 .inputValidator(
173 z.object({
174 audio: z.string(),
175 language: z.string().optional(),
176 responseFormat: TRANSCRIPTION_RESPONSE_FORMAT_SCHEMA,
177 modelOptions: z.record(z.string(), z.any()).optional(),
178 provider: TRANSCRIPTION_PROVIDER_SCHEMA,
179 }),
180 )
181 .handler(async ({ data }) => {
182 // `buildTranscriptionAdapter` can throw `UnknownProviderError`
183 // (defense-in-depth; Zod should catch this first). Translate into a
184 // `ServerFnError` so clients can distinguish it from a generic failure
185 // via the stable `code`.
186 let adapter
187 try {
188 adapter = buildTranscriptionAdapter(data.provider ?? 'openai')
189 } catch (err) {
190 rethrowAudioAdapterError(err)
191 }
192 return generateTranscription({
193 adapter,
194 audio: data.audio,
195 language: data.language,
196 responseFormat: data.responseFormat,
197 modelOptions: data.modelOptions,
198 })
199 })
200​
201export const generateAudioFn = createServerFn({ method: 'POST' })
202 .inputValidator(
203 z.object({
204 prompt: z.string(),
205 duration: z.number().optional(),
206 provider: AUDIO_PROVIDER_SCHEMA,
207 model: z.string().optional(),
208 }),
209 )
210 .handler(async ({ data }) => {
211 // `buildAudioAdapter` can throw `InvalidModelOverrideError` (unknown
212 // model id) or `UnknownProviderError` (defense-in-depth; Zod should
213 // catch this first). Translate both into a `ServerFnError` so clients
214 // can distinguish them from a generic failure via the stable `code`.
215 let adapter
216 try {
217 adapter = buildAudioAdapter(data.provider ?? 'gemini-lyria', data.model)
218 } catch (err) {
219 rethrowAudioAdapterError(err)
220 }
221 return generateAudio({
222 adapter,
223 prompt: data.prompt,
224 duration: data.duration,
225 })
226 })
227​
228export const summarizeFn = createServerFn({ method: 'POST' })
229 .inputValidator(
230 z.object({
231 text: z.string(),
232 maxLength: z.number().optional(),
233 style: z.enum(['bullet-points', 'paragraph', 'concise']).optional(),
234 model: z.string().optional(),
235 }),
236 )
237 .handler(async ({ data }) => {
238 return summarize({
239 adapter: openaiSummarize((data.model ?? 'gpt-4o-mini') as 'gpt-4o-mini'),
240 text: data.text,
241 maxLength: data.maxLength,
242 style: data.style,
243 })
244 })
245​
246export const generateVideoFn = createServerFn({ method: 'POST' })
247 .inputValidator(
248 z.object({
249 prompt: z.string(),
250 size: z.string().optional(),
251 duration: z.number().optional(),
252 }),
253 )
254 .handler(async ({ data }) => {
255 const adapter = grokVideo('grok-imagine-video')
256​
257 // Create the job
258 const { jobId } = await generateVideo({
259 adapter,
260 prompt: data.prompt,
261 size: data.size as any,
262 duration: data.duration,
263 })
264​
265 // Poll until complete (max 10 minutes)
266 const MAX_POLLS = 120
267 let polls = 0
268 let status = await getVideoJobStatus({ adapter, jobId })
269 while (status.status !== 'completed' && status.status !== 'failed') {
270 if (++polls > MAX_POLLS) {
271 throw new Error('Video generation timed out')
272 }
273 await new Promise((r) => setTimeout(r, 5000))
274 status = await getVideoJobStatus({ adapter, jobId })
275 }
276​
277 if (status.status === 'failed') {
278 throw new Error(status.error || 'Video generation failed')
279 }
280​
281 if (!status.url) {
282 throw new Error('Video generation completed but no URL was provided')
283 }
284​
285 return {
286 jobId,
287 status: 'completed' as const,
288 url: status.url,
289 }
290 })
291​
292// =============================================================================
293// Streaming server functions (return SSE Response for client-side parsing)
294// Used with: fetchServerSentEvents((input) => streamFn({ data: input }))
295// =============================================================================
296​
297export const generateImageStreamFn = createServerFn({ method: 'POST' })
298 .inputValidator(imageGenerateInputSchema)
299 .handler(({ data }) => {
300 // One run id for the durability log and the run record so join can replay
301 // exactly the run hydration reports.
302 const runId = crypto.randomUUID()
303 const stream = generateImage({
304 adapter: grokImage('grok-imagine-image'),
305 prompt: data.prompt,
306 numberOfImages: data.numberOfImages,
307 size: data.size as any,
308 threadId: data.threadId,
309 runId,
310 stream: true,
311 middleware: [imagePersistenceMiddleware()],
312 })
313 return toServerSentEventsResponse(stream, {
314 durability: { adapter: memoryStream({ runId }) },
315 })
316 })
317​
318/**
319 * Wire shape for mount hydration. Parsed with Zod so:
320 * - TanStack Start gets a JSON-serializable return type (no `unknown`)
321 * - the store's loose `result` is validated before it crosses the wire
322 */
323const generationHydrationSchema = z.object({
324 resumeSnapshot: z
325 .object({
326 schemaVersion: z.literal(1),
327 resumeState: z
328 .object({
329 threadId: z.string(),
330 runId: z.string(),
331 })
332 .nullable(),
333 status: z.enum(['idle', 'running', 'complete', 'error']),
334 // `z.any()` (not `z.unknown()`) so Start's serializer accepts the values.
335 result: z.record(z.string(), z.any()).optional(),
336 error: z
337 .object({
338 message: z.string(),
339 code: z.string().optional(),
340 })
341 .optional(),
342 activity: z.string().optional(),
343 })
344 .nullable(),
345 activeRun: z.object({ runId: z.string() }).nullable(),
346})
347​
348/** Mount hydration for image `persistence: true` over a fetcher (no GET route). */
349export const getImageHydrationFn = createServerFn({ method: 'GET' })
350 .inputValidator(z.string().min(1))
351 .handler(async ({ data: threadId }) => {
352 // No auth in this single-user demo — gate on session in a multi-user app.
353 return generationHydrationSchema.parse(
354 await getGenerationHydration(generationServerPersistence(), threadId),
355 )
356 })
357​
358/**
359 * Rejoin an in-flight image run over a server function (replay + live tail).
360 * Returns an SSE `Response` — the client parses it the same way
361 * `generateImageStreamFn` does (see `chunksFromSseResponse` on the page).
362 */
363export const joinImageRunFn = createServerFn({ method: 'GET' })
364 .inputValidator(z.string().min(1))
365 .handler(({ data: runId }) =>
366 toServerSentEventsResponse(replayRunStream(memoryStream({ runId }))),
367 )
368​
369export const generateSpeechStreamFn = createServerFn({ method: 'POST' })
370 .inputValidator(
371 z.object({
372 text: z.string(),
373 voice: z.string().optional(),
374 format: z.enum(['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm']).optional(),
375 provider: SPEECH_PROVIDER_SCHEMA,
376 }),
377 )
378 .handler(({ data }) => {
379 // `buildSpeechAdapter` can throw `UnknownProviderError` (defense-in-depth;
380 // Zod should catch this first). Translate into a `ServerFnError` so
381 // clients can distinguish it from a generic failure via the stable `code`.
382 let adapter
383 try {
384 adapter = buildSpeechAdapter(data.provider ?? 'openai')
385 } catch (err) {
386 rethrowAudioAdapterError(err)
387 }
388 return toServerSentEventsResponse(
389 generateSpeech({
390 adapter,
391 text: data.text,
392 voice: data.voice,
393 format: data.format,
394 stream: true,
395 }),
396 )
397 })
398​
399export const transcribeStreamFn = createServerFn({ method: 'POST' })
400 .inputValidator(
401 z.object({
402 audio: z.string(),
403 language: z.string().optional(),
404 responseFormat: TRANSCRIPTION_RESPONSE_FORMAT_SCHEMA,
405 modelOptions: z.record(z.string(), z.any()).optional(),
406 provider: TRANSCRIPTION_PROVIDER_SCHEMA,
407 }),
408 )
409 .handler(({ data }) => {
410 // `buildTranscriptionAdapter` can throw `UnknownProviderError`
411 // (defense-in-depth; Zod should catch this first). Translate into a
412 // `ServerFnError` so clients can distinguish it from a generic failure
413 // via the stable `code`.
414 let adapter
415 try {
416 adapter = buildTranscriptionAdapter(data.provider ?? 'openai')
417 } catch (err) {
418 rethrowAudioAdapterError(err)
419 }
420 return toServerSentEventsResponse(
421 generateTranscription({
422 adapter,
423 audio: data.audio,
424 language: data.language,
425 responseFormat: data.responseFormat,
426 modelOptions: data.modelOptions,
427 stream: true,
428 }),
429 )
430 })
431​
432export const summarizeStreamFn = createServerFn({ method: 'POST' })
433 .inputValidator(
434 z.object({
435 text: z.string(),
436 maxLength: z.number().optional(),
437 style: z.enum(['bullet-points', 'paragraph', 'concise']).optional(),
438 model: z.string().optional(),
439 }),
440 )
441 .handler(({ data }) => {
442 return toServerSentEventsResponse(
443 summarize({
444 adapter: openaiSummarize(
445 (data.model ?? 'gpt-4o-mini') as 'gpt-4o-mini',
446 ),
447 text: data.text,
448 maxLength: data.maxLength,
449 style: data.style,
450 stream: true,
451 }),
452 )
453 })
454​
455export const generateVideoStreamFn = createServerFn({ method: 'POST' })
456 .inputValidator(
457 z.object({
458 prompt: z.string(),
459 size: z.string().optional(),
460 duration: z.number().optional(),
461 }),
462 )
463 .handler(({ data }) => {
464 return toServerSentEventsResponse(
465 generateVideo({
466 adapter: grokVideo('grok-imagine-video'),
467 prompt: data.prompt,
468 size: data.size as any,
469 duration: data.duration,
470 stream: true,
471 }),
472 )
473 })
474​
475// =============================================================================
476// Chat server function — pairs with useChat({ fetcher })
477// =============================================================================
478​
479export const chatFn = createServerFn({ method: 'POST' })
480 .inputValidator(
481 (data: { messages: Array<UIMessage>; data?: Record<string, any> }) => data,
482 )
483 .handler(({ data }) =>
484 toServerSentEventsResponse(
485 chat({
486 adapter: openaiText('gpt-5.2'),
487 messages: data.messages as any,
488 systemPrompts: [
489 'You are a helpful assistant. Keep replies short and friendly.',
490 ],
491 }),
492 ),
493 )