@howells/motif-sdk 5.0.0 → 5.1.0

package/README.md

@@ -32,7 +32,9 @@ console.log(result.value.model, result.value.files[0]?.url, result.value.cost);
 
 Every Task function returns `Result<TaskOutput, MotifError>` from `neverthrow` and does not throw for fal request failures; check `isErr()` / `isOk()`.
 
-Pass `onProgress(status, queuePosition)` to hear fal's queue state while a run waits: `"queued"` with its place in line, then `"in_progress"`, then `"completed"`. Passing it sends the run through fal's queue, since only the queue reports state. Models without streaming report state, not a percentage.
+Pass `onProgress(status, queuePosition)` to hear fal's queue state while a run waits: `"queued"` with its place in line, then `"processing"`, then `"completed"` (or `"failed"`). Passing it sends the run through fal's queue, since only the queue reports state. Models without streaming report state, not a percentage.
+
+Pass `onSubmitted(requestId)` to hear the request id the moment fal's queue accepts the run, before any wait. Keep it: after a restart, `motif.resume(task, input, requestId)` waits for that same job and returns its output, submitting nothing and so paying nothing twice. Passing `onSubmitted` also queues the run.
 
 ## Plan Without Calling fal
 

package/dist/index.cjs

@@ -4262,27 +4262,36 @@ async function getToolResult(exec, job) {
 	const data = await response.value.json();
 	return (0, neverthrow.ok)(isRecord$4(data) ? data : {});
 }
