@howells/motif-sdk 0.11.0 → 1.0.0

package/README.md

@@ -10,10 +10,14 @@ npm install @howells/motif-sdk
 
 ## Generate Images
 
+The primary image API is `createMotifImage` (`@howells/motif-sdk/image`) — provider-agnostic generate/edit across google, openai, replicate, and fal. See [Image Layer](#image-layer-howellsmotif-sdkimage) below.
+
+The examples in this section use the low-level `FalClient`, the fal-native client for fal-specific capabilities (queue, upload, upscale, background removal, video, and utility tools).
+
 ```ts
-import { MotifServer } from "@howells/motif-sdk";
+import { FalClient } from "@howells/motif-sdk";
 
-const motif = new MotifServer({
+const motif = new FalClient({
   apiKey: process.env.FAL_KEY!,
   retries: 3,
   timeout: 120_000,
@@ -103,7 +107,8 @@ const videoJob = await motif.submitVideo({
 
 ## Main Exports
 
-- `MotifServer` - Result-returning fal client for generation, queue jobs, upload, utility tools, and payload deletion.
+- `createMotifImage` (`@howells/motif-sdk/image`) - the primary image API: provider-agnostic generate/edit/best-of-N across google, openai, replicate, and fal.
+- `FalClient` - low-level fal-native client for generation, queue jobs, upload, utility tools, and payload deletion.
 - `buildGenerateBody` - Pure fal request normalization for dry runs and tests.
 - `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.
@@ -119,13 +124,13 @@ The package exports public types for generation, processing, queue, metadata, an
 
 - `GenerateOptions`, `MotifResponse`, `MotifImage`
 - `UpscaleOptions`, `RemoveBackgroundOptions`, `VideoOptions`, `VideoResponse`
-- `QueuedJob`, `JobStatus`, `MotifServerConfig`
+- `QueuedJob`, `JobStatus`, `FalClientConfig`
 - `ModelConfig`, `AspectRatio`, `Resolution`, `ImageSize`, `ImageQuality`, `BackgroundMode`, `ThinkingLevel`
 - `FalToolConfig`, `FalToolId`, `FalToolRequest`, `FalToolRunOptions`
 
 ## Image Layer (`@howells/motif-sdk/image`)
 
-A provider-agnostic image generation + editing layer, additive to the fal-specific `MotifServer` surface above. It is an ESM-only subpath export, built on the Vercel AI SDK image interface (`ai`'s `generateImage`).
+The primary, provider-agnostic image generation + editing layer — the recommended way to generate and edit images. The fal-specific `FalClient` surface above stays for fal-native extras. It is an ESM-only subpath export, built on the Vercel AI SDK image interface (`ai`'s `generateImage`).
 
 ```bash
 npm install @howells/motif-sdk

package/dist/image.d.ts

@@ -14,7 +14,7 @@ declare class MotifError extends Error {
  * Public types for the provider-agnostic image generation + editing layer
  * (`@howells/motif-sdk/image`).
  *
- * This layer is additive: it sits alongside the fal-specific `MotifServer`
+ * This layer is additive: it sits alongside the fal-specific `FalClient`
  * surface and reuses the SDK's Result convention (`Result<T, MotifError>` — no
  * thrown exceptions). See docs/design/provider-agnostic-image-layer.md.
  */
@@ -364,7 +364,7 @@ declare const REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
  * Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/fal`. Building a model
  * performs no network I/O — the request only happens when `generateImage`
  * invokes `model.doGenerate`. This is the lightweight fal *image* adapter; the
- * richer `MotifServer` fal client (queue, upload, upscale, rmbg, video, tools)
+ * richer `FalClient` fal client (queue, upload, upscale, rmbg, video, tools)
  * is a separate, later fold (design doc §8, phase 1d).
  *
  * ENDPOINT QUIRK (Phase 0): fal's gpt-image endpoint wants `image_size` as a
@@ -416,7 +416,7 @@ declare function costForImages(provider: ImageProviderId, modelId: string, provi
  * `@howells/motif-sdk/image` — provider-agnostic image generation + editing.
  *
  * ESM-only subpath export, built on the Vercel AI SDK image interface
- * (`generateImage`, `@ai-sdk/*`). Additive to the fal-specific `MotifServer`
+ * (`generateImage`, `@ai-sdk/*`). Additive to the fal-specific `FalClient`
  * surface; reuses the SDK's Result convention (`Result<T, MotifError>` — no
  * thrown exceptions). Google (Gemini) is the only provider in Phase 1a.
  *

package/dist/index.cjs

@@ -29,13 +29,13 @@ __export(src_exports, {
   FAL_TOOLS_CHECKED_AT: () => FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS: () => FAL_TOOL_IDS,
   FORMAT_PRESETS: () => FORMAT_PRESETS,
+  FalClient: () => FalClient,
   GENERATION_MODELS: () => GENERATION_MODELS,
   IDEOGRAM_STYLES: () => IDEOGRAM_STYLES,
   IMAGE_EDITING_TOP_20: () => IMAGE_EDITING_TOP_20,
   IMAGE_TEXT_TO_IMAGE_TOP_20: () => IMAGE_TEXT_TO_IMAGE_TOP_20,
   MODELS: () => MODELS,
   MotifError: () => MotifError,
-  MotifServer: () => MotifServer,
   RECRAFT_STYLES: () => RECRAFT_STYLES,
   RESOLUTIONS: () => RESOLUTIONS,
   UTILITY_MODELS: () => UTILITY_MODELS,
@@ -2714,7 +2714,7 @@ 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";
-var MotifServer = class {
+var FalClient = class {
   apiKey;
   timeout;
   retries;
@@ -3269,13 +3269,13 @@ function toMotifError(error) {
   FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS,
   FORMAT_PRESETS,
+  FalClient,
   GENERATION_MODELS,
   IDEOGRAM_STYLES,
   IMAGE_EDITING_TOP_20,
   IMAGE_TEXT_TO_IMAGE_TOP_20,
   MODELS,
   MotifError,
-  MotifServer,
   RECRAFT_STYLES,
   RESOLUTIONS,
   UTILITY_MODELS,

package/dist/index.d.cts

@@ -388,7 +388,7 @@ interface JobStatus {
     status: "queued" | "processing" | "completed" | "failed";
 }
 /** ─── Configuration ──────────────────────────────────────────── */
-interface MotifServerConfig {
+interface FalClientConfig {
     apiKey: string;
     /** Max retry attempts for 429/5xx errors (default 3, set 0 to disable) */
     retries?: number;
@@ -475,16 +475,20 @@ declare const RECRAFT_STYLES: readonly ["realistic_image", "realistic_image/b_an
 declare const IDEOGRAM_STYLES: readonly ["AUTO", "GENERAL", "REALISTIC", "DESIGN"];
 
 /**
- * Motif Server SDK
+ * FalClient — the fal-native client.
+ *
+ * The low-level, fal-specific client for AI image generation and fal utilities
+ * (queue, upload, upscale, rmbg, video, tools, generate). Pairs with the
+ * provider-agnostic `createMotifImage` (`@howells/motif-sdk/image`) as the
+ * fal-native entry point.
  *
- * Server-side SDK for AI image generation via fal.ai.
  * All async methods return `Result<T, MotifError>` — no thrown exceptions.
  *
  * @example
  * ```typescript
- * import { MotifServer } from "./fal";
+ * import { FalClient } from "./fal";
  *
- * const motif = new MotifServer(process.env.FAL_KEY!);
+ * const motif = new FalClient(process.env.FAL_KEY!);
  * const result = await motif.generate({ prompt: "a red balloon", model: "banana" });
  *
  * if (result.isOk()) {
@@ -494,11 +498,11 @@ declare const IDEOGRAM_STYLES: readonly ["AUTO", "GENERAL", "REALISTIC", "DESIGN
  * }
  * ```
  */
-declare class MotifServer {
+declare class FalClient {
     private readonly apiKey;
     private readonly timeout;
     private readonly retries;
-    constructor(config: MotifServerConfig | string);
+    constructor(config: FalClientConfig | string);
     /** ─── Synchronous Generation ──────────────────────────────── */
     /** Generate images synchronously (blocks until fal.ai returns). */
     generate(options: GenerateOptions): Promise<Result<MotifResponse, MotifError>>;
@@ -1320,4 +1324,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, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, 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 };
+export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, FalClient, type FalClientConfig, 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, 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

@@ -388,7 +388,7 @@ interface JobStatus {
     status: "queued" | "processing" | "completed" | "failed";
 }
 /** ─── Configuration ──────────────────────────────────────────── */
-interface MotifServerConfig {
+interface FalClientConfig {
     apiKey: string;
     /** Max retry attempts for 429/5xx errors (default 3, set 0 to disable) */
     retries?: number;
@@ -475,16 +475,20 @@ declare const RECRAFT_STYLES: readonly ["realistic_image", "realistic_image/b_an
 declare const IDEOGRAM_STYLES: readonly ["AUTO", "GENERAL", "REALISTIC", "DESIGN"];
 
 /**
- * Motif Server SDK
+ * FalClient — the fal-native client.
+ *
+ * The low-level, fal-specific client for AI image generation and fal utilities
+ * (queue, upload, upscale, rmbg, video, tools, generate). Pairs with the
+ * provider-agnostic `createMotifImage` (`@howells/motif-sdk/image`) as the
+ * fal-native entry point.
  *
- * Server-side SDK for AI image generation via fal.ai.
  * All async methods return `Result<T, MotifError>` — no thrown exceptions.
  *
  * @example
  * ```typescript
- * import { MotifServer } from "./fal";
+ * import { FalClient } from "./fal";
  *
- * const motif = new MotifServer(process.env.FAL_KEY!);
+ * const motif = new FalClient(process.env.FAL_KEY!);
  * const result = await motif.generate({ prompt: "a red balloon", model: "banana" });
  *
  * if (result.isOk()) {
@@ -494,11 +498,11 @@ declare const IDEOGRAM_STYLES: readonly ["AUTO", "GENERAL", "REALISTIC", "DESIGN
  * }
  * ```
  */
-declare class MotifServer {
+declare class FalClient {
     private readonly apiKey;
     private readonly timeout;
     private readonly retries;
-    constructor(config: MotifServerConfig | string);
+    constructor(config: FalClientConfig | string);
     /** ─── Synchronous Generation ──────────────────────────────── */
     /** Generate images synchronously (blocks until fal.ai returns). */
     generate(options: GenerateOptions): Promise<Result<MotifResponse, MotifError>>;
@@ -1320,4 +1324,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, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, 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 };
+export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, FalClient, type FalClientConfig, 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, 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

@@ -2655,7 +2655,7 @@ 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";
-var MotifServer = class {
+var FalClient = class {
   apiKey;
   timeout;
   retries;
@@ -3209,13 +3209,13 @@ export {
   FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS,
   FORMAT_PRESETS,
+  FalClient,
   GENERATION_MODELS,
   IDEOGRAM_STYLES,
   IMAGE_EDITING_TOP_20,
   IMAGE_TEXT_TO_IMAGE_TOP_20,
   MODELS,
   MotifError,
-  MotifServer,
   RECRAFT_STYLES,
   RESOLUTIONS,
   UTILITY_MODELS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "keywords": [
     "fal",