@howells/motif-sdk 0.7.0 → 0.9.0

package/README.md

@@ -123,6 +123,55 @@ The package exports public types for generation, processing, queue, metadata, an
 - `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`).
+
+```bash
+npm install @howells/motif-sdk
+```
+
+```ts
+import { createMotifImage } from "@howells/motif-sdk/image";
+
+const img = createMotifImage({ defaultProvider: "google" });
+
+// text -> image
+const generated = await img.generate({
+  tier: "fast",
+  prompt: "a plain room, bare concrete wall",
+  aspectRatio: "1:1",
+});
+
+// multi-image edit (images + instruction, optional mask -> image out)
+const edited = await img.edit({
+  tier: "balanced",
+  images: [roomBytes, tileBytes],
+  instruction: "Apply the oak texture from image 2 onto the wall in image 1.",
+  mask: surfaceMaskBytes,
+});
+
+if (edited.isOk()) {
+  edited.value.images; // MotifImageFile[]
+  edited.value.cost; // { usd, source: "provider-metadata" | "table" | "unknown" }
+  edited.value.provider; // resolved ImageProviderId
+  edited.value.model; // resolved model id
+}
+```
+
+Both `generate()` and `edit()` return `Result<MotifImageResult, MotifError>`, matching the rest of the SDK — no throws, check `isOk()` / `isErr()`.
+
+Four providers are implemented, each reading its own API key from the environment (or a `MotifImageConfig` override):
+
+| Provider | Env var | Notes |
+| --- | --- | --- |
+| `google` | `GOOGLE_GENERATIVE_AI_API_KEY` | Default provider; Gemini gen + edit |
+| `openai` | `OPENAI_API_KEY` | gpt-image-1 |
+| `replicate` | `REPLICATE_API_TOKEN` | flux-1.1-pro-ultra |
+| `fal` | `FAL_KEY` | fal-hosted adapter |
+
+`generate()` and `edit()` accept `tier` (`"fast" | "balanced" | "quality" | "hero"`) to resolve a model per provider, or an explicit `model` id. Every result carries a normalized per-call `cost: { usd, source }`.
+
 ## Testing
 
 ```bash

package/dist/image.d.ts

@@ -25,11 +25,11 @@ declare class MotifError extends Error {
  */
 type ImageTier = "fast" | "balanced" | "quality" | "hero";
 /**
- * Image provider id. Only `google` is implemented in Phase 1a; the type is kept
- * an open union so later adapters (fal, openai, replicate) can slot in without a
- * breaking type change.
+ * Image provider id. All four Phase 1b adapters are implemented
+ * (`google`, `openai`, `replicate`, `fal`); the type keeps an open union tail so
+ * further adapters can slot in without a breaking type change.
  */
-type ImageProviderId = "google" | (string & Record<never, never>);
+type ImageProviderId = "google" | "openai" | "replicate" | "fal" | (string & Record<never, never>);
 /** Source that produced a normalized per-call cost. */
 type ImageCostSource = "provider-metadata" | "table" | "unknown";
 /** Normalized per-call spend attached to every result. */
@@ -39,7 +39,12 @@ interface ImageCost {
     /** Where the figure came from: the provider's metadata, the static table, or unknown. */
     source: ImageCostSource;
 }
-/** Client configuration. Provider keys fall back to environment variables. */
+/**
+ * Client configuration. Every provider key is optional and falls back to that
+ * provider's environment variable (see each adapter's `apiKeyEnv`). The config
+ * field name mirrors each SDK's own option name — notably Replicate calls its
+ * credential `apiToken`, not `apiKey`.
+ */
 interface MotifImageConfig {
     /** Provider used when a call does not specify one. Defaults to `google`. */
     defaultProvider?: ImageProviderId;
@@ -47,6 +52,21 @@ interface MotifImageConfig {
     google?: {
         apiKey?: string;
     };
+    /** OpenAI provider overrides. `apiKey` falls back to `OPENAI_API_KEY`. */
+    openai?: {
+        apiKey?: string;
+    };
+    /**
+     * Replicate provider overrides. Replicate's SDK names the credential
+     * `apiToken` (not `apiKey`); it falls back to `REPLICATE_API_TOKEN`.
+     */
+    replicate?: {
+        apiToken?: string;
+    };
+    /** fal provider overrides. `apiKey` falls back to `FAL_KEY`. */
+    fal?: {
+        apiKey?: string;
+    };
 }
 /** Options for a text→image generation. */
 interface GenerateImageOptions {
@@ -58,25 +78,53 @@ interface GenerateImageOptions {
     model?: string;
     /** Provider override for this call. */
     provider?: ImageProviderId;
-    /** Aspect ratio, e.g. `"1:1"`. */
+    /**
+     * Aspect ratio, e.g. `"1:1"`. An alternative to {@link size}; pass one or the
+     * other. If both are passed the provider decides which to honor and typically
+     * surfaces a warning (see {@link MotifImageResult.warnings}).
+     */
     aspectRatio?: `${number}:${number}`;
-    /** Explicit pixel size, e.g. `"1024x1024"`. */
+    /**
+     * Explicit pixel size, e.g. `"1024x1024"`. An alternative to
+     * {@link aspectRatio}; pass one or the other. If both are passed the provider
+     * decides which to honor and typically surfaces a warning (see
+     * {@link MotifImageResult.warnings}).
+     */
     size?: `${number}x${number}`;
     /** Number of images to generate. */
     n?: number;
+    /** Seed for reproducible generation, where the provider supports it. */
+    seed?: number;
+    /** Abort signal to cancel the in-flight request. */
+    signal?: AbortSignal;
     /**
      * Provider-specific options, passed straight through to the underlying model
      * as body parameters. Outer key = provider name, inner key = option name.
+     * Values must be JSON-representable; a non-JSON value (undefined, function,
+     * bigint, symbol) makes the call fail with a `MotifError`.
      */
     providerOptions?: Record<string, Record<string, unknown>>;
 }
 /** Options for a multi-image edit (images in → image out), with an optional mask. */
 interface EditImageOptions {
-    /** Input images. Each is raw bytes, a base64 string, or a data URL. */
+    /**
+     * Input images. Each entry is raw bytes (`Uint8Array`) or a string. A string
+     * may be base64, a `data:` URL, OR a remote `http(s)://` URL. Remote URLs are
+     * FETCHED by the provider — and on some providers (e.g. OpenAI) that fetch
+     * happens from the local process running this SDK. Callers that accept
+     * untrusted URLs should fetch and validate the bytes themselves before
+     * passing them here (SSRF / local-network exposure otherwise).
+     */
     images: (Uint8Array | string)[];
     /** Natural-language edit instruction. */
     instruction: string;