-/** Submit a prepared request, poll it to completion and fetch the result. */
-async function runRequestQueued(exec, prepared, onProgress) {
-	const job = await submitRequest(exec, prepared);
-	if (job.isErr()) return (0, neverthrow.err)(job.error);
+/** Poll a submitted job to completion and fetch its result. Submits nothing. */
+async function awaitQueuedRequest(exec, job, onProgress) {
 	for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
-		const status = await checkToolStatus(exec, job.value);
+		const status = await checkToolStatus(exec, job);
 		if (status.isErr()) return (0, neverthrow.err)(status.error);
 		onProgress?.(status.value.status, status.value.queuePosition);
-		if (status.value.status === "completed") return (await getToolResult(exec, job.value)).map((data) => ({
+		if (status.value.status === "completed") return (await getToolResult(exec, job)).map((data) => ({
 			data,
-			requestId: job.value.requestId
+			requestId: job.requestId
 		}));
 		if (status.value.status === "failed") {
 			const message = status.value.error ?? "Queued run failed";
-			return (0, neverthrow.err)(new MotifError(message, 0, void 0, job.value.requestId));
+			return (0, neverthrow.err)(new MotifError(message, 0, void 0, job.requestId));
 		}
 		await new Promise((resolve) => {
 			setTimeout(resolve, POLL_INTERVAL_MS);
 		});
 	}
-	return (0, neverthrow.err)(new MotifError("Queued run timed out", 0, void 0, job.value.requestId));
+	return (0, neverthrow.err)(new MotifError("Queued run timed out", 0, void 0, job.requestId));
+}
+/**
+* Submit a prepared request, poll it to completion and fetch the result.
+* `onSubmitted` hears the request id as soon as fal accepts the job, before
+* any wait, so a caller can keep it and resume the same job later.
+*/
+async function runRequestQueued(exec, prepared, onProgress, onSubmitted) {
+	const job = await submitRequest(exec, prepared);
+	if (job.isErr()) return (0, neverthrow.err)(job.error);
+	onSubmitted?.(job.value.requestId);
+	return await awaitQueuedRequest(exec, job.value, onProgress);
 }
 /** Body of `FalClient.runTool`. */
 async function runTool(exec, options) {
@@ -9898,7 +9907,7 @@ function generationPlan(task, model, config, input) {
 		endpoint: built.endpoint,
 		prompt: typeof built.body.prompt === "string" ? built.body.prompt : void 0,
 		provider: "fal",
-		queued: config.useQueue === true || input.onProgress !== void 0
+		queued: config.useQueue === true || input.onProgress !== void 0 || input.onSubmitted !== void 0
 	});
 }
 /**
@@ -10506,7 +10515,19 @@ function createMotif(config = {}) {
 			headers
 		};
 		const executor = falRequestExecutor(client.value);
-		return (chosen.queued ? await runRequestQueued(executor, prepared, input.onProgress) : await runRequest(executor, prepared)).map((value) => falOutput(chosen, value));
+		return (chosen.queued ? await runRequestQueued(executor, prepared, input.onProgress, input.onSubmitted) : await runRequest(executor, prepared)).map((value) => falOutput(chosen, value));
+	}
+	async function resume(task, input, requestId) {
+		const planned = plan(task, input);
+		if (planned.isErr()) return (0, neverthrow.err)(planned.error);
+		const chosen = planned.value;
+		if (chosen.provider !== "fal") return (0, neverthrow.err)(new MotifError(`Only a fal run can be resumed; ${chosen.model} runs on ${chosen.provider}.`, 0));
+		const client = falClient();
+		if (client.isErr()) return (0, neverthrow.err)(client.error);
+		return (await awaitQueuedRequest(falRequestExecutor(client.value), {
+			endpoint: chosen.endpoint,
+			requestId
+		}, input.onProgress)).map((value) => falOutput(chosen, value));
 	}
 	return {
 		animate: async (input) => await run("animate", input),
@@ -10533,6 +10554,7 @@ function createMotif(config = {}) {
 			return client.isErr() ? (0, neverthrow.err)(client.error) : await client.value.deletePayloads(requestId);
 		},
 		plan,
+		resume,
 		run,
 		stream: taskStreamer(config, plan, context),
 		async upload(bytes, contentType, fileName) {

package/dist/index.d.cts

@@ -262,6 +262,15 @@ interface ImageSizeBounds {
   /** Both edges must be multiples of this. Motif uses 16 when absent. */
   multipleOf?: number;
 }
+interface JobStatus {
+  error?: string;
+  logs?: {
+    message: string;
+    timestamp: string;
+  }[];
+  queuePosition?: number;
+  status: "queued" | "processing" | "completed" | "failed";
+}
 /** ─── Configuration ──────────────────────────────────────────── */
 /** The network seam: a `fetch`-shaped function. */
 type FalFetch = (url: string, init: RequestInit) => Promise<Response>;
@@ -1189,10 +1198,16 @@ interface TaskInput {
   ephemeral?: boolean;
   /**
    * Called on each poll of fal's queue with its status ("queued",
-   * "in_progress", "completed") and, while queued, the place in line. Passing
+   * "processing", "completed", "failed") and, while queued, the place in line. Passing
    * it runs a fal generation through the queue, since only the queue reports.
    */
-  onProgress?: (status: string, queuePosition?: number) => void;
+  onProgress?: (status: JobStatus["status"], queuePosition?: number) => void;
+  /**
+   * Called once, as soon as fal's queue accepts the run, with its request id
+   * and before any wait. Keep it to `resume` the same job after a restart
+   * rather than submitting, and paying for, a second. Passing it queues the run.
+   */
+  onSubmitted?: (requestId: string) => void;
 }
 interface TaskFile {
   /** Output key the URL came from, e.g. "image", "masks", "model_glb". */
@@ -1260,6 +1275,12 @@ interface MotifClient {
   /** Upload bytes to fal storage; returns the public URL. */
   upload: (bytes: Uint8Array, contentType: string, fileName?: string) => Promise<Result$1<string, MotifError>>;
   deletePayloads: (requestId: string) => Promise<Result$1<void, MotifError>>;
+  /**
+   * Read a queued run already submitted, by the request id `onSubmitted` gave:
+   * wait for it and return its output, submitting nothing. Pass the same task
+   * and input the run was made with, so the endpoint and costing match.
+   */
+  resume: (task: TaskId, input: TaskInput, requestId: string) => Promise<Result$1<TaskOutput, MotifError>>;
 }
 /** Create the Task client. Keys fall back to FAL_KEY and OPENAI_API_KEY. */
 export declare function createMotif(config?: MotifClientConfig): MotifClient;

package/dist/index.d.ts

@@ -262,6 +262,15 @@ interface ImageSizeBounds {
   /** Both edges must be multiples of this. Motif uses 16 when absent. */
   multipleOf?: number;
 }
+interface JobStatus {
+  error?: string;
+  logs?: {
+    message: string;
+    timestamp: string;
+  }[];
+  queuePosition?: number;
+  status: "queued" | "processing" | "completed" | "failed";
+}
 /** ─── Configuration ──────────────────────────────────────────── */
 /** The network seam: a `fetch`-shaped function. */
 type FalFetch = (url: string, init: RequestInit) => Promise<Response>;
@@ -1189,10 +1198,16 @@ interface TaskInput {
   ephemeral?: boolean;
   /**
    * Called on each poll of fal's queue with its status ("queued",
-   * "in_progress", "completed") and, while queued, the place in line. Passing
+   * "processing", "completed", "failed") and, while queued, the place in line. Passing
    * it runs a fal generation through the queue, since only the queue reports.
    */
-  onProgress?: (status: string, queuePosition?: number) => void;
+  onProgress?: (status: JobStatus["status"], queuePosition?: number) => void;
+  /**
+   * Called once, as soon as fal's queue accepts the run, with its request id
+   * and before any wait. Keep it to `resume` the same job after a restart
+   * rather than submitting, and paying for, a second. Passing it queues the run.
+   */
+  onSubmitted?: (requestId: string) => void;
 }
 interface TaskFile {
   /** Output key the URL came from, e.g. "image", "masks", "model_glb". */
@@ -1260,6 +1275,12 @@ interface MotifClient {
   /** Upload bytes to fal storage; returns the public URL. */
   upload: (bytes: Uint8Array, contentType: string, fileName?: string) => Promise<Result$1<string, MotifError>>;
   deletePayloads: (requestId: string) => Promise<Result$1<void, MotifError>>;
+  /**
+   * Read a queued run already submitted, by the request id `onSubmitted` gave:
+   * wait for it and return its output, submitting nothing. Pass the same task
+   * and input the run was made with, so the endpoint and costing match.
+   */
+  resume: (task: TaskId, input: TaskInput, requestId: string) => Promise<Result$1<TaskOutput, MotifError>>;
 }
 /** Create the Task client. Keys fall back to FAL_KEY and OPENAI_API_KEY. */
 export declare function createMotif(config?: MotifClientConfig): MotifClient;

package/dist/index.js

@@ -4261,27 +4261,36 @@ async function getToolResult(exec, job) {
 	const data = await response.value.json();
 	return ok$1(isRecord$4(data) ? data : {});
 }
-/** Submit a prepared request, poll it to completion and fetch the result. */
-async function runRequestQueued(exec, prepared, onProgress) {
-	const job = await submitRequest(exec, prepared);
-	if (job.isErr()) return err$1(job.error);
+/** Poll a submitted job to completion and fetch its result. Submits nothing. */
+async function awaitQueuedRequest(exec, job, onProgress) {
 	for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
-		const status = await checkToolStatus(exec, job.value);
+		const status = await checkToolStatus(exec, job);
 		if (status.isErr()) return err$1(status.error);
 		onProgress?.(status.value.status, status.value.queuePosition);
-		if (status.value.status === "completed") return (await getToolResult(exec, job.value)).map((data) => ({
+		if (status.value.status === "completed") return (await getToolResult(exec, job)).map((data) => ({
 			data,
-			requestId: job.value.requestId
+			requestId: job.requestId
 		}));
 		if (status.value.status === "failed") {
 			const message = status.value.error ?? "Queued run failed";
-			return err$1(new MotifError(message, 0, void 0, job.value.requestId));
+			return err$1(new MotifError(message, 0, void 0, job.requestId));
 		}
 		await new Promise((resolve) => {
 			setTimeout(resolve, POLL_INTERVAL_MS);
 		});
 	}
-	return err$1(new MotifError("Queued run timed out", 0, void 0, job.value.requestId));
+	return err$1(new MotifError("Queued run timed out", 0, void 0, job.requestId));
+}
+/**
+* Submit a prepared request, poll it to completion and fetch the result.
+* `onSubmitted` hears the request id as soon as fal accepts the job, before
+* any wait, so a caller can keep it and resume the same job later.
+*/
+async function runRequestQueued(exec, prepared, onProgress, onSubmitted) {
+	const job = await submitRequest(exec, prepared);
+	if (job.isErr()) return err$1(job.error);
+	onSubmitted?.(job.value.requestId);
+	return await awaitQueuedRequest(exec, job.value, onProgress);
 }
 /** Body of `FalClient.runTool`. */
 async function runTool(exec, options) {
@@ -9897,7 +9906,7 @@ function generationPlan(task, model, config, input) {
 		endpoint: built.endpoint,
 		prompt: typeof built.body.prompt === "string" ? built.body.prompt : void 0,
 		provider: "fal",
-		queued: config.useQueue === true || input.onProgress !== void 0
+		queued: config.useQueue === true || input.onProgress !== void 0 || input.onSubmitted !== void 0
 	});
 }
 /**
@@ -10505,7 +10514,19 @@ function createMotif(config = {}) {
 			headers
 		};
 		const executor = falRequestExecutor(client.value);
-		return (chosen.queued ? await runRequestQueued(executor, prepared, input.onProgress) : await runRequest(executor, prepared)).map((value) => falOutput(chosen, value));
+		return (chosen.queued ? await runRequestQueued(executor, prepared, input.onProgress, input.onSubmitted) : await runRequest(executor, prepared)).map((value) => falOutput(chosen, value));
+	}
+	async function resume(task, input, requestId) {
+		const planned = plan(task, input);
+		if (planned.isErr()) return err$1(planned.error);
+		const chosen = planned.value;
+		if (chosen.provider !== "fal") return err$1(new MotifError(`Only a fal run can be resumed; ${chosen.model} runs on ${chosen.provider}.`, 0));
+		const client = falClient();
+		if (client.isErr()) return err$1(client.error);
+		return (await awaitQueuedRequest(falRequestExecutor(client.value), {
+			endpoint: chosen.endpoint,
+			requestId
+		}, input.onProgress)).map((value) => falOutput(chosen, value));
 	}
 	return {
 		animate: async (input) => await run("animate", input),
@@ -10532,6 +10553,7 @@ function createMotif(config = {}) {
 			return client.isErr() ? err$1(client.error) : await client.value.deletePayloads(requestId);
 		},
 		plan,
+		resume,
 		run,
 		stream: taskStreamer(config, plan, context),
 		async upload(bytes, contentType, fileName) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Node SDK for Motif: image, video and 3D Tasks on fal.ai, with Motif choosing the Model.",
   "keywords": [
     "fal",