@howells/motif-sdk 0.11.0 → 0.12.0

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,6 +29,7 @@ __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,
@@ -2714,7 +2715,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;
@@ -3236,6 +3237,7 @@ var MotifServer = class {
     });
   }
 };
+var MotifServer = FalClient;
 var MotifError = class extends Error {
   status;
   code;
@@ -3269,6 +3271,7 @@ function toMotifError(error) {
   FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS,
   FORMAT_PRESETS,
+  FalClient,
   GENERATION_MODELS,
   IDEOGRAM_STYLES,
   IMAGE_EDITING_TOP_20,

package/dist/index.d.cts

@@ -388,13 +388,15 @@ 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;
     /** Request timeout in ms (default 120_000) */
     timeout?: number;
 }
+/** @deprecated Renamed to {@link FalClientConfig}. */
+type MotifServerConfig = FalClientConfig;
 
 /** Ordered by popularity: square first, then common ratios */
 declare const ASPECT_RATIOS: AspectRatio[];
@@ -475,16 +477,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 +500,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>>;
@@ -924,6 +930,8 @@ declare class MotifServer {
      */
     private normalizeResponse;
 }
+/** @deprecated Renamed to {@link FalClient}. `MotifServer` is kept as an alias for backwards compatibility and will be removed in 1.0. */
+declare const MotifServer: typeof FalClient;
 declare class MotifError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -1320,4 +1328,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, 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

@@ -388,13 +388,15 @@ 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;
     /** Request timeout in ms (default 120_000) */
     timeout?: number;
 }
+/** @deprecated Renamed to {@link FalClientConfig}. */
+type MotifServerConfig = FalClientConfig;
 
 /** Ordered by popularity: square first, then common ratios */
 declare const ASPECT_RATIOS: AspectRatio[];
@@ -475,16 +477,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 +500,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>>;
@@ -924,6 +930,8 @@ declare class MotifServer {
      */
     private normalizeResponse;
 }
+/** @deprecated Renamed to {@link FalClient}. `MotifServer` is kept as an alias for backwards compatibility and will be removed in 1.0. */
+declare const MotifServer: typeof FalClient;
 declare class MotifError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -1320,4 +1328,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, 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

@@ -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;
@@ -3177,6 +3177,7 @@ var MotifServer = class {
     });
   }
 };
+var MotifServer = FalClient;
 var MotifError = class extends Error {
   status;
   code;
@@ -3209,6 +3210,7 @@ export {
   FAL_TOOLS_CHECKED_AT,
   FAL_TOOL_IDS,
   FORMAT_PRESETS,
+  FalClient,
   GENERATION_MODELS,
   IDEOGRAM_STYLES,
   IMAGE_EDITING_TOP_20,

package/package.json

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