@howells/motif-sdk 0.2.0 → 0.3.0

package/README.md

@@ -8,16 +8,22 @@ Public Node SDK for Motif fal.ai generation, editing, utility tools, and model m
 npm install @howells/motif-sdk
 ```
 
-## Usage
+## Generate Images
 
 ```ts
-import { MotifServer, FAL_TOOLS, MODELS } from "@howells/motif-sdk";
+import { MotifServer } from "@howells/motif-sdk";
 
-const motif = new MotifServer(process.env.FAL_KEY!);
+const motif = new MotifServer({
+  apiKey: process.env.FAL_KEY!,
+  retries: 3,
+  timeout: 120_000,
+});
 
 const result = await motif.generate({
   model: "banana2",
   prompt: "editorial product photo",
+  resolution: "2K",
+  enableGoogleSearch: true,
   ephemeral: true,
 });
 
@@ -28,13 +34,88 @@ if (result.isErr()) {
 console.log(result.value.images[0]?.url);
 ```
 
+Every async SDK method returns `Result<T, MotifError>` from `neverthrow`. Methods do not throw for fal request failures; check `isErr()` / `isOk()`.
+
+## Dry-Run Request Bodies
+
+Use `buildGenerateBody` or `motif.buildRequestBody()` when you need the exact fal endpoint and request body without making an API call.
+
+```ts
+import { buildGenerateBody } from "@howells/motif-sdk";
+
+const preview = buildGenerateBody({
+  model: "gpt2",
+  prompt: "change the wall color",
+  editImageUrls: ["https://example.com/interior.png"],
+  imageSize: "1536x1024",
+  maskImageUrl: "https://example.com/wall-mask.png",
+  quality: "auto",
+  syncMode: true,
+});
+
+console.log(preview.endpoint);
+console.log(preview.body);
+```
+
+## Queue, Upload, and Cleanup
+
+```ts
+const job = await motif.submitGeneration({
+  model: "gpt2",
+  prompt: "gallery poster",
+});
+
+if (job.isOk()) {
+  const status = await motif.getJobStatus(job.value.endpoint, job.value.requestId);
+  const completed = await motif.getJobResult(job.value.endpoint, job.value.requestId);
+}
+
+const uploaded = await motif.uploadToFalCdn(fileBytes, {
+  contentType: "image/png",
+  fileName: "reference.png",
+});
+
+const deleted = await motif.deletePayloads("fal-request-id");
+```
+
+## Utility Tools and Video
+
+```ts
+const mask = await motif.runTool({
+  tool: "sam3-image",
+  input: "https://example.com/input.png",
+  options: { prompt: "shoe", max_masks: 2 },
+});
+
+const videoJob = await motif.submitVideo({
+  imageUrl: "https://example.com/frame.png",
+  prompt: "slow cinematic push-in",
+  duration: 5,
+  generateAudio: false,
+});
+```
+
 ## 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.
+- `MODELS`, `GENERATION_MODELS`, `UTILITY_MODELS`, `VIDEO_MODELS` - Motif model aliases, fal endpoints, capabilities, pricing, and benchmarks.
+- `FAL_TOOLS`, `FAL_TOOL_IDS`, `buildFalToolRequest`, `isFalToolId` - Normalized fal utility endpoints such as SAM, depth, upscaling, moderation, and background removal.
+- `ASPECT_RATIOS`, `RESOLUTIONS`, `FORMAT_PRESETS`, `aspectToGptSize`, `aspectToFalImageSize` - Shared sizing metadata and normalization helpers.
+- `IMAGE_TEXT_TO_IMAGE_TOP_20`, `IMAGE_EDITING_TOP_20`, `VIDEO_TEXT_TO_VIDEO_TOP_15`, `VIDEO_IMAGE_TO_VIDEO_TOP_15` - Bundled Artificial Analysis snapshots.
+- `estimateCost`, `estimateVideoCost` - Local cost estimates used by CLI dry runs and SDK previews.
 - `getFalKeyFromEnv` - `@howells/envy` backed `FAL_KEY` parsing.
+- Re-exported `neverthrow` helpers: `ok`, `err`, `Result`, `ResultAsync`.
+
+## Common Types
+
+The package exports public types for generation, processing, queue, metadata, and utility tools:
+
+- `GenerateOptions`, `MotifResponse`, `MotifImage`
+- `UpscaleOptions`, `RemoveBackgroundOptions`, `VideoOptions`, `VideoResponse`
+- `QueuedJob`, `JobStatus`, `MotifServerConfig`
+- `ModelConfig`, `AspectRatio`, `Resolution`, `ImageSize`, `ImageQuality`, `BackgroundMode`, `ThinkingLevel`
+- `FalToolConfig`, `FalToolId`, `FalToolRequest`, `FalToolRunOptions`
 
 ## Testing
 
@@ -48,4 +129,3 @@ 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

@@ -21,6 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ASPECT_RATIOS: () => ASPECT_RATIOS,
+  CREATIVE_FIELDS: () => CREATIVE_FIELDS,
+  CREATIVE_TAXONOMY: () => CREATIVE_TAXONOMY,
+  CreativeOptionError: () => CreativeOptionError,
   FAL_TOOLS: () => FAL_TOOLS,
   FAL_TOOLS_CHECKED_AT: () => FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS: () => FAL_TOOL_IDS,
@@ -42,6 +45,7 @@ __export(index_exports, {
   aspectToGptSize: () => aspectToGptSize,
   buildFalToolRequest: () => buildFalToolRequest,
   buildGenerateBody: () => buildGenerateBody,
+  enrichPrompt: () => enrichPrompt,
   err: () => import_neverthrow2.err,
   estimateCost: () => estimateCost,
   estimateVideoCost: () => estimateVideoCost,
@@ -49,7 +53,8 @@ __export(index_exports, {
   isFalToolId: () => isFalToolId,
   motifEnvSchema: () => motifEnvSchema,
   ok: () => import_neverthrow2.ok,
-  parseMotifEnv: () => parseMotifEnv
+  parseMotifEnv: () => parseMotifEnv,
+  sanitizePrompt: () => sanitizePrompt
 });
 module.exports = __toCommonJS(index_exports);
 var import_neverthrow2 = require("neverthrow");
@@ -969,6 +974,136 @@ function estimateVideoCost(durationSeconds = 5, generateAudio = true) {
   return perSecond * durationSeconds;
 }
 
+// src/creative.ts
+var CONTROL_CHAR_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+var CreativeOptionError = class extends Error {
+  availableIds;
+  code = "INVALID_OPTION";
+  field;
+  value;
+  constructor(details) {
+    super(
+      `Unknown creative ${details.field}: ${details.value}. Available: ${details.availableIds.join(", ")}`
+    );
+    this.name = "CreativeOptionError";
+    this.availableIds = details.availableIds;
+    this.field = details.field;
+    this.value = details.value;
+  }
+};
+var CREATIVE_FIELDS = [
+  "recipe",
+  "shot",
+  "lighting",
+  "genre",
+  "camera",
+  "color",
+  "material",
+  "motion"
+];
+var CREATIVE_TAXONOMY = {
+  recipe: [
+    {
+      clause: "cinematic scene",
+      description: "Frames the prompt as a cinematic still or scene.",
+      id: "cinematic",
+      label: "Cinematic"
+    }
+  ],
+  shot: [
+    {
+      clause: "close-up composition with controlled depth of field",
+      description: "Tight framing that emphasizes subject detail.",
+      id: "close-up",
+      label: "Close-up"
+    }
+  ],
+  lighting: [
+    {
+      clause: "rim lighting with defined edge highlights",
+      description: "Back or side light that separates the subject edge.",
+      id: "rim",
+      label: "Rim"
+    }
+  ],
+  genre: [
+    {
+      clause: "film noir mood with high contrast shadows",
+      description: "High-contrast cinematic mood with shadow-forward drama.",
+      id: "film-noir",
+      label: "Film noir"
+    }
+  ],
+  camera: [
+    {
+      clause: "macro product photography with crisp surface detail",
+      description: "Product-oriented macro camera language for close detail.",
+      id: "macro-product",
+      label: "Macro product"
+    }
+  ],
+  color: [
+    {
+      clause: "monochrome palette with tonal contrast",
+      description: "Black-and-white or single-channel tonal treatment.",
+      id: "monochrome",
+      label: "Monochrome"
+    }
+  ],
+  material: [
+    {
+      clause: "reflective material surfaces with controlled highlights",
+      description: "Emphasizes reflections and highlight control on surfaces.",
+      id: "reflective",
+      label: "Reflective"
+    }
+  ],
+  motion: [
+    {
+      clause: "still composition with no motion blur",
+      description: "Freezes the subject without implied movement.",
+      id: "still",
+      label: "Still"
+    }
+  ]
+};
+function sanitizePrompt(prompt) {
+  return prompt.replace(CONTROL_CHAR_REGEX, "").replace(/\r\n/g, "\n").trim();
+}
+function enrichPrompt(options) {
+  const basePrompt = sanitizePrompt(options.prompt);
+  const clauses = [];
+  const selected = {};
+  for (const field of CREATIVE_FIELDS) {
+    const optionId = options.creative?.[field];
+    if (!optionId) {
+      continue;
+    }
+    const option = CREATIVE_TAXONOMY[field].find(
+      (candidate) => candidate.id === optionId
+    );
+    if (!option) {
+      throw new CreativeOptionError({
+        availableIds: CREATIVE_TAXONOMY[field].map((candidate) => candidate.id),
+        field,
+        value: optionId
+      });
+    }
+    selected[field] = option.id;
+    if (!clauses.includes(option.clause)) {
+      clauses.push(option.clause);
+    }
+  }
+  return {
+    basePrompt,
+    creative: {
+      clauses,
+      selected
+    },
+    prompt: clauses.length ? [basePrompt, ...clauses].join(", ") : basePrompt
+  };
+}
+
 // src/env.ts
 var import_envy = require("@howells/envy");
 var import_zod = require("zod");
@@ -1135,6 +1270,7 @@ function buildGenerateBody(options) {
   const {
     prompt,
     model,
+    creative,
     aspect = "1:1",
     resolution = "2K",
     numImages = 1,
@@ -1169,7 +1305,8 @@ function buildGenerateBody(options) {
     throw new Error(`Unknown model: ${model}`);
   }
   let endpoint = config.endpoint;
-  const body = { prompt };
+  const enrichedPrompt = creative ? enrichPrompt({ prompt, creative }).prompt : prompt;
+  const body = { prompt: enrichedPrompt };
   const hasEditImages = Boolean(editImageUrls?.length);
   const editImages = editImageUrls ?? [];
   const explicitAspect = options.aspect !== void 0;
@@ -2115,6 +2252,23 @@ var FAL_TOOLS = {
       output_format: "png"
     }
   },
+  "sam3-1-image": {
+    name: "SAM 3.1 Image",
+    endpoint: "fal-ai/sam-3-1/image",
+    task: "promptable image segmentation",
+    category: "segmentation",
+    description: "Segment image objects with text, point, or box prompts. SAM 3.1 adds Object Multiplex for faster multi-object tracking.",
+    inputKind: "image",
+    inputField: "image_url",
+    outputKeys: ["image", "masks", "metadata", "scores", "boxes"],
+    pricing: "$0.005/request",
+    sourceUrl: "https://fal.ai/models/fal-ai/sam-3-1/image",
+    defaultOptions: {
+      apply_mask: true,
+      max_masks: 3,
+      output_format: "png"
+    }
+  },
   "sam3-image-rle": {
     name: "SAM 3 Image RLE",
     endpoint: "fal-ai/sam-3/image-rle",
@@ -2743,6 +2897,9 @@ var MotifError = class extends Error {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ASPECT_RATIOS,
+  CREATIVE_FIELDS,
+  CREATIVE_TAXONOMY,
+  CreativeOptionError,
   FAL_TOOLS,
   FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS,
@@ -2764,6 +2921,7 @@ var MotifError = class extends Error {
   aspectToGptSize,
   buildFalToolRequest,
   buildGenerateBody,
+  enrichPrompt,
   err,
   estimateCost,
   estimateVideoCost,
@@ -2771,5 +2929,6 @@ var MotifError = class extends Error {
   isFalToolId,
   motifEnvSchema,
   ok,
-  parseMotifEnv
+  parseMotifEnv,
+  sanitizePrompt
 });

package/dist/index.d.cts

@@ -3,6 +3,143 @@ export { Result, ResultAsync, err, ok } from 'neverthrow';
 import * as _howells_envy from '@howells/envy';
 import { z } from 'zod';
 
+/**
+ * Creative direction fields applied to prompts in Motif's canonical order.
+ *
+ * The order matters when multiple fields are selected because prompt clauses
+ * are appended in this sequence for stable dry runs, tests, and history.
+ */
+type CreativeField = "recipe" | "shot" | "lighting" | "genre" | "camera" | "color" | "material" | "motion";
+/**
+ * Selected creative option ids keyed by direction field.
+ *
+ * Values must match option ids from `CREATIVE_TAXONOMY`; unknown ids throw a
+ * `CreativeOptionError` before any fal request body is built.
+ */
+type CreativeDirection = Partial<Record<CreativeField, string>>;
+/** A single selectable creative direction option exposed to CLI and MCP schemas. */
+interface CreativeOption {
+    /** Prompt fragment appended when this option is selected. */
+    clause: string;
+    /** Human-facing explanation used in schema metadata and generated docs. */
+    description: string;
+    /** Stable machine id accepted by `CreativeDirection`. */
+    id: string;
+    /** Short display label for UIs and schema enum descriptions. */
+    label: string;
+}
+/** Structured details returned when a creative direction id is not recognized. */
+interface CreativeOptionErrorDetails {
+    availableIds: string[];
+    code: "INVALID_OPTION";
+    field: CreativeField;
+    value: string;
+}
+/**
+ * Error thrown when prompt enrichment receives an unknown creative option id.
+ *
+ * The extra fields make CLI and agent callers able to show field-specific
+ * recovery hints without parsing the error message.
+ */
+declare class CreativeOptionError extends Error implements CreativeOptionErrorDetails {
+    readonly availableIds: string[];
+    readonly code = "INVALID_OPTION";
+    readonly field: CreativeField;
+    readonly value: string;
+    constructor(details: Omit<CreativeOptionErrorDetails, "code">);
+}
+/** Canonical creative field order used for prompt enrichment and schema output. */
+declare const CREATIVE_FIELDS: readonly ["recipe", "shot", "lighting", "genre", "camera", "color", "material", "motion"];
+/**
+ * Built-in creative direction catalog.
+ *
+ * Each field contains the option ids accepted by `CreativeDirection` and the
+ * exact prompt clause that will be appended when selected.
+ */
+declare const CREATIVE_TAXONOMY: {
+    readonly recipe: readonly [{
+        readonly clause: "cinematic scene";
+        readonly description: "Frames the prompt as a cinematic still or scene.";
+        readonly id: "cinematic";
+        readonly label: "Cinematic";
+    }];
+    readonly shot: readonly [{
+        readonly clause: "close-up composition with controlled depth of field";
+        readonly description: "Tight framing that emphasizes subject detail.";
+        readonly id: "close-up";
+        readonly label: "Close-up";
+    }];
+    readonly lighting: readonly [{
+        readonly clause: "rim lighting with defined edge highlights";
+        readonly description: "Back or side light that separates the subject edge.";
+        readonly id: "rim";
+        readonly label: "Rim";
+    }];
+    readonly genre: readonly [{
+        readonly clause: "film noir mood with high contrast shadows";
+        readonly description: "High-contrast cinematic mood with shadow-forward drama.";
+        readonly id: "film-noir";
+        readonly label: "Film noir";
+    }];
+    readonly camera: readonly [{
+        readonly clause: "macro product photography with crisp surface detail";
+        readonly description: "Product-oriented macro camera language for close detail.";
+        readonly id: "macro-product";
+        readonly label: "Macro product";
+    }];
+    readonly color: readonly [{
+        readonly clause: "monochrome palette with tonal contrast";
+        readonly description: "Black-and-white or single-channel tonal treatment.";
+        readonly id: "monochrome";
+        readonly label: "Monochrome";
+    }];
+    readonly material: readonly [{
+        readonly clause: "reflective material surfaces with controlled highlights";
+        readonly description: "Emphasizes reflections and highlight control on surfaces.";
+        readonly id: "reflective";
+        readonly label: "Reflective";
+    }];
+    readonly motion: readonly [{
+        readonly clause: "still composition with no motion blur";
+        readonly description: "Freezes the subject without implied movement.";
+        readonly id: "still";
+        readonly label: "Still";
+    }];
+};
+/** Result of applying creative direction to a base prompt. */
+interface CreativePromptResult {
+    /** Sanitized user prompt before Motif adds creative clauses. */
+    basePrompt: string;
+    creative: {
+        /** Clauses appended to the prompt, de-duplicated in canonical field order. */
+        clauses: string[];
+        /** Validated option ids that were applied. */
+        selected: CreativeDirection;
+    };
+    /** Final prompt sent to fal after creative enrichment. */
+    prompt: string;
+}
+/** Input for Motif's prompt enrichment step. */
+interface EnrichPromptOptions {
+    /** Optional selected creative option ids. */
+    creative?: CreativeDirection;
+    /** User-authored prompt before Motif normalization and enrichment. */
+    prompt: string;
+}
+/**
+ * Remove control characters and surrounding whitespace from a prompt.
+ *
+ * Newline style is normalized to `\n`; other text content is left unchanged.
+ */
+declare function sanitizePrompt(prompt: string): string;
+/**
+ * Append selected creative direction clauses to a prompt.
+ *
+ * Options are validated against `CREATIVE_TAXONOMY`, applied in
+ * `CREATIVE_FIELDS` order, and returned as metadata alongside the final prompt.
+ */
+declare function enrichPrompt(options: EnrichPromptOptions): CreativePromptResult;
+
 /** ─── Model Types ─────────────────────────────────────────────── */
 type AspectRatio = "auto" | "8:1" | "4:1" | "21:9" | "16:9" | "3:2" | "4:3" | "5:4" | "1:1" | "4:5" | "3:4" | "2:3" | "9:16" | "1:4" | "1:8";
 type Resolution = "0.5K" | "1K" | "2K" | "4K";
@@ -104,6 +241,13 @@ interface GenerateOptions {
     aspect?: AspectRatio;
     /** GPT background mode where supported */
     background?: BackgroundMode;
+    /**
+     * Motif prompt enrichment choices applied before fal request construction.
+     *
+     * These options are not sent to fal directly; they append validated creative
+     * clauses to `prompt` and are omitted from the final request body.
+     */
+    creative?: CreativeDirection;
     editImageUrls?: string[];
     /** Ask fal not to store IO payloads, and expose request ids for deletion. */
     ephemeral?: boolean;
@@ -639,6 +783,23 @@ declare class MotifServer {
                 readonly output_format: "png";
             };
         };
+        readonly "sam3-1-image": {
+            readonly name: "SAM 3.1 Image";
+            readonly endpoint: "fal-ai/sam-3-1/image";
+            readonly task: "promptable image segmentation";
+            readonly category: "segmentation";
+            readonly description: "Segment image objects with text, point, or box prompts. SAM 3.1 adds Object Multiplex for faster multi-object tracking.";
+            readonly inputKind: "image";
+            readonly inputField: "image_url";
+            readonly outputKeys: ["image", "masks", "metadata", "scores", "boxes"];
+            readonly pricing: "$0.005/request";
+            readonly sourceUrl: "https://fal.ai/models/fal-ai/sam-3-1/image";
+            readonly defaultOptions: {
+                readonly apply_mask: true;
+                readonly max_masks: 3;
+                readonly output_format: "png";
+            };
+        };
         readonly "sam3-image-rle": {
             readonly name: "SAM 3 Image RLE";
             readonly endpoint: "fal-ai/sam-3/image-rle";
@@ -1019,6 +1180,23 @@ declare const FAL_TOOLS: {
             readonly output_format: "png";
         };
     };
+    readonly "sam3-1-image": {
+        readonly name: "SAM 3.1 Image";
+        readonly endpoint: "fal-ai/sam-3-1/image";
+        readonly task: "promptable image segmentation";
+        readonly category: "segmentation";
+        readonly description: "Segment image objects with text, point, or box prompts. SAM 3.1 adds Object Multiplex for faster multi-object tracking.";
+        readonly inputKind: "image";
+        readonly inputField: "image_url";
+        readonly outputKeys: ["image", "masks", "metadata", "scores", "boxes"];
+        readonly pricing: "$0.005/request";
+        readonly sourceUrl: "https://fal.ai/models/fal-ai/sam-3-1/image";
+        readonly defaultOptions: {
+            readonly apply_mask: true;
+            readonly max_masks: 3;
+            readonly output_format: "png";
+        };
+    };
     readonly "sam3-image-rle": {
         readonly name: "SAM 3 Image RLE";
         readonly endpoint: "fal-ai/sam-3/image-rle";
@@ -1137,4 +1315,4 @@ type FalToolId = (typeof FAL_TOOL_IDS)[number];
 declare function isFalToolId(tool: string): tool is FalToolId;
 declare function buildFalToolRequest(options: FalToolRunOptions): FalToolRequest;
 
-export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, type CustomImageSize, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv };
+export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };

package/dist/index.d.ts

@@ -3,6 +3,143 @@ export { Result, ResultAsync, err, ok } from 'neverthrow';
 import * as _howells_envy from '@howells/envy';
 import { z } from 'zod';
 
+/**
+ * Creative direction fields applied to prompts in Motif's canonical order.
+ *
+ * The order matters when multiple fields are selected because prompt clauses
+ * are appended in this sequence for stable dry runs, tests, and history.
+ */
+type CreativeField = "recipe" | "shot" | "lighting" | "genre" | "camera" | "color" | "material" | "motion";
+/**
+ * Selected creative option ids keyed by direction field.
+ *
+ * Values must match option ids from `CREATIVE_TAXONOMY`; unknown ids throw a
+ * `CreativeOptionError` before any fal request body is built.
+ */
+type CreativeDirection = Partial<Record<CreativeField, string>>;
+/** A single selectable creative direction option exposed to CLI and MCP schemas. */
+interface CreativeOption {
+    /** Prompt fragment appended when this option is selected. */
+    clause: string;
+    /** Human-facing explanation used in schema metadata and generated docs. */
+    description: string;
+    /** Stable machine id accepted by `CreativeDirection`. */
+    id: string;
+    /** Short display label for UIs and schema enum descriptions. */
+    label: string;
+}
+/** Structured details returned when a creative direction id is not recognized. */
+interface CreativeOptionErrorDetails {
+    availableIds: string[];
+    code: "INVALID_OPTION";
+    field: CreativeField;
+    value: string;
+}
+/**
+ * Error thrown when prompt enrichment receives an unknown creative option id.
+ *
+ * The extra fields make CLI and agent callers able to show field-specific
+ * recovery hints without parsing the error message.
+ */
+declare class CreativeOptionError extends Error implements CreativeOptionErrorDetails {
+    readonly availableIds: string[];
+    readonly code = "INVALID_OPTION";
+    readonly field: CreativeField;
+    readonly value: string;
+    constructor(details: Omit<CreativeOptionErrorDetails, "code">);
+}
+/** Canonical creative field order used for prompt enrichment and schema output. */
+declare const CREATIVE_FIELDS: readonly ["recipe", "shot", "lighting", "genre", "camera", "color", "material", "motion"];
+/**
+ * Built-in creative direction catalog.
+ *
+ * Each field contains the option ids accepted by `CreativeDirection` and the
+ * exact prompt clause that will be appended when selected.
+ */
+declare const CREATIVE_TAXONOMY: {
+    readonly recipe: readonly [{
+        readonly clause: "cinematic scene";
+        readonly description: "Frames the prompt as a cinematic still or scene.";
+        readonly id: "cinematic";
+        readonly label: "Cinematic";
+    }];
+    readonly shot: readonly [{
+        readonly clause: "close-up composition with controlled depth of field";
+        readonly description: "Tight framing that emphasizes subject detail.";
+        readonly id: "close-up";
+        readonly label: "Close-up";
+    }];
+    readonly lighting: readonly [{
+        readonly clause: "rim lighting with defined edge highlights";
+        readonly description: "Back or side light that separates the subject edge.";
+        readonly id: "rim";
+        readonly label: "Rim";
+    }];
+    readonly genre: readonly [{
+        readonly clause: "film noir mood with high contrast shadows";
+        readonly description: "High-contrast cinematic mood with shadow-forward drama.";
+        readonly id: "film-noir";
+        readonly label: "Film noir";
+    }];
+    readonly camera: readonly [{
+        readonly clause: "macro product photography with crisp surface detail";
+        readonly description: "Product-oriented macro camera language for close detail.";
+        readonly id: "macro-product";
+        readonly label: "Macro product";
+    }];
+    readonly color: readonly [{
+        readonly clause: "monochrome palette with tonal contrast";
+        readonly description: "Black-and-white or single-channel tonal treatment.";
+        readonly id: "monochrome";
+        readonly label: "Monochrome";
+    }];
+    readonly material: readonly [{
+        readonly clause: "reflective material surfaces with controlled highlights";
+        readonly description: "Emphasizes reflections and highlight control on surfaces.";
+        readonly id: "reflective";
+        readonly label: "Reflective";
+    }];
+    readonly motion: readonly [{
+        readonly clause: "still composition with no motion blur";
+        readonly description: "Freezes the subject without implied movement.";
+        readonly id: "still";
+        readonly label: "Still";
+    }];
+};
+/** Result of applying creative direction to a base prompt. */
+interface CreativePromptResult {
+    /** Sanitized user prompt before Motif adds creative clauses. */
+    basePrompt: string;
+    creative: {
+        /** Clauses appended to the prompt, de-duplicated in canonical field order. */
+        clauses: string[];
+        /** Validated option ids that were applied. */
+        selected: CreativeDirection;
+    };
+    /** Final prompt sent to fal after creative enrichment. */
+    prompt: string;
+}
+/** Input for Motif's prompt enrichment step. */
+interface EnrichPromptOptions {
+    /** Optional selected creative option ids. */
+    creative?: CreativeDirection;
+    /** User-authored prompt before Motif normalization and enrichment. */
+    prompt: string;
+}
+/**
+ * Remove control characters and surrounding whitespace from a prompt.
+ *
+ * Newline style is normalized to `\n`; other text content is left unchanged.
+ */
+declare function sanitizePrompt(prompt: string): string;
+/**
+ * Append selected creative direction clauses to a prompt.
+ *
+ * Options are validated against `CREATIVE_TAXONOMY`, applied in
+ * `CREATIVE_FIELDS` order, and returned as metadata alongside the final prompt.
+ */
+declare function enrichPrompt(options: EnrichPromptOptions): CreativePromptResult;
+
 /** ─── Model Types ─────────────────────────────────────────────── */
 type AspectRatio = "auto" | "8:1" | "4:1" | "21:9" | "16:9" | "3:2" | "4:3" | "5:4" | "1:1" | "4:5" | "3:4" | "2:3" | "9:16" | "1:4" | "1:8";
 type Resolution = "0.5K" | "1K" | "2K" | "4K";
@@ -104,6 +241,13 @@ interface GenerateOptions {
     aspect?: AspectRatio;
     /** GPT background mode where supported */
     background?: BackgroundMode;
+    /**
+     * Motif prompt enrichment choices applied before fal request construction.
+     *
+     * These options are not sent to fal directly; they append validated creative
+     * clauses to `prompt` and are omitted from the final request body.
+     */
+    creative?: CreativeDirection;
     editImageUrls?: string[];
     /** Ask fal not to store IO payloads, and expose request ids for deletion. */
     ephemeral?: boolean;
@@ -639,6 +783,23 @@ declare class MotifServer {
                 readonly output_format: "png";
             };
         };
+        readonly "sam3-1-image": {
+            readonly name: "SAM 3.1 Image";
+            readonly endpoint: "fal-ai/sam-3-1/image";
+            readonly task: "promptable image segmentation";
+            readonly category: "segmentation";
+            readonly description: "Segment image objects with text, point, or box prompts. SAM 3.1 adds Object Multiplex for faster multi-object tracking.";
+            readonly inputKind: "image";
+            readonly inputField: "image_url";
+            readonly outputKeys: ["image", "masks", "metadata", "scores", "boxes"];
+            readonly pricing: "$0.005/request";
+            readonly sourceUrl: "https://fal.ai/models/fal-ai/sam-3-1/image";
+            readonly defaultOptions: {
+                readonly apply_mask: true;
+                readonly max_masks: 3;
+                readonly output_format: "png";
+            };
+        };
         readonly "sam3-image-rle": {
             readonly name: "SAM 3 Image RLE";
             readonly endpoint: "fal-ai/sam-3/image-rle";
@@ -1019,6 +1180,23 @@ declare const FAL_TOOLS: {
             readonly output_format: "png";
         };
     };
+    readonly "sam3-1-image": {
+        readonly name: "SAM 3.1 Image";
+        readonly endpoint: "fal-ai/sam-3-1/image";
+        readonly task: "promptable image segmentation";
+        readonly category: "segmentation";
+        readonly description: "Segment image objects with text, point, or box prompts. SAM 3.1 adds Object Multiplex for faster multi-object tracking.";
+        readonly inputKind: "image";
+        readonly inputField: "image_url";
+        readonly outputKeys: ["image", "masks", "metadata", "scores", "boxes"];
+        readonly pricing: "$0.005/request";
+        readonly sourceUrl: "https://fal.ai/models/fal-ai/sam-3-1/image";
+        readonly defaultOptions: {
+            readonly apply_mask: true;
+            readonly max_masks: 3;
+            readonly output_format: "png";
+        };
+    };
     readonly "sam3-image-rle": {
         readonly name: "SAM 3 Image RLE";
         readonly endpoint: "fal-ai/sam-3/image-rle";
@@ -1137,4 +1315,4 @@ type FalToolId = (typeof FAL_TOOL_IDS)[number];
 declare function isFalToolId(tool: string): tool is FalToolId;
 declare function buildFalToolRequest(options: FalToolRunOptions): FalToolRequest;
 
-export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, type CustomImageSize, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv };
+export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };

package/dist/index.js

@@ -916,6 +916,136 @@ function estimateVideoCost(durationSeconds = 5, generateAudio = true) {
   return perSecond * durationSeconds;
 }
 
+// src/creative.ts
+var CONTROL_CHAR_REGEX = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+var CreativeOptionError = class extends Error {
+  availableIds;
+  code = "INVALID_OPTION";
+  field;
+  value;
+  constructor(details) {
+    super(
+      `Unknown creative ${details.field}: ${details.value}. Available: ${details.availableIds.join(", ")}`
+    );
+    this.name = "CreativeOptionError";
+    this.availableIds = details.availableIds;
+    this.field = details.field;
+    this.value = details.value;
+  }
+};
+var CREATIVE_FIELDS = [
+  "recipe",
+  "shot",
+  "lighting",
+  "genre",
+  "camera",
+  "color",
+  "material",
+  "motion"
+];
+var CREATIVE_TAXONOMY = {
+  recipe: [
+    {
+      clause: "cinematic scene",
+      description: "Frames the prompt as a cinematic still or scene.",
+      id: "cinematic",
+      label: "Cinematic"
+    }
+  ],
+  shot: [
+    {
+      clause: "close-up composition with controlled depth of field",
+      description: "Tight framing that emphasizes subject detail.",
+      id: "close-up",
+      label: "Close-up"
+    }
+  ],
+  lighting: [
+    {
+      clause: "rim lighting with defined edge highlights",
+      description: "Back or side light that separates the subject edge.",
+      id: "rim",
+      label: "Rim"
+    }
+  ],
+  genre: [
+    {
+      clause: "film noir mood with high contrast shadows",
+      description: "High-contrast cinematic mood with shadow-forward drama.",
+      id: "film-noir",
+      label: "Film noir"
+    }
+  ],
+  camera: [
+    {
+      clause: "macro product photography with crisp surface detail",
+      description: "Product-oriented macro camera language for close detail.",
+      id: "macro-product",
+      label: "Macro product"
+    }
+  ],
+  color: [
+    {
+      clause: "monochrome palette with tonal contrast",
+      description: "Black-and-white or single-channel tonal treatment.",
+      id: "monochrome",
+      label: "Monochrome"
+    }
+  ],
+  material: [
+    {
+      clause: "reflective material surfaces with controlled highlights",
+      description: "Emphasizes reflections and highlight control on surfaces.",
+      id: "reflective",
+      label: "Reflective"
+    }
+  ],
+  motion: [
+    {
+      clause: "still composition with no motion blur",
+      description: "Freezes the subject without implied movement.",
+      id: "still",
+      label: "Still"
+    }
+  ]
+};
+function sanitizePrompt(prompt) {
+  return prompt.replace(CONTROL_CHAR_REGEX, "").replace(/\r\n/g, "\n").trim();
+}
+function enrichPrompt(options) {
+  const basePrompt = sanitizePrompt(options.prompt);
+  const clauses = [];
+  const selected = {};
+  for (const field of CREATIVE_FIELDS) {
+    const optionId = options.creative?.[field];
+    if (!optionId) {
+      continue;
+    }
+    const option = CREATIVE_TAXONOMY[field].find(
+      (candidate) => candidate.id === optionId
+    );
+    if (!option) {
+      throw new CreativeOptionError({
+        availableIds: CREATIVE_TAXONOMY[field].map((candidate) => candidate.id),
+        field,
+        value: optionId
+      });
+    }
+    selected[field] = option.id;
+    if (!clauses.includes(option.clause)) {
+      clauses.push(option.clause);
+    }
+  }
+  return {
+    basePrompt,
+    creative: {
+      clauses,
+      selected
+    },
+    prompt: clauses.length ? [basePrompt, ...clauses].join(", ") : basePrompt
+  };
+}
+
 // src/env.ts
 import { defineEnv } from "@howells/envy";
 import { z } from "zod";
@@ -1082,6 +1212,7 @@ function buildGenerateBody(options) {
   const {
     prompt,
     model,
+    creative,
     aspect = "1:1",
     resolution = "2K",
     numImages = 1,
@@ -1116,7 +1247,8 @@ function buildGenerateBody(options) {
     throw new Error(`Unknown model: ${model}`);
   }
   let endpoint = config.endpoint;
-  const body = { prompt };
+  const enrichedPrompt = creative ? enrichPrompt({ prompt, creative }).prompt : prompt;
+  const body = { prompt: enrichedPrompt };
   const hasEditImages = Boolean(editImageUrls?.length);
   const editImages = editImageUrls ?? [];
   const explicitAspect = options.aspect !== void 0;
@@ -2062,6 +2194,23 @@ var FAL_TOOLS = {
       output_format: "png"
     }
   },
+  "sam3-1-image": {
+    name: "SAM 3.1 Image",
+    endpoint: "fal-ai/sam-3-1/image",
+    task: "promptable image segmentation",
+    category: "segmentation",
+    description: "Segment image objects with text, point, or box prompts. SAM 3.1 adds Object Multiplex for faster multi-object tracking.",
+    inputKind: "image",
+    inputField: "image_url",
+    outputKeys: ["image", "masks", "metadata", "scores", "boxes"],
+    pricing: "$0.005/request",
+    sourceUrl: "https://fal.ai/models/fal-ai/sam-3-1/image",
+    defaultOptions: {
+      apply_mask: true,
+      max_masks: 3,
+      output_format: "png"
+    }
+  },
   "sam3-image-rle": {
     name: "SAM 3 Image RLE",
     endpoint: "fal-ai/sam-3/image-rle",
@@ -2689,6 +2838,9 @@ var MotifError = class extends Error {
 };
 export {
   ASPECT_RATIOS,
+  CREATIVE_FIELDS,
+  CREATIVE_TAXONOMY,
+  CreativeOptionError,
   FAL_TOOLS,
   FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS,
@@ -2710,6 +2862,7 @@ export {
   aspectToGptSize,
   buildFalToolRequest,
   buildGenerateBody,
+  enrichPrompt,
   err2 as err,
   estimateCost,
   estimateVideoCost,
@@ -2717,5 +2870,6 @@ export {
   isFalToolId,
   motifEnvSchema,
   ok2 as ok,
-  parseMotifEnv
+  parseMotifEnv,
+  sanitizePrompt
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "license": "MIT",
   "author": "Daniel Howells",
@@ -37,6 +37,17 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "howells-lint",
+    "format": "howells-format",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepack": "pnpm build"
+  },
   "dependencies": {
     "@howells/envy": "^0.3.7",
     "neverthrow": "^8.2.0",
@@ -50,15 +61,5 @@
     "tsup": "^8.0.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "lint": "howells-lint",
-    "format": "howells-format",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Daniel Howells
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.