@howells/motif-sdk 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,51 @@
+# @howells/motif-sdk
+
+Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.
+
+## Install
+
+```bash
+npm install @howells/motif-sdk
+```
+
+## Usage
+
+```ts
+import { MotifServer, FAL_TOOLS, MODELS } from "@howells/motif-sdk";
+
+const motif = new MotifServer(process.env.FAL_KEY!);
+
+const result = await motif.generate({
+  model: "banana2",
+  prompt: "editorial product photo",
+  ephemeral: true,
+});
+
+if (result.isErr()) {
+  throw result.error;
+}
+
+console.log(result.value.images[0]?.url);
+```
+
+## Main Exports
+
+- `MotifServer` - Result-returning fal client for generation, queue jobs, upload, utility tools, and payload deletion.
+- `buildGenerateBody` - Pure fal request normalization for dry runs and tests.
+- `MODELS` - Motif model aliases, fal endpoints, capabilities, pricing, and benchmarks.
+- `FAL_TOOLS` - Normalized fal utility endpoints such as SAM, depth, upscaling, moderation, and background removal.
+- `getFalKeyFromEnv` - `@howells/envy` backed `FAL_KEY` parsing.
+
+## Testing
+
+```bash
+pnpm --filter @howells/motif-sdk test
+pnpm --filter @howells/motif-sdk typecheck
+```
+
+Live fal canaries are opt-in:
+
+```bash
+RUN_FAL_CANARY=1 pnpm --filter @howells/motif-sdk test -- tests/fal-canary.test.ts
+```
+

package/dist/index.cjs

