@tanstack/ai-fal 1.0.1 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/dist/esm/adapters/audio.d.ts +1 -0
  2. package/dist/esm/adapters/audio.js +10 -5
  3. package/dist/esm/adapters/audio.js.map +1 -1
  4. package/dist/esm/adapters/files.d.ts +1 -0
  5. package/dist/esm/adapters/files.js +4 -4
  6. package/dist/esm/adapters/files.js.map +1 -1
  7. package/dist/esm/adapters/image.d.ts +1 -0
  8. package/dist/esm/adapters/image.js +10 -5
  9. package/dist/esm/adapters/image.js.map +1 -1
  10. package/dist/esm/adapters/speech.d.ts +1 -0
  11. package/dist/esm/adapters/speech.js +13 -8
  12. package/dist/esm/adapters/speech.js.map +1 -1
  13. package/dist/esm/adapters/transcription.d.ts +1 -0
  14. package/dist/esm/adapters/transcription.js +10 -5
  15. package/dist/esm/adapters/transcription.js.map +1 -1
  16. package/dist/esm/adapters/video.d.ts +14 -2
  17. package/dist/esm/adapters/video.js +24 -9
  18. package/dist/esm/adapters/video.js.map +1 -1
  19. package/dist/esm/client/index.d.ts +65 -0
  20. package/dist/esm/client/index.js +307 -0
  21. package/dist/esm/client/index.js.map +1 -0
  22. package/dist/esm/index.d.ts +2 -1
  23. package/dist/esm/index.js +2 -1
  24. package/dist/esm/utils/client.d.ts +10 -1
  25. package/dist/esm/utils/client.js +13 -7
  26. package/dist/esm/utils/client.js.map +1 -1
  27. package/dist/esm/utils/configure.d.ts +12 -0
  28. package/dist/esm/utils/configure.js +20 -0
  29. package/dist/esm/utils/configure.js.map +1 -0
  30. package/dist/esm/utils/index.d.ts +2 -1
  31. package/package.json +5 -4
  32. package/src/adapters/audio.ts +15 -5
  33. package/src/adapters/files.ts +5 -4
  34. package/src/adapters/image.ts +16 -6
  35. package/src/adapters/speech.ts +21 -7
  36. package/src/adapters/transcription.ts +16 -6
  37. package/src/adapters/video.ts +35 -10
  38. package/src/client/index.ts +456 -0
  39. package/src/index.ts +1 -1
  40. package/src/utils/client.ts +12 -4
  41. package/src/utils/configure.ts +17 -0
  42. package/src/utils/index.ts +2 -1
@@ -1,7 +1,6 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { BaseAudioAdapter } from '@tanstack/ai/adapters'
3
2
  import {
4
- configureFalClient,
3
+ createAdapterFalClient,
5
4
  deriveAudioContentType,
6
5
  generateId as utilGenerateId,
7
6
  } from '../utils/client'
@@ -12,6 +11,7 @@ import type {
12
11
  AudioGenerationResult,
13
12
  } from '@tanstack/ai'
14
13
  import type { FalClientConfig } from '../utils/client'
14
+ import type { FalClient } from '../client/index'
15
15
  import type { FalModel, FalModelInput } from '../model-meta'
16
16
 
