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;
+ };