@howells/motif-sdk 0.5.1 → 0.7.0

package/dist/image.d.ts

@@ -0,0 +1,197 @@
+import { generateImage, ImageModel } 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. 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.
+ */
+type ImageProviderId = "google" | (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. Provider keys fall back to environment variables. */
+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;
+    };
+}
+/** 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>>;
+}
+
+/**
+ * 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";
+
+/**
+ * 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).
+ *   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, 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 };