@tanstack/ai-fal 1.1.0 → 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 +5 -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 +5 -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 +5 -5
  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 +5 -5
  15. package/dist/esm/adapters/transcription.js.map +1 -1
  16. package/dist/esm/adapters/video.d.ts +2 -1
  17. package/dist/esm/adapters/video.js +8 -8
  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 +7 -6
  33. package/src/adapters/files.ts +5 -4
  34. package/src/adapters/image.ts +8 -7
  35. package/src/adapters/speech.ts +7 -6
  36. package/src/adapters/transcription.ts +8 -7
  37. package/src/adapters/video.ts +11 -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
@@ -0,0 +1,456 @@
1
+ import type {
2
+ FalClient as SdkFalClient,
3
+ QueueClient,
4
+ StorageClient,
5
+ StorageSettings,
6
+ ValidationErrorInfo,
7
+ } from '@fal-ai/client'
8
+
9
+ /**
10
+ * Config for {@link createFalClient}. These are the `@fal-ai/client` config
11
+ * fields this package uses.
12
+ */
13
+ export interface FalClientOptions {
14
+ /** Sent as `Authorization: Key <credentials>`. */
15
+ credentials: string
16
+ fetch: typeof fetch
17
+ /** In a browser, requests go here with the real URL in `x-fal-target-url`. */
18
+ proxyUrl?: string
19
+ }
20
+
21
+ /**
22
+ * The part of the `@fal-ai/client` client that the adapters call. A real SDK
23
+ * client also fits this type.
24
+ */
25
+ export type FalClient = Pick<SdkFalClient, 'subscribe'> & {
26
+ queue: Pick<QueueClient, 'submit' | 'status' | 'result' | 'cancel'>
27
+ storage: Pick<StorageClient, 'upload'>
28
+ }
29
+
30
+ interface ApiErrorArgs<Body> {
31
+ message: string
32
+ status: number
33
+ body?: Body
34
+ requestId?: string
35
+ timeoutType?: string
36
+ }
37
+
38
+ /**
39
+ * Thrown when fal answers with a status that is not OK. Same name and fields
40
+ * as the `@fal-ai/client` `ApiError`.
41
+ */
42
+ export class ApiError<Body = unknown> extends Error {
43
+ readonly status: number
44
+ readonly body: Body | undefined
45
+ readonly requestId: string
46
+ readonly timeoutType?: string
47
+
48
+ constructor({
49
+ message,
50
+ status,
51
+ body,
52
+ requestId,
53
+ timeoutType,
54
+ }: ApiErrorArgs<Body>) {
55
+ super(message)
56
+ this.name = 'ApiError'
57
+ this.status = status
58
+ this.body = body
59
+ this.requestId = requestId || ''
60
+ this.timeoutType = timeoutType
61
+ }
62
+
63
+ /** True when the request hit the timeout that the caller asked for. */
64
+ get isUserTimeout() {
65
+ return this.status === 504 && this.timeoutType === 'user'
66
+ }
67
+ }
68
+
69
+ /**
70
+ * Thrown for a 422 answer. Same name and fields as the `@fal-ai/client`
71
+ * `ValidationError`.
72
+ */
73
+ export class ValidationError extends ApiError<{
74
+ detail?: Array<ValidationErrorInfo> | string
75
+ }> {
76
+ constructor(
77
+ args: ApiErrorArgs<{ detail?: Array<ValidationErrorInfo> | string }>,
78
+ ) {
79
+ super(args)
80
+ this.name = 'ValidationError'
81
+ }
82
+
83
+ get fieldErrors(): Array<ValidationErrorInfo> {
84
+ const detail = this.body?.detail
85
+ if (typeof detail === 'string') {
86
+ return [{ loc: ['body'], msg: detail, type: 'value_error' }]
87
+ }
88
+ return detail || []
89
+ }
90
+
91
+ getFieldErrors(field: string) {
92
+ return this.fieldErrors.filter((error) => error.loc.at(-1) === field)
93
+ }
94
+ }
95
+
96
+ interface RetryPolicy {
97
+ maxRetries: number
98
+ maxDelay: number
99
+ statusCodes: Array<number>
100
+ }
101
+
102
+ const RETRYABLE_STATUS_CODES = [429, 502, 503, 504]
103
+ const DEFAULT_RETRY: RetryPolicy = {
104
+ maxRetries: 3,
105
+ maxDelay: 30_000,
106
+ statusCodes: RETRYABLE_STATUS_CODES,
107
+ }
108
+ const QUEUE_RETRY: RetryPolicy = { ...DEFAULT_RETRY, maxDelay: 60_000 }
109
+ const QUEUE_STATUS_RETRY: RetryPolicy = {
110
+ maxRetries: 5,
111
+ maxDelay: 30_000,
112
+ statusCodes: [...RETRYABLE_STATUS_CODES, 500],
113
+ }
114
+
115
+ const NETWORK_ERROR_CODES = new Set([
116
+ 'ECONNABORTED',
117
+ 'ECONNREFUSED',
118
+ 'ECONNRESET',
119
+ 'EAI_AGAIN',
120
+ 'EHOSTUNREACH',
121
+ 'ENETUNREACH',
122
+ 'ENOTFOUND',
123
+ 'EPIPE',
124
+ 'ETIMEDOUT',
125
+ 'UND_ERR_BODY_TIMEOUT',
126
+ 'UND_ERR_CONNECT_TIMEOUT',
127
+ 'UND_ERR_HEADERS_TIMEOUT',
128
+ 'UND_ERR_SOCKET',
129
+ ])
130
+
131
+ const POLL_INTERVAL_MS = 500
132
+ const MULTIPART_THRESHOLD_BYTES = 90 * 1024 * 1024
133
+ const UPLOAD_INITIATE_URL =
134
+ 'https://rest.fal.ai/storage/upload/initiate?storage_type=fal-cdn-v3'
135
+ const ENDPOINT_NAMESPACES = ['workflows', 'comfy']
136
+ const EXPIRATION_SECONDS: Record<string, number | undefined> = {
137
+ never: undefined,
138
+ immediate: 60,
139
+ '1h': 3600,
140
+ '1d': 86400,
141
+ '7d': 604800,
142
+ '30d': 2592000,
143
+ '1y': 31536000,
144
+ }
145
+
146
+ const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms))
147
+
148
+ const isBrowser = () =>
149
+ typeof window !== 'undefined' && typeof window.document !== 'undefined'
150
+
151
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
152
+ return !!value && Object.getPrototypeOf(value) === Object.prototype
153
+ }
154
+
155
+ /** Transport errors (reset, DNS, socket timeout) are retried. Aborts are not. */
156
+ function isNetworkError(error: unknown) {
157
+ const seen = new Set<unknown>()
158
+ let current = error
159
+ let hasNetworkCode = false
160
+ while (current && typeof current === 'object' && !seen.has(current)) {
161
+ seen.add(current)
162
+ const name = 'name' in current ? current.name : undefined
163
+ const code = 'code' in current ? current.code : undefined
164
+ if (name === 'AbortError' || name === 'TimeoutError') return false
165
+ if (typeof code === 'string' && NETWORK_ERROR_CODES.has(code)) {
166
+ hasNetworkCode = true
167
+ }
168
+ current = 'cause' in current ? current.cause : undefined
169
+ }
170
+ return (
171
+ hasNetworkCode ||
172
+ (error instanceof TypeError && /fetch failed/i.test(error.message))
173
+ )
174
+ }
175
+
176
+ function isRetryable(error: unknown, statusCodes: Array<number>) {
177
+ if (error instanceof ApiError) {
178
+ return !error.isUserTimeout && statusCodes.includes(error.status)
179
+ }
180
+ return isNetworkError(error)
181
+ }
182
+
183
+ /** Exponential backoff from 1 s, doubled per attempt, capped, with +-25% jitter. */
184
+ function backoffDelay(attempt: number, maxDelay: number) {
185
+ const delay = Math.min(1000 * 2 ** attempt, maxDelay)
186
+ return Math.max(0, delay + 0.25 * delay * (Math.random() * 2 - 1))
187
+ }
188
+
189
+ /** Reads a fal response, or throws `ApiError` / `ValidationError`. */
190
+ async function parseResponse(response: Response) {
191
+ const { status, statusText } = response
192
+ const contentType = response.headers.get('Content-Type') ?? ''
193
+ const requestId = response.headers.get('x-fal-request-id') || undefined
194
+ const timeoutType =
195
+ response.headers.get('x-fal-request-timeout-type') || undefined
196
+ const isJson = contentType.includes('application/json')
197
+ if (!response.ok) {
198
+ if (!isJson) {
199
+ throw new ApiError({
200
+ message: `HTTP ${status}: ${statusText}`,
201
+ status,
202
+ requestId,
203
+ timeoutType,
204
+ })
205
+ }
206
+ const body = await response.json()
207
+ const ErrorType = status === 422 ? ValidationError : ApiError
208
+ throw new ErrorType({
209
+ message: body.message || statusText,
210
+ status,
211
+ body,
212
+ requestId,
213
+ timeoutType,
214
+ })
215
+ }
216
+ if (isJson) return response.json()
217
+ if (contentType.includes('application/octet-stream')) {
218
+ return response.arrayBuffer()
219
+ }
220
+ return response.text()
221
+ }
222
+
223
+ /** `123-app` becomes `123/app`. Ids that already have a `/` stay as they are. */
224
+ function normalizeEndpointId(id: string) {
225
+ if (id.includes('/')) return id
226
+ const match = /^([0-9]+)-([a-zA-Z0-9-]+)$/.exec(id)
227
+ if (!match) {
228
+ throw new Error(
229
+ `Invalid app id: ${id}. Must be in the format <appOwner>/<appId>`,
230
+ )
231
+ }
232
+ return `${match[1]}/${match[2]}`
233
+ }
234
+
235
+ /** Status and result URLs use only `[namespace/]owner/alias`, not the subpath. */
236
+ function queueAppId(endpointId: string) {
237
+ const parts = normalizeEndpointId(endpointId).split('/')
238
+ const hasNamespace = ENDPOINT_NAMESPACES.includes(parts[0] ?? '')
239
+ const [owner, alias] = hasNamespace ? parts.slice(1) : parts
240
+ return `${hasNamespace ? `${parts[0]}/` : ''}${owner}/${alias}`
241
+ }
242
+
243
+ function isFalUrl(url: string) {
244
+ try {
245
+ return /(fal\.(ai|run))$/.test(new URL(url).host)
246
+ } catch {
247
+ return false
248
+ }
249
+ }
250
+
251
+ function queueUrl(id: string, path = '', query?: Record<string, string>) {
252
+ const search = query ? `?${new URLSearchParams(query).toString()}` : ''
253
+ const cleanPath = path.replace(/^\//, '').replace(/\/{2,}/, '/')
254
+ if (isFalUrl(id)) {
255
+ return `${id.endsWith('/') ? id : `${id}/`}${cleanPath}${search}`
256
+ }
257
+ const url = `https://queue.fal.run/${normalizeEndpointId(id)}/${cleanPath}`
258
+ return `${url.replace(/\/$/, '')}${search}`
259
+ }
260
+
261
+ function lifecycleConfig(lifecycle: StorageSettings | undefined) {
262
+ if (!lifecycle) return undefined
263
+ const { expiresIn, initialAcl } = lifecycle
264
+ const seconds =
265
+ typeof expiresIn === 'number'
266
+ ? expiresIn
267
+ : expiresIn === undefined
268
+ ? undefined
269
+ : EXPIRATION_SECONDS[expiresIn]
270
+ const config = {
271
+ ...(seconds !== undefined ? { expiration_duration_seconds: seconds } : {}),
272
+ ...(initialAcl !== undefined ? { initial_acl: initialAcl } : {}),
273
+ }
274
+ return Object.keys(config).length > 0 ? config : undefined
275
+ }
276
+
277
+ function uploadFileName(file: Blob, contentType: string) {
278
+ if (file instanceof File && file.name) return file.name
279
+ const extension = contentType.split('/')[1]?.split(/[-;]/)[0] ?? 'bin'
280
+ return `${Date.now()}.${extension}`
281
+ }
282
+
283
+ interface SendOptions {
284
+ body?: unknown
285
+ headers?: Record<string, string>
286
+ signal?: AbortSignal
287
+ retry?: RetryPolicy
288
+ }
289
+
290
+ /**
291
+ * Create a fal client that talks to the fal queue and storage REST API with
292
+ * `fetch`. It has the same method names, arguments, results, and errors as the
293
+ * `@fal-ai/client` methods the adapters use.
294
+ *
295
+ * @param options credentials, the `fetch` to use, and an optional proxy URL.
296
+ * @example
297
+ * const client = createFalClient({ credentials: 'key', fetch })
298
+ * const { data } = await client.subscribe('fal-ai/flux/dev', { input })
299
+ */
300
+ export function createFalClient(options: FalClientOptions) {
301
+ const { credentials, proxyUrl } = options
302
+ if (isBrowser() && credentials) {
303
+ console.warn(
304
+ "The fal credentials are exposed in the browser's environment. " +
305
+ "That's not recommended for production use cases.",
306
+ )
307
+ }
308
+
309
+ async function send(
310
+ method: 'GET' | 'POST' | 'PUT',
311
+ url: string,
312
+ { body, headers, signal, retry = DEFAULT_RETRY }: SendOptions = {},
313
+ ) {
314
+ // Same as the SDK proxy middleware: without a `when` rule it only
315
+ // proxies in a browser.
316
+ const useProxy = proxyUrl !== undefined && isBrowser()
317
+ for (let attempt = 0; ; attempt++) {
318
+ try {
319
+ const response = await options.fetch(useProxy ? proxyUrl : url, {
320
+ method,
321
+ headers: {
322
+ ...(credentials ? { Authorization: `Key ${credentials}` } : {}),
323
+ Accept: 'application/json',
324
+ 'Content-Type': 'application/json',
325
+ ...headers,
326
+ ...(useProxy ? { 'x-fal-target-url': url } : {}),
327
+ },
328
+ signal,
329
+ body: method !== 'GET' && body ? JSON.stringify(body) : undefined,
330
+ })
331
+ return { response, data: await parseResponse(response) }
332
+ } catch (error) {
333
+ const isLastTry =
334
+ attempt === retry.maxRetries ||
335
+ !isRetryable(error, retry.statusCodes) ||
336
+ signal?.aborted
337
+ if (isLastTry) throw error
338
+ await sleep(backoffDelay(attempt, retry.maxDelay))
339
+ }
340
+ }
341
+ }
342
+
343
+ async function transformInput(input: unknown): Promise<unknown> {
344
+ if (Array.isArray(input)) {
345
+ return Promise.all(input.map((item) => transformInput(item)))
346
+ }
347
+ if (input instanceof Blob) return storage.upload(input)
348
+ if (isPlainObject(input)) {
349
+ const entries = Object.entries(input)
350
+ return Object.fromEntries(
351
+ await Promise.all(
352
+ entries.map(async ([key, value]) => [
353
+ key,
354
+ await transformInput(value),
355
+ ]),
356
+ ),
357
+ )
358
+ }
359
+ return input
360
+ }
361
+
362
+ const storage: FalClient['storage'] = {
363
+ async upload(file, uploadOptions) {
364
+ if (file.size > MULTIPART_THRESHOLD_BYTES) {
365
+ // ponytail: multipart upload stays in the SDK. Only files over 90 MB
366
+ // load it.
367
+ const sdk = await import('@fal-ai/client')
368
+ return sdk.createFalClient(options).storage.upload(file, uploadOptions)
369
+ }
370
+ const contentType = file.type || 'application/octet-stream'
371
+ const lifecycle = lifecycleConfig(uploadOptions?.lifecycle)
372
+ const { data } = await send('POST', UPLOAD_INITIATE_URL, {
373
+ body: {
374
+ content_type: contentType,
375
+ file_name: uploadFileName(file, contentType),
376
+ },
377
+ headers: lifecycle
378
+ ? { 'X-Fal-Object-Lifecycle': JSON.stringify(lifecycle) }
379
+ : {},
380
+ })
381
+ const uploaded = await options.fetch(data.upload_url, {
382
+ method: 'PUT',
383
+ body: file,
384
+ headers: { 'Content-Type': contentType },
385
+ })
386
+ await parseResponse(uploaded)
387
+ return data.file_url
388
+ },
389
+ }
390
+
391
+ const queue: FalClient['queue'] = {
392
+ async submit(endpointId, { input, abortSignal }) {
393
+ const body = input ? await transformInput(input) : undefined
394
+ const { data } = await send('POST', queueUrl(endpointId), {
395
+ body,
396
+ headers: { 'x-fal-queue-priority': 'normal' },
397
+ signal: abortSignal,
398
+ retry: QUEUE_RETRY,
399
+ })
400
+ return data
401
+ },
402
+ async status(endpointId, { requestId, logs = false, abortSignal }) {
403
+ const url = queueUrl(
404
+ queueAppId(endpointId),
405
+ `/requests/${requestId}/status`,
406
+ { logs: logs ? '1' : '0' },
407
+ )
408
+ const { data } = await send('GET', url, {
409
+ signal: abortSignal,
410
+ retry: QUEUE_STATUS_RETRY,
411
+ })
412
+ return data
413
+ },
414
+ async result(endpointId, { requestId, abortSignal }) {
415
+ const url = queueUrl(queueAppId(endpointId), `/requests/${requestId}`)
416
+ const { response, data } = await send('GET', url, {
417
+ signal: abortSignal,
418
+ retry: QUEUE_RETRY,
419
+ })
420
+ return {
421
+ data,
422
+ requestId: response.headers.get('x-fal-request-id') || '',
423
+ }
424
+ },
425
+ async cancel(endpointId, { requestId, abortSignal }) {
426
+ const url = queueUrl(
427
+ queueAppId(endpointId),
428
+ `/requests/${requestId}/cancel`,
429
+ )
430
+ await send('PUT', url, { signal: abortSignal })
431
+ },
432
+ }
433
+
434
+ const client: FalClient = {
435
+ queue,
436
+ storage,
437
+ async subscribe(endpointId, subscribeOptions) {
438
+ const { request_id: requestId } = await queue.submit(
439
+ endpointId,
440
+ subscribeOptions,
441
+ )
442
+ const { abortSignal, logs, onEnqueue } = subscribeOptions
443
+ onEnqueue?.(requestId)
444
+ // Same as the SDK: poll right away, then every 500 ms until COMPLETED.
445
+ while (
446
+ (await queue.status(endpointId, { requestId, logs, abortSignal }))
447
+ .status !== 'COMPLETED'
448
+ ) {
449
+ await sleep(POLL_INTERVAL_MS)
450
+ }
451
+ // The SDK does not pass the abort signal to the result request.
452
+ return queue.result(endpointId, { requestId })
453
+ },
454
+ }
455
+ return client
456
+ }
package/src/index.ts CHANGED
@@ -83,7 +83,7 @@ export {
83
83
 
84
84
  export {
85
85
  getFalApiKeyFromEnv,
86
- configureFalClient,
87
86
  generateId,
88
87
  type FalClientConfig,
89
88
  } from './utils/client'
89
+ export { configureFalClient } from './utils/configure'
@@ -1,5 +1,5 @@
1
- import { fal } from '@fal-ai/client'
2
1
  import { generateId as _generateId, getApiKeyFromEnv } from '@tanstack/ai-utils'
2
+ import { createFalClient } from '../client/index'
3
3
  import { createBillingFetch } from './billing'
4
4
 
5
5
  export interface FalClientConfig {
@@ -18,16 +18,24 @@ export function getFalApiKeyFromEnv(): string {
18
18
  return getApiKeyFromEnv('FAL_KEY')
19
19
  }
20
20
 
21
- export function configureFalClient(config?: FalClientConfig): void {
21
+ export function toFalClientOptions(config?: FalClientConfig) {
22
22
  const apiKey = config?.apiKey ?? getFalApiKeyFromEnv()
23
- fal.config({
23
+ return {
24
24
  credentials: apiKey,
25
25
  // Wrap the (optionally overridden) fetch to read fal's
26
26
  // `x-fal-billable-units` header off every response so adapters can surface
27
27
  // the billed quantity as `result.usage`. See ./billing.ts.
28
28
  fetch: createBillingFetch(config?.fetch),
29
29
  ...(config?.proxyUrl ? { proxyUrl: config.proxyUrl } : {}),
30
- })
30
+ }
31
+ }
32
+
33
+ /**
34
+ * Create the fal client for one adapter. Each adapter has its own client, so
35
+ * two adapters with different API keys do not change each other.
36
+ */
37
+ export function createAdapterFalClient(config?: FalClientConfig) {
38
+ return createFalClient(toFalClientOptions(config))
31
39
  }
32
40
 
33
41
  export function generateId(prefix: string): string {
@@ -0,0 +1,17 @@
1
+ import { fal } from '@fal-ai/client'
2
+ import { toFalClientOptions } from './client'
3
+ import type { FalClientConfig } from './client'
4
+
5
+ /**
6
+ * Configure the global `fal` client of `@fal-ai/client` with this config, for
7
+ * apps that call `fal` themselves. The adapters do not use the global client.
8
+ *
9
+ * ponytail: this file is the only static import of `@fal-ai/client`. It is a
10
+ * separate module, so a bundle that does not import this function drops it.
11
+ *
12
+ * @param config the API key (or `FAL_KEY` from the environment), an optional
13
+ * proxy URL, and an optional `fetch`.
14
+ */
15
+ export function configureFalClient(config?: FalClientConfig): void {
16
+ fal.config(toFalClientOptions(config))
17
+ }
@@ -1,6 +1,5 @@
1
1
  export {
2
2
  getFalApiKeyFromEnv,
3
- configureFalClient,
4
3
  generateId,
5
4
  arrayBufferToBase64,
6
5
  dataUrlToBlob,
@@ -10,3 +9,5 @@ export {
10
9
  } from './client'
11
10
 
12
11
  export { takeBillableUnits, buildFalUsage } from './billing'
12
+
13
+ export { configureFalClient } from './configure'