@@ -2261,6 +2261,7 @@ function buildFalToolRequest(options) {
 // src/server.ts
 var FAL_BASE_URL = "https://fal.run";
 var FAL_QUEUE_URL = "https://queue.fal.run";
+var FAL_API_URL = "https://api.fal.ai";
 var FAL_REST_URL = "https://rest.alpha.fal.ai";
 function endpointFromQueueUrl(url, fallback) {
   if (!url) return fallback;
@@ -2300,7 +2301,8 @@ var MotifServer = class {
     const { endpoint, body } = buildGenerateBody(options);
     const response = await this.request(`${FAL_BASE_URL}/${endpoint}`, {
       method: "POST",
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      headers: this.ephemeralHeaders(options)
     });
     if (response.isErr()) {
       return (0, import_neverthrow.err)(response.error);
@@ -2341,7 +2343,8 @@ var MotifServer = class {
     const { endpoint, body } = buildGenerateBody(options);
     const response = await this.request(`${FAL_QUEUE_URL}/${endpoint}`, {
       method: "POST",
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      headers: this.ephemeralHeaders(options)
     });
     if (response.isErr()) {
       return (0, import_neverthrow.err)(response.error);
@@ -2392,7 +2395,7 @@ var MotifServer = class {
       return (0, import_neverthrow.err)(response.error);
     }
     const data = await response.value.json();
-    return this.normalizeResponse(data);
+    return this.normalizeResponse(data, requestId);
   }
   /** ─── Processing ──────────────────────────────────────────── */
   /** Upscale an image using clarity or crystal upscaler. */
@@ -2607,6 +2610,23 @@ var MotifServer = class {
     }
     return (0, import_neverthrow.ok)(await response.value.json());
   }
+  /**
+   * Delete fal's stored IO payloads for a completed request.
+   *
+   * This removes request input/output payload files exposed by fal's payloads
+   * API. It does not remove billing/account metadata or input files separately
+   * uploaded to fal storage before a request.
+   */
+  async deletePayloads(requestId) {
+    const response = await this.request(
+      `${FAL_API_URL}/v1/models/requests/${encodeURIComponent(requestId)}/payloads`,
+      { method: "DELETE" }
+    );
+    if (response.isErr()) {
+      return (0, import_neverthrow.err)(response.error);
+    }
+    return (0, import_neverthrow.ok)(void 0);
+  }
   /** Estimate cost for a generation (no API call). */
   estimateCost(model, resolution, numImages) {
     return estimateCost(model, resolution, numImages);
@@ -2681,12 +2701,16 @@ var MotifServer = class {
     }
     return (0, import_neverthrow.err)(lastError ?? new MotifError("Request failed after retries", 0));
   }
+  ephemeralHeaders(options) {
+    return options.ephemeral ? { "X-Fal-Store-IO": "0" } : {};
+  }
   /**
    * Normalize fal.ai responses.
    * Some APIs return `{ image: {...} }` instead of `{ images: [...] }`.
    */
-  normalizeResponse(data) {
+  normalizeResponse(data, fallbackRequestId) {
     const obj = data;
+    const requestId = obj.request_id ?? obj.requestId ?? fallbackRequestId;
     if ("detail" in obj) {
       return (0, import_neverthrow.err)(
         new MotifError(obj.detail, 0, "FAL_ERROR")
@@ -2696,10 +2720,14 @@ var MotifServer = class {
       return (0, import_neverthrow.ok)({
         images: [obj.image],
         seed: obj.seed,
-        prompt: obj.prompt
+        prompt: obj.prompt,
+        requestId
       });
     }
-    return (0, import_neverthrow.ok)(obj);
+    return (0, import_neverthrow.ok)({
+      ...obj,
+      requestId
+    });
   }
 };
 var MotifError = class extends Error {

package/dist/index.d.cts

@@ -105,6 +105,8 @@ interface GenerateOptions {
     /** GPT background mode where supported */
     background?: BackgroundMode;
     editImageUrls?: string[];
+    /** Ask fal not to store IO payloads, and expose request ids for deletion. */
+    ephemeral?: boolean;
     /** Google-search alias for fal models that expose enable_google_search */
     enableGoogleSearch?: boolean;
     /** fal safety checker toggle where supported */
@@ -223,6 +225,7 @@ interface MotifImage {
 interface MotifResponse {
     images: MotifImage[];
     prompt?: string;
+    requestId?: string;
     seed?: number;
 }
 /** ─── Queue Types ────────────────────────────────────────────── */
@@ -387,6 +390,14 @@ declare class MotifServer {
     /** ─── Utilities ───────────────────────────────────────────── */
     /** Run a registered fal utility/tool endpoint. */
     runTool(options: ToolRunOptions): Promise<Result<ToolResponse, MotifError>>;
+    /**
+     * Delete fal's stored IO payloads for a completed request.
+     *
+     * This removes request input/output payload files exposed by fal's payloads
+     * API. It does not remove billing/account metadata or input files separately
+     * uploaded to fal storage before a request.
+     */
+    deletePayloads(requestId: string): Promise<Result<void, MotifError>>;
     /** Estimate cost for a generation (no API call). */
     estimateCost(model: string, resolution?: Resolution, numImages?: number): number;
     /** Build the fal.ai request body without sending it. */
@@ -743,6 +754,7 @@ declare class MotifServer {
     /** ─── Private ─────────────────────────────────────────────── */
     /** Authenticated fetch to fal.ai APIs with retry logic. */
     private request;
+    private ephemeralHeaders;
     /**
      * Normalize fal.ai responses.
      * Some APIs return `{ image: {...} }` instead of `{ images: [...] }`.

package/dist/index.d.ts

@@ -105,6 +105,8 @@ interface GenerateOptions {
     /** GPT background mode where supported */
     background?: BackgroundMode;
     editImageUrls?: string[];
+    /** Ask fal not to store IO payloads, and expose request ids for deletion. */
+    ephemeral?: boolean;
     /** Google-search alias for fal models that expose enable_google_search */
     enableGoogleSearch?: boolean;
     /** fal safety checker toggle where supported */
@@ -223,6 +225,7 @@ interface MotifImage {
 interface MotifResponse {
     images: MotifImage[];
     prompt?: string;
+    requestId?: string;
     seed?: number;
 }
 /** ─── Queue Types ────────────────────────────────────────────── */
@@ -387,6 +390,14 @@ declare class MotifServer {
     /** ─── Utilities ───────────────────────────────────────────── */
     /** Run a registered fal utility/tool endpoint. */
     runTool(options: ToolRunOptions): Promise<Result<ToolResponse, MotifError>>;
+    /**
+     * Delete fal's stored IO payloads for a completed request.
+     *
+     * This removes request input/output payload files exposed by fal's payloads
+     * API. It does not remove billing/account metadata or input files separately
+     * uploaded to fal storage before a request.
+     */
+    deletePayloads(requestId: string): Promise<Result<void, MotifError>>;
     /** Estimate cost for a generation (no API call). */
     estimateCost(model: string, resolution?: Resolution, numImages?: number): number;
     /** Build the fal.ai request body without sending it. */
@@ -743,6 +754,7 @@ declare class MotifServer {
     /** ─── Private ─────────────────────────────────────────────── */
     /** Authenticated fetch to fal.ai APIs with retry logic. */
     private request;
+    private ephemeralHeaders;
     /**
      * Normalize fal.ai responses.
      * Some APIs return `{ image: {...} }` instead of `{ images: [...] }`.

package/dist/index.js

@@ -2208,6 +2208,7 @@ function buildFalToolRequest(options) {
 // src/server.ts
 var FAL_BASE_URL = "https://fal.run";
 var FAL_QUEUE_URL = "https://queue.fal.run";
+var FAL_API_URL = "https://api.fal.ai";
 var FAL_REST_URL = "https://rest.alpha.fal.ai";
 function endpointFromQueueUrl(url, fallback) {
   if (!url) return fallback;
@@ -2247,7 +2248,8 @@ var MotifServer = class {
     const { endpoint, body } = buildGenerateBody(options);
     const response = await this.request(`${FAL_BASE_URL}/${endpoint}`, {
       method: "POST",
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      headers: this.ephemeralHeaders(options)
     });
     if (response.isErr()) {
       return err(response.error);
@@ -2288,7 +2290,8 @@ var MotifServer = class {
     const { endpoint, body } = buildGenerateBody(options);
     const response = await this.request(`${FAL_QUEUE_URL}/${endpoint}`, {
       method: "POST",
-      body: JSON.stringify(body)
+      body: JSON.stringify(body),
+      headers: this.ephemeralHeaders(options)
     });
     if (response.isErr()) {
       return err(response.error);
@@ -2339,7 +2342,7 @@ var MotifServer = class {
       return err(response.error);
     }
     const data = await response.value.json();
-    return this.normalizeResponse(data);
+    return this.normalizeResponse(data, requestId);
   }
   /** ─── Processing ──────────────────────────────────────────── */
   /** Upscale an image using clarity or crystal upscaler. */
@@ -2554,6 +2557,23 @@ var MotifServer = class {
     }
     return ok(await response.value.json());
   }
+  /**
+   * Delete fal's stored IO payloads for a completed request.
+   *
+   * This removes request input/output payload files exposed by fal's payloads
+   * API. It does not remove billing/account metadata or input files separately
+   * uploaded to fal storage before a request.
+   */
+  async deletePayloads(requestId) {
+    const response = await this.request(
+      `${FAL_API_URL}/v1/models/requests/${encodeURIComponent(requestId)}/payloads`,
+      { method: "DELETE" }
+    );
+    if (response.isErr()) {
+      return err(response.error);
+    }
+    return ok(void 0);
+  }
   /** Estimate cost for a generation (no API call). */
   estimateCost(model, resolution, numImages) {
     return estimateCost(model, resolution, numImages);
@@ -2628,12 +2648,16 @@ var MotifServer = class {
     }
     return err(lastError ?? new MotifError("Request failed after retries", 0));
   }
+  ephemeralHeaders(options) {
+    return options.ephemeral ? { "X-Fal-Store-IO": "0" } : {};
+  }
   /**
    * Normalize fal.ai responses.
    * Some APIs return `{ image: {...} }` instead of `{ images: [...] }`.
    */
-  normalizeResponse(data) {
+  normalizeResponse(data, fallbackRequestId) {
     const obj = data;
+    const requestId = obj.request_id ?? obj.requestId ?? fallbackRequestId;
     if ("detail" in obj) {
       return err(
         new MotifError(obj.detail, 0, "FAL_ERROR")
@@ -2643,10 +2667,14 @@ var MotifServer = class {
       return ok({
         images: [obj.image],
         seed: obj.seed,
-        prompt: obj.prompt
+        prompt: obj.prompt,
+        requestId
       });
     }
-    return ok(obj);
+    return ok({
+      ...obj,
+      requestId
+    });
   }
 };
 var MotifError = class extends Error {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "license": "MIT",
   "author": "Daniel Howells",