-    /** Optional mask (bytes, base64, or data URL) constraining the edited region. */
+    /**
+     * Optional mask constraining the edited region. Same accepted forms as
+     * {@link EditImageOptions.images} (bytes, base64, `data:` URL, or a remote
+     * `http(s)://` URL that the provider fetches — see the images note on
+     * untrusted URLs). When multiple images are passed, the mask applies to
+     * `images[0]`.
+     */
     mask?: Uint8Array | string;
     /** Quality/latency tier. Ignored when `model` is set. */
     tier?: ImageTier;
@@ -86,6 +134,10 @@ interface EditImageOptions {
     provider?: ImageProviderId;
     /** Number of images to generate. */
     n?: number;
+    /** Seed for reproducible generation, where the provider supports it. */
+    seed?: number;
+    /** Abort signal to cancel the in-flight request. */
+    signal?: AbortSignal;
     /** Provider-specific options (see {@link GenerateImageOptions.providerOptions}). */
     providerOptions?: Record<string, Record<string, unknown>>;
 }
@@ -107,6 +159,12 @@ interface MotifImageResult {
     model: string;
     /** Provider correlation id, where the provider surfaces one. */
     requestId?: string;
+    /**
+     * Degraded-success warnings from the provider (a requested setting was
+     * ignored or adjusted — e.g. passing both `size` and `aspectRatio`). Each is a
+     * readable string. Omitted entirely when the provider returned none.
+     */
+    warnings?: readonly string[];
 }
 /** The provider-agnostic image client. Every method returns a Result — no throws. */
 interface MotifImageClient {
@@ -116,6 +174,78 @@ interface MotifImageClient {
     edit: (opts: EditImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
 }
 
+/**
+ * Internal dependency-injection seam for the image layer.
+ *
+ * These types are INTERNAL: they are consumed by `createMotifImage`'s `deps`
+ * parameter and by the offline tests, but they are deliberately NOT re-exported
+ * from the public `@howells/motif-sdk/image` subpath, so they never appear in
+ * `dist/image.d.ts`. Import them from `./deps` inside the package (and from
+ * `../src/image/deps` in tests).
+ */
+
+/** A model resolver: builds an AI SDK `ImageModel` for a (provider, model, key). */
+type ResolveImageModel = (provider: ImageProviderId, modelId: string, apiKey?: string) => ImageModel;
+/** Internal dependency-injection seam (default: real `generateImage` + adapters). */
+interface MotifImageDeps {
+    generateImage?: typeof generateImage;
+    resolveModel?: ResolveImageModel;
+}
+
+/**
+ * Provider registry for the image layer.
+ *
+ * Each provider (google, openai, replicate, fal) contributes exactly one
+ * {@link ImageProviderAdapter}. The dispatch functions in `index.ts` and the
+ * cost lookup in `cost.ts` read the registry by id, so adding a provider is a
+ * single registry entry — not new branches spread across generate/edit/cost.
+ */
+
+/**
+ * A single image provider. A thin wrapper over the provider's `@ai-sdk/*` image
+ * model, plus the metadata the layer needs to route by tier, resolve keys, and
+ * meter spend.
+ */
+interface ImageProviderAdapter {
+    /** Provider id, matching the key it is registered under in {@link PROVIDERS}. */
+    readonly id: ImageProviderId;
+    /** Tier → model id map, used when a call does not pass an explicit `model`. */
+    readonly tierModels: Readonly<Record<ImageTier, string>>;
+    /** Env var read for the API key when no key is supplied in config. */
+    readonly apiKeyEnv: string;
+    /**
+     * Build the AI SDK `ImageModel` for a model id. Prefers the passed `apiKey`,
+     * else the adapter's `apiKeyEnv`. Throws `MotifError` when neither is present
+     * (callers translate this into a `Result.err`). Building a model performs no
+     * network I/O.
+     */
+    readonly resolveModel: (modelId: string, apiKey?: string) => ImageModel;
+    /**
+     * Static per-model USD/**image** table (best-effort; cited per adapter). This
+     * is multiplied by the returned image count to form the call total.
+     *
+     * Cost contract: if an adapter instead surfaces a cost on
+     * `result.providerMetadata` (the preferred source; see
+     * {@link costFromProviderMetadata}), that value MUST already be the **call
+     * total** across all `n` images — NOT a per-image figure. `priceUsdByModel`
+     * is per-image; `providerMetadata.cost` is the whole call. These two paths
+     * intentionally differ, so an adapter must not populate a per-image number
+     * into `providerMetadata.cost`.
+     */
+    readonly priceUsdByModel: Readonly<Record<string, number>>;
+}
+/**
+ * The provider registry. Every id in {@link ImageProviderId}'s closed part maps
+ * to its adapter; the open union tail means a lookup can still miss, so access
+ * goes through {@link getProviderAdapter}.
+ */
+declare const PROVIDERS: Record<ImageProviderId, ImageProviderAdapter>;
+/**
+ * Look up an adapter by provider id, throwing a `MotifError` for an unknown
+ * provider (callers catch this into a `Result.err`).
+ */
+declare function getProviderAdapter(provider: ImageProviderId): ImageProviderAdapter;
+
 /**
  * Google (Gemini) provider adapter.
  *
@@ -137,14 +267,70 @@ declare const GOOGLE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the Google API key when `apiKey` is not supplied in config. */
 declare const GOOGLE_API_KEY_ENV = "GOOGLE_GENERATIVE_AI_API_KEY";
 
+/**
+ * OpenAI (gpt-image) provider adapter.
+ *
+ * Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/openai`. Building a model
+ * performs no network I/O — the request only happens when `generateImage`
+ * invokes `model.doGenerate`.
+ */
+
+/** Tier → OpenAI image model id (all tiers → the single gpt-image model). */
+declare const OPENAI_TIER_MODELS: Readonly<Record<ImageTier, string>>;
+/** Env var read for the OpenAI API key when `apiKey` is not supplied in config. */
+declare const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+
+/**
+ * Replicate provider adapter.
+ *
+ * Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/replicate`. Building a model
+ * performs no network I/O — the request only happens when `generateImage`
+ * invokes `model.doGenerate`.
+ *
+ * NOTE: Replicate's SDK names the credential option `apiToken` (not `apiKey`),
+ * and reads `REPLICATE_API_TOKEN` from the environment.
+ */
+
+/** Tier → Replicate model id (all tiers → FLUX 1.1 Pro Ultra for now). */
+declare const REPLICATE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
+/** Env var read for the Replicate API token when `apiToken` is not in config. */
+declare const REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
+
+/**
+ * fal provider adapter.
+ *
+ * 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)
+ * is a separate, later fold (design doc §8, phase 1d).
+ *
+ * ENDPOINT QUIRK (Phase 0): fal's gpt-image endpoint wants `image_size` as a
+ * STRING enum (e.g. "1024x1024"), passed at generate time via
+ * `providerOptions.fal.image_size` — NOT the AI SDK's generic `size` object.
+ * This adapter does NOT auto-inject it; callers pass `providerOptions` when they
+ * need a specific size. Example:
+ *   img.generate({
+ *     provider: "fal",
+ *     tier: "balanced",
+ *     prompt: "...",
+ *     providerOptions: { fal: { image_size: "1024x1024" } },
+ *   });
+ */
+
+/** Tier → fal model id. */
+declare const FAL_TIER_MODELS: Readonly<Record<ImageTier, string>>;
+/** Env var read for the fal key when `apiKey` is not supplied in config. */
+declare const FAL_API_KEY_ENV = "FAL_KEY";
+
 /**
  * Per-call cost tracking for the image layer.
  *
  * Preference order:
  *   1. A cost surfaced by the provider on `result.providerMetadata` (most image
  *      providers do NOT surface one today, so this is usually absent).
- *   2. A static per-model table seeded from Google's published Gemini image
- *      pricing (see sources below).
+ *   2. A static per-model table, owned per-adapter (`priceUsdByModel`) and read
+ *      from the provider registry (see sources in each adapter).
  *   3. Unknown → `{ usd: 0, source: "unknown" }`.
  */
 
@@ -178,13 +364,6 @@ declare function costForImages(provider: ImageProviderId, modelId: string, provi
  * ```
  */
 
-/** A model resolver: builds an AI SDK `ImageModel` for a (provider, model, key). */
-type ResolveImageModel = (provider: ImageProviderId, modelId: string, apiKey?: string) => ImageModel;
-/** Internal dependency-injection seam (default: real `generateImage` + adapters). */
-interface MotifImageDeps {
-    generateImage?: typeof generateImage;
-    resolveModel?: ResolveImageModel;
-}
 /**
  * Create a provider-agnostic image client.
  *
@@ -194,4 +373,4 @@ interface MotifImageDeps {
  */
 declare function createMotifImage(config?: MotifImageConfig, deps?: MotifImageDeps): MotifImageClient;
 
-export { type EditImageOptions, GOOGLE_API_KEY_ENV, GOOGLE_TIER_MODELS, type GenerateImageOptions, type ImageCost, type ImageCostSource, type ImageProviderId, type ImageTier, type MotifImageClient, type MotifImageConfig, type MotifImageDeps, type MotifImageFile, type MotifImageResult, type ResolveImageModel, costForImages, costFromProviderMetadata, createMotifImage };
+export { type EditImageOptions, FAL_API_KEY_ENV, FAL_TIER_MODELS, GOOGLE_API_KEY_ENV, GOOGLE_TIER_MODELS, type GenerateImageOptions, type ImageCost, type ImageCostSource, type ImageProviderAdapter, type ImageProviderId, type ImageTier, type MotifImageClient, type MotifImageConfig, type MotifImageFile, type MotifImageResult, OPENAI_API_KEY_ENV, OPENAI_TIER_MODELS, PROVIDERS, REPLICATE_API_KEY_ENV, REPLICATE_TIER_MODELS, costForImages, costFromProviderMetadata, createMotifImage, getProviderAdapter };

package/dist/image.js

@@ -1279,12 +1279,149 @@ var MotifError = class extends Error {
   }
 };
 
-// src/image/cost.ts
+// src/image/fal.ts
+import { createFal } from "@ai-sdk/fal";
+var FAL_FLUX_MODEL = "fal-ai/flux-pro/v1.1-ultra";
+var FAL_GPT_IMAGE_MODEL = "fal-ai/gpt-image-1.5";
+var FAL_TIER_MODELS = {
+  fast: FAL_FLUX_MODEL,
+  balanced: FAL_GPT_IMAGE_MODEL,
+  quality: FAL_GPT_IMAGE_MODEL,
+  hero: FAL_GPT_IMAGE_MODEL
+};
+var FAL_API_KEY_ENV = "FAL_KEY";
+var FAL_IMAGE_PRICE_USD = {
+  [FAL_FLUX_MODEL]: MODELS.flux?.pricePerImageUsd ?? 0.06,
+  [FAL_GPT_IMAGE_MODEL]: MODELS.gpt?.pricePerImageUsd ?? 0.133
+};
+function resolveModel(modelId, apiKey) {
+  const key = apiKey ?? process.env[FAL_API_KEY_ENV];
+  if (key === void 0 || key === "") {
+    throw new MotifError(
+      `fal image generation requires an API key (config.fal.apiKey or ${FAL_API_KEY_ENV})`,
+      0
+    );
+  }
+  return createFal({ apiKey: key }).image(modelId);
+}
+var falAdapter = {
+  id: "fal",
+  tierModels: FAL_TIER_MODELS,
+  apiKeyEnv: FAL_API_KEY_ENV,
+  resolveModel,
+  priceUsdByModel: FAL_IMAGE_PRICE_USD
+};
+
+// src/image/google.ts
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+var GOOGLE_TIER_MODELS = {
+  fast: "gemini-2.5-flash-image",
+  balanced: "gemini-3.1-flash-image-preview",
+  quality: "gemini-3-pro-image-preview",
+  hero: "gemini-3-pro-image-preview"
+};
+var GOOGLE_API_KEY_ENV = "GOOGLE_GENERATIVE_AI_API_KEY";
 var GOOGLE_IMAGE_PRICE_USD = {
   "gemini-2.5-flash-image": 0.039,
   "gemini-3.1-flash-image-preview": 0.039,
   "gemini-3-pro-image-preview": 0.134
 };
+function resolveModel2(modelId, apiKey) {
+  const key = apiKey ?? process.env[GOOGLE_API_KEY_ENV];
+  if (key === void 0 || key === "") {
+    throw new MotifError(
+      `Google image generation requires an API key (config.google.apiKey or ${GOOGLE_API_KEY_ENV})`,
+      0
+    );
+  }
+  return createGoogleGenerativeAI({ apiKey: key }).image(modelId);
+}
+var googleAdapter = {
+  id: "google",
+  tierModels: GOOGLE_TIER_MODELS,
+  apiKeyEnv: GOOGLE_API_KEY_ENV,
+  resolveModel: resolveModel2,
+  priceUsdByModel: GOOGLE_IMAGE_PRICE_USD
+};
+
+// src/image/openai.ts
+import { createOpenAI } from "@ai-sdk/openai";
+var OPENAI_MODEL = "gpt-image-1";
+var OPENAI_TIER_MODELS = {
+  fast: OPENAI_MODEL,
+  balanced: OPENAI_MODEL,
+  quality: OPENAI_MODEL,
+  hero: OPENAI_MODEL
+};
+var OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
+var OPENAI_IMAGE_PRICE_USD = {
+  "gpt-image-1": 0.042
+};
+function resolveModel3(modelId, apiKey) {
+  const key = apiKey ?? process.env[OPENAI_API_KEY_ENV];
+  if (key === void 0 || key === "") {
+    throw new MotifError(
+      `OpenAI image generation requires an API key (config.openai.apiKey or ${OPENAI_API_KEY_ENV})`,
+      0
+    );
+  }
+  return createOpenAI({ apiKey: key }).image(modelId);
+}
+var openaiAdapter = {
+  id: "openai",
+  tierModels: OPENAI_TIER_MODELS,
+  apiKeyEnv: OPENAI_API_KEY_ENV,
+  resolveModel: resolveModel3,
+  priceUsdByModel: OPENAI_IMAGE_PRICE_USD
+};
+
+// src/image/replicate.ts
+import { createReplicate } from "@ai-sdk/replicate";
+var REPLICATE_MODEL = "black-forest-labs/flux-1.1-pro-ultra";
+var REPLICATE_TIER_MODELS = {
+  fast: REPLICATE_MODEL,
+  balanced: REPLICATE_MODEL,
+  quality: REPLICATE_MODEL,
+  hero: REPLICATE_MODEL
+};
+var REPLICATE_API_KEY_ENV = "REPLICATE_API_TOKEN";
+var REPLICATE_IMAGE_PRICE_USD = {
+  "black-forest-labs/flux-1.1-pro-ultra": 0.06
+};
+function resolveModel4(modelId, apiKey) {
+  const token = apiKey ?? process.env[REPLICATE_API_KEY_ENV];
+  if (token === void 0 || token === "") {
+    throw new MotifError(
+      `Replicate image generation requires an API token (config.replicate.apiToken or ${REPLICATE_API_KEY_ENV})`,
+      0
+    );
+  }
+  return createReplicate({ apiToken: token }).image(modelId);
+}
+var replicateAdapter = {
+  id: "replicate",
+  tierModels: REPLICATE_TIER_MODELS,
+  apiKeyEnv: REPLICATE_API_KEY_ENV,
+  resolveModel: resolveModel4,
+  priceUsdByModel: REPLICATE_IMAGE_PRICE_USD
+};
+
+// src/image/provider.ts
+var PROVIDERS = {
+  google: googleAdapter,
+  openai: openaiAdapter,
+  replicate: replicateAdapter,
+  fal: falAdapter
+};
+function getProviderAdapter(provider) {
+  const adapter = PROVIDERS[provider];
+  if (adapter === void 0) {
+    throw new MotifError(`Unsupported image provider: ${provider}`, 0);
+  }
+  return adapter;
+}
+
+// src/image/cost.ts
 function isRecord2(value) {
   return typeof value === "object" && value !== null;
 }
@@ -1303,10 +1440,11 @@ function costFromProviderMetadata(providerMetadata) {
   return void 0;
 }
 function tablePricePerImage(provider, modelId) {
-  if (provider === "google") {
-    return GOOGLE_IMAGE_PRICE_USD[modelId];
+  const adapter = PROVIDERS[provider];
+  if (adapter === void 0) {
+    return void 0;
   }
-  return void 0;
+  return adapter.priceUsdByModel[modelId];
 }
 function roundUsd(value) {
   return Number(value.toFixed(6));
@@ -1326,29 +1464,6 @@ function costForImages(provider, modelId, providerMetadata, imageCount) {
   return { usd: 0, source: "unknown" };
 }
 
-// src/image/google.ts
-import { createGoogleGenerativeAI } from "@ai-sdk/google";
-var GOOGLE_TIER_MODELS = {
-  fast: "gemini-2.5-flash-image",
-  balanced: "gemini-3.1-flash-image-preview",
-  quality: "gemini-3-pro-image-preview",
-  hero: "gemini-3-pro-image-preview"
-};
-var GOOGLE_API_KEY_ENV = "GOOGLE_GENERATIVE_AI_API_KEY";
-function googleModelForTier(tier) {
-  return GOOGLE_TIER_MODELS[tier];
-}
-function resolveModel(modelId, apiKey) {
-  const key = apiKey ?? process.env[GOOGLE_API_KEY_ENV];
-  if (key === void 0 || key === "") {
-    throw new MotifError(
-      `Google image generation requires an API key (config.google.apiKey or ${GOOGLE_API_KEY_ENV})`,
-      0
-    );
-  }
-  return createGoogleGenerativeAI({ apiKey: key }).image(modelId);
-}
-
 // src/image/index.ts
 var DEFAULT_TIER = "balanced";
 var DEFAULT_PROVIDER = "google";
@@ -1359,10 +1474,23 @@ function createMotifImage(config = {}, deps = {}) {
     return provider ?? config.defaultProvider ?? DEFAULT_PROVIDER;
   }
   function apiKeyFor(provider) {
-    if (provider === "google") {
-      return config.google?.apiKey;
+    switch (provider) {
+      case "google": {
+        return config.google?.apiKey;
+      }
+      case "openai": {
+        return config.openai?.apiKey;
+      }
+      case "replicate": {
+        return config.replicate?.apiToken;
+      }
+      case "fal": {
+        return config.fal?.apiKey;
+      }
+      default: {
+        return void 0;
+      }
     }
-    return void 0;
   }
   async function generate(opts) {
     const provider = resolveProvider(opts.provider);
@@ -1375,6 +1503,8 @@ function createMotifImage(config = {}, deps = {}) {
         ...opts.n === void 0 ? {} : { n: opts.n },
         ...opts.size === void 0 ? {} : { size: opts.size },
         ...opts.aspectRatio === void 0 ? {} : { aspectRatio: opts.aspectRatio },
+        ...opts.seed === void 0 ? {} : { seed: opts.seed },
+        ...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
         ...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
       });
       return ok2(toMotifImageResult(result, provider, modelId));
@@ -1395,6 +1525,8 @@ function createMotifImage(config = {}, deps = {}) {
           ...opts.mask === void 0 ? {} : { mask: opts.mask }
         },
         ...opts.n === void 0 ? {} : { n: opts.n },
+        ...opts.seed === void 0 ? {} : { seed: opts.seed },
+        ...opts.signal === void 0 ? {} : { abortSignal: opts.signal },
         ...opts.providerOptions === void 0 ? {} : { providerOptions: toProviderOptions(opts.providerOptions) }
       });
       return ok2(toMotifImageResult(result, provider, modelId));
@@ -1405,20 +1537,14 @@ function createMotifImage(config = {}, deps = {}) {
   return { generate, edit };
 }
 function defaultResolveModel(provider, modelId, apiKey) {
-  if (provider === "google") {
-    return resolveModel(modelId, apiKey);
-  }
-  throw new MotifError(`Unsupported image provider: ${provider}`, 0);
+  return getProviderAdapter(provider).resolveModel(modelId, apiKey);
 }
 function resolveModelId(provider, model, tier) {
   if (model !== void 0 && model !== "") {
     return model;
   }
   const resolvedTier = tier ?? DEFAULT_TIER;
-  if (provider === "google") {
-    return googleModelForTier(resolvedTier);
-  }
-  throw new MotifError(`Unsupported image provider: ${provider}`, 0);
+  return getProviderAdapter(provider).tierModels[resolvedTier];
 }
 function toMotifImageResult(result, provider, model) {
   const images = result.images.map((file) => ({
@@ -1433,14 +1559,26 @@ function toMotifImageResult(result, provider, model) {
     images.length
   );
   const requestId = extractRequestId(result);
+  const warnings = result.warnings.map(renderWarning);
   return {
     images,
     cost,
     provider,
     model,
-    ...requestId === void 0 ? {} : { requestId }
+    ...requestId === void 0 ? {} : { requestId },
+    ...warnings.length === 0 ? {} : { warnings }
   };
 }
+function renderWarning(warning) {
+  if (warning.type === "unsupported" || warning.type === "compatibility") {
+    const label = warning.type === "unsupported" ? "unsupported feature" : "compatibility mode for feature";
+    return warning.details === void 0 ? `${label} "${warning.feature}"` : `${label} "${warning.feature}": ${warning.details}`;
+  }
+  if (warning.type === "deprecated") {
+    return `deprecated setting "${warning.setting}": ${warning.message}`;
+  }
+  return warning.message;
+}
 function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
@@ -1479,13 +1617,13 @@ function toProviderOptions(input) {
   for (const [namespace, options] of Object.entries(input)) {
     const inner = {};
     for (const [key, value] of Object.entries(options)) {
-      inner[key] = toJsonValue(value);
+      inner[key] = toJsonValue(value, `providerOptions.${namespace}.${key}`);
     }
     out[namespace] = inner;
   }
   return out;
 }
-function toJsonValue(value) {
+function toJsonValue(value, path) {
   if (value === null) {
     return null;
   }
@@ -1495,18 +1633,21 @@ function toJsonValue(value) {
   if (typeof value === "object") {
     if (Array.isArray(value)) {
       const arr = [];
-      for (const item of value) {
-        arr.push(toJsonValue(item));
+      for (const [index, item] of value.entries()) {
+        arr.push(toJsonValue(item, `${path}[${index}]`));
       }
       return arr;
     }
     const obj = {};
     for (const [key, entry] of Object.entries(value)) {
-      obj[key] = toJsonValue(entry);
+      obj[key] = toJsonValue(entry, `${path}.${key}`);
     }
     return obj;
   }
-  return null;
+  throw new MotifError(
+    `providerOptions value at ${path} is not JSON-representable (type: ${typeof value})`,
+    0
+  );
 }
 function toMotifError(error) {
   if (error instanceof MotifError) {
@@ -1517,9 +1658,17 @@ function toMotifError(error) {
   return new MotifError(message, 0, code);
 }
 export {
+  FAL_API_KEY_ENV,
+  FAL_TIER_MODELS,
   GOOGLE_API_KEY_ENV,
   GOOGLE_TIER_MODELS,
+  OPENAI_API_KEY_ENV,
+  OPENAI_TIER_MODELS,
+  PROVIDERS,
+  REPLICATE_API_KEY_ENV,
+  REPLICATE_TIER_MODELS,
   costForImages,
   costFromProviderMetadata,
-  createMotifImage
+  createMotifImage,
+  getProviderAdapter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "keywords": [
     "fal",
@@ -42,7 +42,10 @@
     "access": "public"
   },
   "dependencies": {
+    "@ai-sdk/fal": "^3.0.8",
     "@ai-sdk/google": "^4.0.12",
+    "@ai-sdk/openai": "^4.0.11",
+    "@ai-sdk/replicate": "^3.0.8",
     "@howells/envy": "^0.3.7",
     "ai": "^7.0.22",
     "neverthrow": "^8.2.0",
@@ -58,8 +61,8 @@
     "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup",
+    "dev": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsup --watch",
     "lint": "howells-check .",
     "lint:fix": "howells-fix .",
     "typecheck": "tsc --noEmit",