@howells/motif-sdk 0.6.0 → 0.8.0

package/dist/image.d.ts

@@ -0,0 +1,316 @@
+import { ImageModel, generateImage } from 'ai';
+import { Result } from 'neverthrow';
+
+declare class MotifError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    /** fal's request-correlation id (from the `x-fal-request-id` header or the
+     * error body). Ties a failure back to fal's dashboard/support. */
+    readonly requestId?: string;
+    constructor(message: string, status: number, code?: string, requestId?: string);
+}
+
+/**
+ * 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`
+ * surface and reuses the SDK's Result convention (`Result<T, MotifError>` — no
+ * thrown exceptions). See docs/design/provider-agnostic-image-layer.md.
+ */
+
+/**
+ * Quality/latency tier. Resolves through a provider-aware tier→model map when no
+ * explicit `model` id is given. `balanced` is the default when a tier is omitted.
+ */
+type ImageTier = "fast" | "balanced" | "quality" | "hero";
+/**
+ * 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" | "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. */
+interface ImageCost {
+    /** Total USD for the call (all images), best-effort. */
+    usd: number;
+    /** Where the figure came from: the provider's metadata, the static table, or unknown. */
+    source: ImageCostSource;
+}
+/**
+ * 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;
+    /** Google provider overrides. `apiKey` falls back to `GOOGLE_GENERATIVE_AI_API_KEY`. */
+    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 {
+    /** The text prompt. */
+    prompt: string;
+    /** Quality/latency tier. Ignored when `model` is set. */
+    tier?: ImageTier;
+    /** Explicit provider model id. Overrides `tier`. */
+    model?: string;
+    /** Provider override for this call. */
+    provider?: ImageProviderId;
+    /** Aspect ratio, e.g. `"1:1"`. */
+    aspectRatio?: `${number}:${number}`;
+    /** Explicit pixel size, e.g. `"1024x1024"`. */
+    size?: `${number}x${number}`;
+    /** Number of images to generate. */
+    n?: number;
+    /**
+     * Provider-specific options, passed straight through to the underlying model
+     * as body parameters. Outer key = provider name, inner key = option name.
+     */
+    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. */
+    images: (Uint8Array | string)[];
+    /** Natural-language edit instruction. */
+    instruction: string;
+    /** Optional mask (bytes, base64, or data URL) constraining the edited region. */
+    mask?: Uint8Array | string;
+    /** Quality/latency tier. Ignored when `model` is set. */
+    tier?: ImageTier;
+    /** Explicit provider model id. Overrides `tier`. */
+    model?: string;
+    /** Provider override for this call. */
+    provider?: ImageProviderId;
+    /** Number of images to generate. */
+    n?: number;
+    /** Provider-specific options (see {@link GenerateImageOptions.providerOptions}). */
+    providerOptions?: Record<string, Record<string, unknown>>;
+}
+/** A single generated image, mirroring the AI SDK's `GeneratedFile`. */
+interface MotifImageFile {
+    uint8Array: Uint8Array;
+    base64: string;
+    mediaType: string;
+}
+/** Normalized result of a generate/edit call. */
+interface MotifImageResult {
+    /** Generated images. */
+    images: MotifImageFile[];
+    /** Normalized per-call cost + provenance. */
+    cost: ImageCost;
+    /** Resolved provider. */
+    provider: ImageProviderId;
+    /** Resolved model id. */
+    model: string;
+    /** Provider correlation id, where the provider surfaces one. */
+    requestId?: string;
+}
+/** The provider-agnostic image client. Every method returns a Result — no throws. */
+interface MotifImageClient {
+    /** Text→image generation. */
+    generate: (opts: GenerateImageOptions) => Promise<Result<MotifImageResult, MotifError>>;
+    /** Multi-image edit (with optional mask). */
+    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.
+ *
+ * Builds a Vercel AI SDK `ImageModel` from `@ai-sdk/google`. Building a model
+ * performs no network I/O — the request only happens when `generateImage`
+ * invokes `model.doGenerate`. Gemini supports both text→image generation and
+ * multi-image-in → image-out editing (with an optional mask), which is the core
+ * operation this layer normalizes.
+ */
+
+/**
+ * Tier → Gemini image model id.
+ *
+ * Seeded from Material Desk's `RENDER_IMAGE_MODEL_BY_QUALITY` (the driving
+ * consumer, see the design doc). `gemini-2.5-flash-image` is the proven-reachable
+ * floor; the preview ids may require allowlist/tier access.
+ */
+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, owned per-adapter (`priceUsdByModel`) and read
+ *      from the provider registry (see sources in each adapter).
+ *   3. Unknown → `{ usd: 0, source: "unknown" }`.
+ */
+
+/**
+ * Extract a provider-reported total cost from a `generateImage` result's
+ * `providerMetadata`, if the provider surfaces a numeric `cost`. The shape is
+ * `{ [provider]: { ...; cost?: number } }`. Returns undefined otherwise.
+ */
+declare function costFromProviderMetadata(providerMetadata: unknown): number | undefined;
+/**
+ * Normalized per-call cost for a generation. Prefers a provider-metadata cost,
+ * then the static table (× image count), then unknown.
+ */
+declare function costForImages(provider: ImageProviderId, modelId: string, providerMetadata: unknown, imageCount: number): ImageCost;
+
+/**
+ * `@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`
+ * surface; reuses the SDK's Result convention (`Result<T, MotifError>` — no
+ * thrown exceptions). Google (Gemini) is the only provider in Phase 1a.
+ *
+ * @example
+ * ```ts
+ * import { createMotifImage } from "@howells/motif-sdk/image";
+ *
+ * const img = createMotifImage({ defaultProvider: "google" });
+ * const r = await img.generate({ tier: "fast", prompt: "a bare concrete wall" });
+ * if (r.isOk()) console.log(r.value.images[0].mediaType, r.value.cost);
+ * ```
+ */
+
+/** 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.
+ *
+ * @param config - provider selection + keys (keys fall back to env).
+ * @param deps - INTERNAL testing seam. Defaults to the real AI SDK `generateImage`
+ *   and the built-in provider adapters; tests inject fakes here to run offline.
+ */
+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 };