@howells/motif-sdk 0.2.0 → 0.3.1

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");
@@ -936,6 +941,10 @@ function estimateCost(model, resolution, numImages = 1) {
     if ((model === "banana" || model === "gemini3") && resolution === "4K") {
       return configuredPrice * 2 * numImages;
     }
+    if (model === "banana2") {
+      const multiplier = resolution === "4K" ? 2 : resolution === "2K" ? 1.5 : resolution === "0.5K" ? 0.75 : 1;
+      return configuredPrice * multiplier * numImages;
+    }
     return configuredPrice * numImages;
   }
   switch (model) {
@@ -969,6 +978,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 +1274,7 @@ function buildGenerateBody(options) {
   const {
     prompt,
     model,
+    creative,
     aspect = "1:1",
     resolution = "2K",
     numImages = 1,
@@ -1169,7 +1309,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;
@@ -2298,7 +2439,13 @@ var MotifServer = class {
     if (config?.useQueue) {
       return this.generateQueued(options);
     }
-    const { endpoint, body } = buildGenerateBody(options);
+    let built;
+    try {
+      built = buildGenerateBody(options);
+    } catch (error) {
+      return (0, import_neverthrow.err)(toMotifError(error));
+    }
+    const { endpoint, body } = built;
     const response = await this.request(`${FAL_BASE_URL}/${endpoint}`, {
       method: "POST",
       body: JSON.stringify(body),
@@ -2340,7 +2487,13 @@ var MotifServer = class {
   /** ─── Queue-Based Generation ──────────────────────────────── */
   /** Submit a generation to the fal.ai queue (returns immediately). */
   async submitGeneration(options) {
-    const { endpoint, body } = buildGenerateBody(options);
+    let built;
+    try {
+      built = buildGenerateBody(options);
+    } catch (error) {
+      return (0, import_neverthrow.err)(toMotifError(error));
+    }
+    const { endpoint, body } = built;
     const response = await this.request(`${FAL_QUEUE_URL}/${endpoint}`, {
       method: "POST",
       body: JSON.stringify(body),
@@ -2740,9 +2893,20 @@ var MotifError = class extends Error {
     this.code = code;
   }
 };
+function toMotifError(error) {
+  if (error instanceof MotifError) {
+    return error;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
+  return new MotifError(message, 0, code);
+}
 // 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 +2928,7 @@ var MotifError = class extends Error {
   aspectToGptSize,
   buildFalToolRequest,
   buildGenerateBody,
+  enrichPrompt,
   err,
   estimateCost,
   estimateVideoCost,
@@ -2771,5 +2936,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;
@@ -1137,4 +1281,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;
@@ -1137,4 +1281,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

@@ -883,6 +883,10 @@ function estimateCost(model, resolution, numImages = 1) {
     if ((model === "banana" || model === "gemini3") && resolution === "4K") {
       return configuredPrice * 2 * numImages;
     }
+    if (model === "banana2") {
+      const multiplier = resolution === "4K" ? 2 : resolution === "2K" ? 1.5 : resolution === "0.5K" ? 0.75 : 1;
+      return configuredPrice * multiplier * numImages;
+    }
     return configuredPrice * numImages;
   }
   switch (model) {
@@ -916,6 +920,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 +1216,7 @@ function buildGenerateBody(options) {
   const {
     prompt,
     model,
+    creative,
     aspect = "1:1",
     resolution = "2K",
     numImages = 1,
@@ -1116,7 +1251,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;
@@ -2245,7 +2381,13 @@ var MotifServer = class {
     if (config?.useQueue) {
       return this.generateQueued(options);
     }
-    const { endpoint, body } = buildGenerateBody(options);
+    let built;
+    try {
+      built = buildGenerateBody(options);
+    } catch (error) {
+      return err(toMotifError(error));
+    }
+    const { endpoint, body } = built;
     const response = await this.request(`${FAL_BASE_URL}/${endpoint}`, {
       method: "POST",
       body: JSON.stringify(body),
@@ -2287,7 +2429,13 @@ var MotifServer = class {
   /** ─── Queue-Based Generation ──────────────────────────────── */
   /** Submit a generation to the fal.ai queue (returns immediately). */
   async submitGeneration(options) {
-    const { endpoint, body } = buildGenerateBody(options);
+    let built;
+    try {
+      built = buildGenerateBody(options);
+    } catch (error) {
+      return err(toMotifError(error));
+    }
+    const { endpoint, body } = built;
     const response = await this.request(`${FAL_QUEUE_URL}/${endpoint}`, {
       method: "POST",
       body: JSON.stringify(body),
@@ -2687,8 +2835,19 @@ var MotifError = class extends Error {
     this.code = code;
   }
 };
+function toMotifError(error) {
+  if (error instanceof MotifError) {
+    return error;
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : void 0;
+  return new MotifError(message, 0, code);
+}
 export {
   ASPECT_RATIOS,
+  CREATIVE_FIELDS,
+  CREATIVE_TAXONOMY,
+  CreativeOptionError,
   FAL_TOOLS,
   FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS,
@@ -2710,6 +2869,7 @@ export {
   aspectToGptSize,
   buildFalToolRequest,
   buildGenerateBody,
+  enrichPrompt,
   err2 as err,
   estimateCost,
   estimateVideoCost,
@@ -2717,5 +2877,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.1",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "license": "MIT",
   "author": "Daniel Howells",