17
17
  /**
@@ -68,10 +68,11 @@ export class FalAudioAdapter<TModel extends FalModel> extends BaseAudioAdapter<
68
68
  FalAudioProviderOptions<TModel>
69
69
  > {
70
70
  readonly name = 'fal' as const
71
+ private readonly client: FalClient
71
72
 
72
73
  constructor(model: TModel, config?: FalClientConfig) {
73
74
  super(model, {})
74
- configureFalClient(config)
75
+ this.client = createAdapterFalClient(config)
75
76
  }
76
77
 
77
78
  async generateAudio(
@@ -82,15 +83,24 @@ export class FalAudioAdapter<TModel extends FalModel> extends BaseAudioAdapter<
82
83
  provider: 'fal',
83
84
  model: this.model,
84
85
  })
86
+ let requestId: string | undefined
85
87
  try {
86
88
  const input = this.buildInput(options)
87
- // Request-specific abortSignal only — not fal.config() (global).
88
- const result = await fal.subscribe(this.model, {
89
+ // Pass the abortSignal per request, not in the client config.
90
+ const result = await this.client.subscribe(this.model, {
89
91
  input,
90
92
  ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
93
+ onEnqueue: (id) => {
94
+ requestId = id
95
+ },
91
96
  })
92
97
  return this.transformResponse(result)
93
98
  } catch (error) {
99
+ // The SDK stops waiting on abort but leaves the queued job running.
100
+ // Cancel it so it stops billing.
101
+ if (requestId && options.abortSignal?.aborted) {
102
+ this.client.queue.cancel(this.model, { requestId }).catch(() => {})
103
+ }
94
104
  logger.errors('fal.generateAudio fatal', {
95
105
  error,
96
106
  source: 'fal.generateAudio',
@@ -1,12 +1,12 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import {
3
2
  BaseFilesAdapter,
4
3
  normalizeFileUploadInput,
5
4
  } from '@tanstack/ai/adapters'
6
- import { configureFalClient } from '../utils/client'
5
+ import { createAdapterFalClient } from '../utils/client'
7
6
  import type { StorageSettings } from '@fal-ai/client'
8
7
  import type { FileHandle, FileUploadInput } from '@tanstack/ai/adapters'
9
8
  import type { FalClientConfig } from '../utils/client'
9
+ import type { FalClient } from '../client/index'
10
10
 
11
11
  export interface FalFilesConfig extends FalClientConfig {
12
12
  /**
@@ -25,17 +25,18 @@ export interface FalFilesConfig extends FalClientConfig {
25
25
  */
