diff --git a/libs/client/package.json b/libs/client/package.json index 46c946c..5e54b08 100644 --- a/libs/client/package.json +++ b/libs/client/package.json @@ -1,7 +1,7 @@ { "name": "@fal-ai/serverless-client", "description": "The fal serverless JS/TS client", - "version": "0.5.1", + "version": "0.5.2", "license": "MIT", "repository": { "type": "git", diff --git a/libs/client/src/function.ts b/libs/client/src/function.ts index aba52cb..4574e2e 100644 --- a/libs/client/src/function.ts +++ b/libs/client/src/function.ts @@ -157,6 +157,17 @@ type QueueSubscribeOptions = { logs?: boolean; }; +/** + * Options for submitting a request to the queue. + */ +type SubmitOptions = RunOptions & { + /** + * The URL to send a webhook notification to when the request is completed. + * @see WebHookResponse + */ + webhookUrl?: string; +}; + type BaseQueueOptions = { /** * The unique identifier for the enqueued request. @@ -184,7 +195,10 @@ interface Queue { * @param options - Options to configure how the request is run. * @returns A promise that resolves to the result of enqueuing the request. */ - submit(id: string, options: RunOptions): Promise; + submit( + id: string, + options: SubmitOptions + ): Promise; /** * Retrieves the status of a specific request in the queue. @@ -221,13 +235,16 @@ interface Queue { export const queue: Queue = { async submit( id: string, - options: RunOptions + options: SubmitOptions ): Promise { - const path = options.path ?? ''; + const { webhookUrl, path = '', ...runOptions } = options; + const query = webhookUrl + ? '?' + new URLSearchParams({ fal_webhook: webhookUrl }).toString() + : ''; return run(id, { - ...options, + ...runOptions, method: 'post', - path: '/fal/queue/submit' + path, + path: '/fal/queue/submit' + path + query, }); }, async status( diff --git a/libs/client/src/index.ts b/libs/client/src/index.ts index 7d1d611..75e3f54 100644 --- a/libs/client/src/index.ts +++ b/libs/client/src/index.ts @@ -5,4 +5,8 @@ export { withMiddleware, withProxy } from './middleware'; export type { RequestMiddleware } from './middleware'; export { ApiError, ValidationError } from './response'; export type { ResponseHandler } from './response'; -export type { QueueStatus, ValidationErrorInfo } from './types'; +export type { + QueueStatus, + ValidationErrorInfo, + WebHookResponse, +} from './types'; diff --git a/libs/client/src/types.ts b/libs/client/src/types.ts index 4faf9f6..3f7088d 100644 --- a/libs/client/src/types.ts +++ b/libs/client/src/types.ts @@ -34,3 +34,32 @@ export type ValidationErrorInfo = { loc: Array; type: string; }; + +/** + * Represents the response from a WebHook request. + * This is a union type that varies based on the `status` property. + * + * @template Payload - The type of the payload in the response. It defaults to `any`, + * allowing for flexibility in specifying the structure of the payload. + */ +export type WebHookResponse = + | { + /** Indicates a successful response. */ + status: 'OK'; + /** The payload of the response, structure determined by the Payload type. */ + payload: Payload; + /** Error is never present in a successful response. */ + error: never; + /** The unique identifier for the request. */ + request_id: string; + } + | { + /** Indicates an unsuccessful response. */ + status: 'ERROR'; + /** The payload of the response, structure determined by the Payload type. */ + payload: Payload; + /** Description of the error that occurred. */ + error: string; + /** The unique identifier for the request. */ + request_id: string; + };