feat(client): webhook url support on queue submit (#26)

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",

libs/client/src/function.ts

@@ -157,6 +157,17 @@ type QueueSubscribeOptions = {
   logs?: boolean;
 };
 
+/**
+ * Options for submitting a request to the queue.
+ */
+type SubmitOptions<Input> = RunOptions<Input> & {
+  /**
+   * 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<Input>(id: string, options: RunOptions<Input>): Promise<EnqueueResult>;
+  submit<Input>(
+    id: string,
+    options: SubmitOptions<Input>
+  ): Promise<EnqueueResult>;
 
   /**
    * Retrieves the status of a specific request in the queue.
@@ -221,13 +235,16 @@ interface Queue {
 export const queue: Queue = {
   async submit<Input>(
     id: string,
-    options: RunOptions<Input>
+    options: SubmitOptions<Input>
   ): Promise<EnqueueResult> {
-    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(

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';

libs/client/src/types.ts

@@ -34,3 +34,32 @@ export type ValidationErrorInfo = {
   loc: Array<string | number>;
   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<Payload = any> =
+  | {
+      /** 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;
+    };