26
26
  export class FalFilesAdapter extends BaseFilesAdapter<'fal'> {
27
27
  readonly name = 'fal' as const
28
+ private readonly client: FalClient
28
29
  private readonly expiresIn?: StorageSettings['expiresIn']
29
30
 
30
31
  constructor(config?: FalFilesConfig) {
31
32
  super()
32
- configureFalClient(config)
33
+ this.client = createAdapterFalClient(config)
33
34
  this.expiresIn = config?.expiresIn
34
35
  }
35
36
 
36
37
  async upload(input: FileUploadInput): Promise<FileHandle<'fal'>> {
37
38
  const { blob, mimeType } = normalizeFileUploadInput(input)
38
- const url = await fal.storage.upload(
39
+ const url = await this.client.storage.upload(
39
40
  blob,
40
41
  this.expiresIn !== undefined
41
42
  ? { lifecycle: { expiresIn: this.expiresIn } }
@@ -1,8 +1,7 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { resolveMediaPrompt } from '@tanstack/ai'
3
2
  import { BaseImageAdapter } from '@tanstack/ai/adapters'
4
3
  import {
5
- configureFalClient,
4
+ createAdapterFalClient,
6
5
  generateId as utilGenerateId,
7
6
  } from '../utils/client'
8
7
  import { buildFalUsage, takeBillableUnits } from '../utils/billing'
@@ -10,6 +9,7 @@ import { mapSizeToFalFormat } from '../image/image-provider-options'
10
9
  import { mapImageInputsToFalFields } from '../image/image-inputs'
11
10
  import type { OutputType, Result } from '@fal-ai/client'
12
11
  import type { FalClientConfig } from '../utils/client'
12
+ import type { FalClient } from '../client/index'
13
13
  import type {
14
14
  GeneratedImage,
15
15
  ImageGenerationOptions,
@@ -53,12 +53,13 @@ export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
53
53
  > {
54
54
  override readonly kind = 'image' as const
55
55
  readonly name = 'fal' as const
56
+ private readonly client: FalClient
56
57
  // Consumes fal storage URLs uploaded via falFiles().
57
58
  override readonly supportsFileSources = true
58
59
 
59
60
  constructor(model: TModel, config?: FalClientConfig) {
60
61
  super(model, {})
61
- configureFalClient(config)
62
+ this.client = createAdapterFalClient(config)
62
63
  }
63
64
 
64
65
  async generateImages(
@@ -87,16 +88,25 @@ export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
87
88
  )
88
89
  }
89
90
 
91
+ let requestId: string | undefined
90
92
  try {
91
93
  const input = this.buildInput(options, resolved)
92
- // Pass request-specific abortSignal only — never via fal.config(), which
93
- // is global and would cancel concurrent generations from other calls.
94
- const result = await fal.subscribe(this.model, {
94
+ // Pass the abortSignal per request, not in the client config, so it
95
+ // cannot cancel other generations.
96
+ const result = await this.client.subscribe(this.model, {
95
97
  input,
96
98
  ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
99
+ onEnqueue: (id) => {
100
+ requestId = id
101
+ },
97
102
  })
98
103
  return this.transformResponse(result)
99
104
  } catch (error) {
105
+ // The SDK stops waiting on abort but leaves the queued job running.
106
+ // Cancel it so it stops billing.
107
+ if (requestId && options.abortSignal?.aborted) {
108
+ this.client.queue.cancel(this.model, { requestId }).catch(() => {})
109
+ }
100
110
  logger.errors('fal.generateImage fatal', {
101
111
  error,
102
112
  source: 'fal.generateImage',
@@ -1,8 +1,7 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { BaseTTSAdapter } from '@tanstack/ai/adapters'
3
2
  import {
4
3
  arrayBufferToBase64,
5
- configureFalClient,
4
+ createAdapterFalClient,
6
5
  extractUrlExtension,
7
6
  generateId as utilGenerateId,
8
7
  } from '../utils/client'
@@ -10,6 +9,7 @@ import { buildFalUsage, takeBillableUnits } from '../utils/billing'
10
9
  import type { OutputType, Result } from '@fal-ai/client'
11
10
  import type { TTSOptions, TTSResult } from '@tanstack/ai'
12
11
  import type { FalClientConfig } from '../utils/client'
12
+ import type { FalClient } from '../client/index'
13
13
  import type { FalModel, FalModelInput } from '../model-meta'
14
14
 
15
15
  /**
@@ -40,10 +40,11 @@ export class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<
40
40
  FalSpeechProviderOptions<TModel>
41
41
  > {
42
42
  readonly name = 'fal' as const
43
+ private readonly client: FalClient
43
44
 
44
45
  constructor(model: TModel, config?: FalClientConfig) {
45
46
  super(model, {})
46
- configureFalClient(config)
47
+ this.client = createAdapterFalClient(config)
47
48
  }
48
49
 
49
50
  async generateSpeech(
@@ -54,15 +55,24 @@ export class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<
54
55
  provider: 'fal',
55
56
  model: this.model,
56
57
  })
58
+ let requestId: string | undefined
57
59
  try {
58
60
  const input = this.buildInput(options)
59
- // Request-specific abortSignal only — not fal.config() (global).
60
- const result = await fal.subscribe(this.model, {
61
+ // Pass the abortSignal per request, not in the client config.
62
+ const result = await this.client.subscribe(this.model, {
61
63
  input,
62
64
  ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
65
+ onEnqueue: (id) => {
66
+ requestId = id
67
+ },
63
68
  })
64
- return await this.transformResponse(result)
69
+ return await this.transformResponse(result, options.abortSignal)
65
70
  } catch (error) {
71
+ // The SDK stops waiting on abort but leaves the queued job running.
72
+ // Cancel it so it stops billing.
73
+ if (requestId && options.abortSignal?.aborted) {
74
+ this.client.queue.cancel(this.model, { requestId }).catch(() => {})
75
+ }
66
76
  logger.errors('fal.generateSpeech fatal', {
67
77
  error,
68
78
  source: 'fal.generateSpeech',
@@ -91,6 +101,7 @@ export class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<
91
101
 
92
102
  private async transformResponse(
93
103
  response: Result<OutputType<TModel>>,
104
+ abortSignal: AbortSignal | undefined,
94
105
  ): Promise<TTSResult> {
95
106
  const data = response.data as Record<string, unknown>
96
107
 
@@ -117,7 +128,10 @@ export class FalSpeechAdapter<TModel extends FalModel> extends BaseTTSAdapter<
117
128
  // Fetch the audio and convert to base64 to match TTSResult contract.
118
129
  // Using a chunked helper here — spreading Uint8Array into btoa exceeds
119
130
  // V8's argument limit (~65k) for any realistic TTS clip.
120
- const audioResponse = await fetch(audioUrl)
131
+ const audioResponse = await fetch(
132
+ audioUrl,
133
+ abortSignal ? { signal: abortSignal } : undefined,
134
+ )
121
135
  if (!audioResponse.ok) {
122
136
  throw new Error(
123
137
  `Failed to fetch audio from ${audioUrl}: ${audioResponse.status} ${audioResponse.statusText}`,
@@ -1,7 +1,6 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'
3
2
  import {
4
- configureFalClient,
3
+ createAdapterFalClient,
5
4
  dataUrlToBlob,
6
5
  generateId as utilGenerateId,
7
6
  } from '../utils/client'
@@ -13,6 +12,7 @@ import type {
13
12
  TranscriptionSegment,
14
13
  } from '@tanstack/ai'
15
14
  import type { FalClientConfig } from '../utils/client'
15
+ import type { FalClient } from '../client/index'
16
16
  import type { FalModel, FalModelInput } from '../model-meta'
17
17
 
18
18
  /**
@@ -51,10 +51,11 @@ export class FalTranscriptionAdapter<
51
51
  FalTranscriptionProviderOptions<TModel>
52
52
  > {
53
53
  readonly name = 'fal' as const
54
+ private readonly client: FalClient
54
55
 
55
56
  constructor(model: TModel, config?: FalClientConfig) {
56
57
  super(model, {})
57
- configureFalClient(config)
58
+ this.client = createAdapterFalClient(config)
58
59
  }
59
60
 
60
61
  async transcribe(
@@ -68,15 +69,24 @@ export class FalTranscriptionAdapter<
68
69
  model: this.model,
69
70
  },
70
71
  )
72
+ let requestId: string | undefined
71
73
  try {
72
74
  const input = this.buildInput(options)
73
- // Request-specific abortSignal only — not fal.config() (global).
74
- const result = await fal.subscribe(this.model, {
75
+ // Pass the abortSignal per request, not in the client config.
76
+ const result = await this.client.subscribe(this.model, {
75
77
  input,
76
78
  ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
79
+ onEnqueue: (id) => {
80
+ requestId = id
81
+ },
77
82
  })
78
83
  return this.transformResponse(result)
79
84
  } catch (error) {
85
+ // The SDK stops waiting on abort but leaves the queued job running.
86
+ // Cancel it so it stops billing.
87
+ if (requestId && options.abortSignal?.aborted) {
88
+ this.client.queue.cancel(this.model, { requestId }).catch(() => {})
89
+ }
80
90
  logger.errors('fal.generateTranscription fatal', {
81
91
  error,
82
92
  source: 'fal.generateTranscription',
@@ -88,7 +98,7 @@ export class FalTranscriptionAdapter<
88
98
  private buildInput(
89
99
  options: TranscriptionOptions<FalTranscriptionProviderOptions<TModel>>,
90
100
  ): FalModelInput<TModel> {
91
- // fal-client auto-uploads Blob/File inputs via fal.storage.upload, but
101
+ // The fal client auto-uploads Blob/File inputs via storage.upload, but
92
102
  // passes strings through unchanged — so a `data:` URL would reach fal's
93
103
  // API and get rejected with a 422 "Unsupported data URL". Decode data
94
104
  // URLs to a Blob up front so the auto-upload path handles them.
@@ -1,8 +1,7 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { resolveMediaPrompt } from '@tanstack/ai'
3
2
  import { BaseVideoAdapter } from '@tanstack/ai/adapters'
4
3
  import {
5
- configureFalClient,
4
+ createAdapterFalClient,
6
5
  generateId as utilGenerateId,
7
6
  } from '../utils/client'
8
7
  import { buildFalUsage, takeBillableUnits } from '../utils/billing'
@@ -33,6 +32,7 @@ import type {
33
32
  FalVideoProviderOptions,
34
33
  } from '../model-meta'
35
34
  import type { FalClientConfig } from '../utils/client'
35
+ import type { FalClient } from '../client/index'
36
36
 
37
37
  /**
38
38
  * Map video conditioning inputs onto fal field names.
@@ -138,12 +138,13 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
138
138
  > {
139
139
  override readonly kind = 'video' as const
140
140
  readonly name = 'fal' as const
141
+ private readonly client: FalClient
141
142
  // Consumes fal storage URLs uploaded via falFiles().
142
143
  override readonly supportsFileSources = true
143
144
 
144
145
  constructor(model: TModel, config?: FalClientConfig) {
145
146
  super({}, model)
146
- configureFalClient(config)
147
+ this.client = createAdapterFalClient(config)
147
148
  }
148
149
 
149
150
  async createVideoJob(
@@ -184,9 +185,9 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
184
185
  ...(duration !== undefined ? { duration } : {}),
185
186
  } as FalModelInput<TModel>
186
187
 
187
- // Submit to queue and get request ID. Request-specific abortSignal only —
188
- // never via fal.config() (global; would cancel concurrent jobs).
189
- const { request_id } = await fal.queue.submit(this.model, {
188
+ // Submit to the queue and get the request ID. Pass the abortSignal per
189
+ // request, not in the client config, so it cannot cancel other jobs.
190
+ const { request_id } = await this.client.queue.submit(this.model, {
190
191
  input,
191
192
  ...(options.abortSignal ? { abortSignal: options.abortSignal } : {}),
192
193
  })
@@ -210,10 +211,28 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
210
211
  return getFalVideoDurationOptions(this.model)
211
212
  }
212
213
 
213
- async getVideoStatus(jobId: string): Promise<VideoStatusResult> {
214
- const statusResponse = (await fal.queue.status(this.model, {
214
+ /**
215
+ * Cancels a queued request with the fal queue cancel endpoint. fal can refuse when the
216
+ * request already runs, and then this rejects.
217
+ */
218
+ async cancelVideoJob(
219
+ jobId: string,
220
+ options?: { abortSignal?: AbortSignal },
221
+ ): Promise<void> {
222
+ await this.client.queue.cancel(this.model, {
223
+ requestId: jobId,
224
+ ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
225
+ })
226
+ }
227
+
228
+ async getVideoStatus(
229
+ jobId: string,
230
+ options?: { abortSignal?: AbortSignal },
231
+ ): Promise<VideoStatusResult> {
232
+ const statusResponse = (await this.client.queue.status(this.model, {
215
233
  requestId: jobId,
216
234
  logs: true,
235
+ ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
217
236
  })) as FalStatusResponse
218
237
 
219
238
  return {
@@ -227,13 +246,19 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
227
246
  }
228
247
  }
229
248
 
230
- override async getVideo(jobId: string): Promise<VideoUrlResult> {
249
+ override async getVideo(
250
+ jobId: string,
251
+ options?: { abortSignal?: AbortSignal },
252
+ ): Promise<VideoUrlResult> {
231
253
  let result
232
254
  try {
233
- result = await fal.queue.result(this.model, {
255
+ result = await this.client.queue.result(this.model, {
234
256
  requestId: jobId,
257
+ ...(options?.abortSignal ? { abortSignal: options.abortSignal } : {}),
235
258
  })
236
259
  } catch (error: unknown) {
260
+ // A cancelled call is not a provider failure: keep the abort error.
261
+ if (options?.abortSignal?.aborted) throw error
237
262
  // fal.ai may report COMPLETED status but throw on result fetch
238
263
  // (e.g. 422 validation errors). Extract the detailed error info.
239
264
  const err = error as { body?: { detail?: unknown }; message?: string }