@howells/motif-sdk 0.7.0 → 0.8.0

package/dist/image.d.ts

@@ -1,4 +1,4 @@
-import { generateImage, ImageModel } from 'ai';
+import { ImageModel, generateImage } from 'ai';
 import { Result } from 'neverthrow';
 
 declare class MotifError extends Error {
@@ -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 {
@@ -116,6 +136,49 @@ interface MotifImageClient {
     edit: (opts: EditImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
 }
 
+/**
+ * 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). */
+    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 +200,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" }`.
  */
 
@@ -194,4 +313,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 MotifImageDeps, type MotifImageFile, type MotifImageResult, OPENAI_API_KEY_ENV, OPENAI_TIER_MODELS, PROVIDERS, REPLICATE_API_KEY_ENV, REPLICATE_TIER_MODELS, type ResolveImageModel, 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);
@@ -1405,20 +1533,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) => ({
@@ -1517,9 +1639,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.8.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",