@howells/motif-sdk 0.8.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

@@ -1,4 +1,4 @@
-import { ImageModel, generateImage } from 'ai';
+import { generateImage, ImageModel } from 'ai';
 import { Result } from 'neverthrow';
 
 declare class MotifError extends Error {
@@ -78,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;
@@ -106,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>>;
 }
@@ -127,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 {
@@ -136,6 +174,24 @@ 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.
  *
@@ -164,7 +220,18 @@ interface ImageProviderAdapter {
      * network I/O.
      */
     readonly resolveModel: (modelId: string, apiKey?: string) => ImageModel;
-    /** Static per-model USD/image table (best-effort; cited per adapter). */
+    /**
+     * 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>>;
 }
 /**
@@ -297,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.
  *
@@ -313,4 +373,4 @@ interface MotifImageDeps {
  */
 declare function createMotifImage(config?: MotifImageConfig, deps?: MotifImageDeps): MotifImageClient;
 
-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 };
+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

@@ -1503,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));
@@ -1523,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));
@@ -1555,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;
 }
@@ -1601,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;
   }
@@ -1617,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "keywords": [
     "fal",
@@ -61,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",