@basementstudio/sanity-ai-image-plugin 0.0.0

package/README.md

@@ -0,0 +1,257 @@
+# `sanity-ai-image-plugin`
+
+Portable Sanity Studio plugin and server helper for generating images with
+Gemini, OpenAI, and other package-supported image models and dropping the
+result straight into Sanity image fields.
+
+This package is intentionally self-contained so it can be copied into a new repo
+or published later without dragging along an app-specific schema layout.
+
+This repo is source-first while it is being developed here:
+
+- package exports point at `src/*`
+
+## What It Owns
+
+- a Studio plugin via `aiImagePlugin(...)`
+- a plugin-owned settings document and settings tool
+- a generic image asset source
+- optional generate-button targets for specific image fields
+- a server helper export for the app-owned API route
+
+## Install Shape
+
+The package exposes two entrypoints:
+
+- `sanity-ai-image-plugin`
+- `sanity-ai-image-plugin/server`
+
+## Consumer Setup
+
+### 1. Add the Studio plugin
+
+```ts
+import { defineConfig } from "sanity";
+import {
+  SUPPORTED_AI_IMAGE_MODELS,
+  createArticleFeaturedImageTarget,
+  aiImagePlugin,
+} from "sanity-ai-image-plugin";
+
+const allowedModels = [
+  SUPPORTED_AI_IMAGE_MODELS[0],
+  SUPPORTED_AI_IMAGE_MODELS[2],
+] as const;
+
+export default defineConfig({
+  // ...your existing config
+  plugins: [
+    aiImagePlugin({
+      apiVersion: "2025-02-19",
+      allowedModels: [...allowedModels],
+      assetSource: true,
+      targets: [
+        createArticleFeaturedImageTarget(),
+        {
+          id: "home-page-featured-image",
+          type: "generateButton",
+          title: "Home Page Featured Image",
+          documentType: "homePage",
+          fieldPath: "featuredImage",
+          suggestedContextFieldPaths: ["title", "description"],
+        },
+      ],
+    }),
+  ],
+});
+```
+
+### 2. Add the thin app-owned route.
+
+```ts
+import {
+  handleAiImageRequest,
+  SUPPORTED_AI_IMAGE_MODELS,
+} from "sanity-ai-image-plugin/server";
+
+const allowedModels = [
+  SUPPORTED_AI_IMAGE_MODELS[0],
+  SUPPORTED_AI_IMAGE_MODELS[2],
+] as const;
+
+export async function POST(request: Request) {
+  return handleAiImageRequest(request, {
+    allowedModels: [...allowedModels],
+    apiKey: process.env.GEMINI_API_KEY,
+    openAiApiKey: process.env.OPENAI_API_KEY,
+    // Same-origin protection is enabled by default.
+    // Optional overrides:
+    // model: process.env.AI_IMAGE_MODEL as (typeof allowedModels)[number],
+    // maxReferenceFileBytes: 8 * 1024 * 1024,
+    // maxTotalReferenceBytes: 5 * 8 * 1024 * 1024,
+  })
+}
+```
+
+### 3. Set env vars
+
+- `GEMINI_API_KEY` is required when you allow Google models
+- `OPENAI_API_KEY` is required when you allow OpenAI models
+- `AI_IMAGE_MODEL` is optional and can still override the server default
+
+## Supported Models
+
+The package has an internal supported-model registry. In this first pass it
+contains exactly:
+
+- `gemini-2.5-flash-image`
+- `gemini-3.1-flash-image-preview`
+- `gpt-image-1`
+
+Each installation can opt into any non-empty subset of those models with the
+ordered `allowedModels` config. The first allowed model becomes the default
+model for both the Studio UI and the server helper unless the settings document
+or route overrides it.
+
+## Settings Model
+
+The plugin owns one settings document:
+
+- `_id`: `aiImagePlugin.settings`
+- `_type`: `aiImagePluginSettings`
+
+It stores:
+
+- `globalModel`
+- `globalPrompt`
+- `globalReferenceImages`
+- `targetConfigs[]`
+
+Each target config can override:
+
+- `targetId`
+- `prompt`
+- `referenceImages`
+
+## Behavior
+
+### Server helper
+
+The server helper is same-origin only by default.
+
+That means requests are accepted when the browser `Origin` matches the API
+route origin exactly, for example:
+
+- `http://localhost:3000/studio` -> `http://localhost:3000/api/ai-image-plugin`
+- `https://myapp.vercel.app/studio` -> `https://myapp.vercel.app/api/ai-image-plugin`
+
+The helper does not inspect the `/studio` path directly because browser
+`Origin` headers only include the scheme, host, and port.
+
+By default it also enforces:
+
+- `8 MiB` maximum per reference image
+- a combined reference-image cap of `maxReferences * 8 MiB`
+- the requested `model` must be both package-supported and present in the
+  route's configured `allowedModels`
+
+If your framework supports route-level body limits, keep those enabled too.
+
+### Asset source
+
+The generic asset source composes:
+
+1. global prompt
+2. asset-source target prompt
+3. editor prompt
+
+Reference images are combined from:
+
+1. global reference images
+2. asset-source target reference images
+3. local editor-uploaded reference images
+
+The selected model is resolved like this:
+
+1. `settings.globalModel` when it is present and allowed
+2. otherwise the first configured `allowedModels` entry
+
+### Generate button targets
+
+Generate-button targets match against:
+
+- `documentType`
+- `fieldPath`
+
+When matched, the plugin renders a `Generate` button above the normal Sanity
+image input.
+
+Targets can also declare:
+
+- `suggestedContextFieldPaths`
+
+When the dialog opens, the plugin inspects the current document schema and shows
+eligible top-level document fields as toggle tags. In this first pass, eligible
+field types are:
+
+- `string`
+- `text`
+- `number`
+- `boolean`
+- `date`
+- `datetime`
+- `slug`
+
+Suggested context field paths are only default-on tags. They are filtered to
+fields that exist on the current document type, and editors can toggle them on
+or off for each generation.
+
+Prompt composition order is:
+
+1. global prompt
+2. target prompt
+3. optional selected document context
+4. optional editor prompt
+
+Selected document context is built as generic lines such as:
+
+- `The field called "title" has content "...".`
+
+## Optional Preset
+
+`createArticleFeaturedImageTarget(...)` is an optional preset for
+`article.featuredImage`.
+
+It feeds the model:
+
+- shared global settings
+- target-specific article settings
+- editor-selectable document-derived title + excerpt context suggestions
+- optional editor prompt
+
+If you do not use that preset, the package still works as a generic asset source
+and generic generate-button plugin.
+
+## Desk Structure
+
+The plugin does not require custom desk structure wiring. If a consuming app
+uses a custom structure and wants to hide `aiImagePluginSettings` from the normal
+document list, that is optional and app-owned.
+
+## PNG Normalization
+
+All reference images are converted to PNG before they are sent to the server
+helper. That includes:
+
+- locally uploaded reference files
+- stored settings images downloaded from Sanity
+- new images uploaded through the settings tool
+
+## Development
+
+```sh
+bun run check
+bun run build
+bun test
+```
+

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@basementstudio/sanity-ai-image-plugin",
+  "private": false,
+  "version": "0.0.0",
+  "packageManager": "bun@1.3.7",
+  "description": "Portable Sanity Studio plugin and server helper for AI image generation.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/server.ts",
+      "import": "./src/server.ts",
+      "default": "./src/server.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test tests",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish",
+    "version-canary": "changeset version --snapshot canary",
+    "release-canary": "changeset publish --tag canary --no-git-tag"
+  },
+  "keywords": [
+    "sanity",
+    "sanity-plugin",
+    "gemini",
+    "image-generation",
+    "ai-image-plugin"
+  ],
+  "peerDependencies": {
+    "@sanity/ui": "^2.0.0 || ^3.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "sanity": "^3.0.0 || ^4.0.0 || ^5.0.0"
+  },
+  "dependencies": {
+    "@ai-sdk/google": "^3",
+    "@ai-sdk/openai": "^3",
+    "ai": "^6"
+  },
+  "devDependencies": {
+    "@sanity/ui": "^3.1.14",
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.29.8",
+    "@types/bun": "^1.3.6",
+    "@types/node": "^20.19.30",
+    "@types/react": "^19.2.9",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "sanity": "^5.6.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export {
+  DEFAULT_API_ENDPOINT,
+  DEFAULT_ASSET_SOURCE_TARGET_ID,
+  MAX_REFERENCE_IMAGES,
+  SETTINGS_DOCUMENT_ID,
+  SETTINGS_SCHEMA_TYPE,
+  SETTINGS_TOOL_NAME,
+  SETTINGS_TOOL_TITLE,
+  SOURCE_NAME,
+  SOURCE_TITLE,
+  type AssetSourceTarget,
+  type GenerateButtonTarget,
+  type PluginOptions,
+  type SettingsTargetConfigValue,
+  type SettingsValue,
+  type StoredImage,
+} from "./utils/shared";
+export {
+  SUPPORTED_AI_IMAGE_MODELS,
+  type SupportedAiImageModelId,
+} from "./utils/models";
+export { createArticleFeaturedImageTarget } from "./presets/article-featured-image";
+export { aiImagePlugin } from "./studio/plugin";

package/src/presets/article-featured-image.ts

@@ -0,0 +1,23 @@
+import type { GenerateButtonTarget } from "../utils/shared"
+
+export function createArticleFeaturedImageTarget(
+  options: Partial<Omit<GenerateButtonTarget, "type">> = {}
+): GenerateButtonTarget {
+  return {
+    id: options.id || "article-featured-image",
+    type: "generateButton",
+    title: options.title || "Article Featured Image",
+    description:
+      options.description ||
+      "Adds a Generate button that combines shared art direction, article context, and an optional editor prompt.",
+    dialogTitle: options.dialogTitle || "Generate Featured Image",
+    documentType: options.documentType || "article",
+    fieldPath: options.fieldPath || "featuredImage",
+    promptLabel: options.promptLabel || "Custom prompt",
+    promptPlaceholder:
+      options.promptPlaceholder ||
+      "Optional custom instructions for this article image.",
+    suggestedContextFieldPaths:
+      options.suggestedContextFieldPaths || ["title", "excerpt"],
+  }
+}

package/src/server/constants.ts

@@ -0,0 +1,20 @@
+import { DEFAULT_SUPPORTED_AI_IMAGE_MODEL } from "../utils/models";
+
+export const DEFAULT_MODEL = DEFAULT_SUPPORTED_AI_IMAGE_MODEL;
+export const DEFAULT_PROVIDER_API_URL =
+  "https://generativelanguage.googleapis.com/v1beta";
+export const DEFAULT_MAX_REFERENCE_FILE_BYTES = 8 * 1024 * 1024;
+
+export const SUPPORTED_REFERENCE_IMAGE_TYPES = new Set([
+  "image/heic",
+  "image/heif",
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+]);
+
+export const OPENAI_SUPPORTED_REFERENCE_IMAGE_TYPES = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+]);

package/src/server/handle-request.ts

@@ -0,0 +1,207 @@
+import {
+  isSupportedAiImageModelId,
+  resolveAllowedAiImageModel,
+  SUPPORTED_AI_IMAGE_MODELS,
+} from "../utils/models";
+import {
+  generateImageWithModel,
+  getErrorMessage,
+  getErrorStatusCode,
+  getFormRequestPayload,
+  getMissingApiKeyErrorMessage,
+  getProviderApiKey,
+  getProviderDisplayName,
+  getReferenceImageValidationError,
+  getSameOriginValidationError,
+  isMultipartFormData,
+  jsonResponse,
+  parseHeaderByteLength,
+  resolveRequestOptions,
+} from "./utils";
+import type { RequestOptions, SuccessResponse } from "./types";
+export {
+  DEFAULT_MAX_REFERENCE_FILE_BYTES,
+  DEFAULT_MODEL,
+  DEFAULT_PROVIDER_API_URL,
+  SUPPORTED_REFERENCE_IMAGE_TYPES,
+} from "./constants";
+export type { RequestOptions, SuccessResponse } from "./types";
+
+export async function handleAiImageRequest(
+  request: Request,
+  options: RequestOptions = {},
+): Promise<Response> {
+  let requestOptions: ReturnType<typeof resolveRequestOptions>;
+
+  // Normalize server config up front so the rest of the handler can assume a
+  // single, fully-resolved set of limits and model choices.
+  try {
+    requestOptions = resolveRequestOptions(options);
+  } catch (error) {
+    return jsonResponse(
+      {
+        error:
+          getErrorMessage(error) ||
+          "AI Image Plugin server configuration is invalid.",
+      },
+      500,
+    );
+  }
+
+  // Reject browser requests that do not come from the same Sanity Studio
+  // origin when same-origin enforcement is enabled.
+  if (requestOptions.enforceSameOrigin) {
+    const sameOriginError = getSameOriginValidationError(request);
+
+    if (sameOriginError) {
+      return jsonResponse(
+        {
+          error: sameOriginError.error,
+        },
+        sameOriginError.status,
+      );
+    }
+  }
+
+  // The endpoint only accepts multipart form submissions because prompt/model
+  // metadata and uploaded reference images arrive together.
+  if (!isMultipartFormData(request.headers.get("content-type"))) {
+    return jsonResponse(
+      {
+        error: "AI Image Plugin requires a multipart/form-data request.",
+      },
+      415,
+    );
+  }
+
+  // Fail early on obviously oversized requests before parsing the body.
+  const contentLength = parseHeaderByteLength(
+    request.headers.get("content-length"),
+  );
+
+  if (
+    contentLength !== null &&
+    contentLength > requestOptions.maxTotalReferenceBytes
+  ) {
+    return jsonResponse(
+      {
+        error: `AI Image Plugin requests cannot exceed ${requestOptions.maxTotalReferenceBytes} bytes.`,
+      },
+      413,
+    );
+  }
+
+  let formData: FormData;
+
+  // Parse the multipart payload into the prompt, optional model override, and
+  // the capped list of uploaded reference images.
+  try {
+    formData = await request.formData();
+  } catch {
+    return jsonResponse(
+      {
+        error: "AI Image Plugin could not read the upload payload.",
+      },
+      400,
+    );
+  }
+
+  const { prompt, referenceImages, requestedModel } = getFormRequestPayload(
+    formData,
+    requestOptions.maxReferences,
+  );
+
+  if (!prompt) {
+    return jsonResponse({ error: "Prompt is required." }, 400);
+  }
+
+  // Resolve the effective model, then make sure it is both supported by the
+  // plugin and allowed by this installation's server config.
+  const modelId = requestedModel || requestOptions.defaultModel;
+
+  if (!isSupportedAiImageModelId(modelId)) {
+    return jsonResponse(
+      {
+        error: `AI Image Plugin does not support the model "${modelId}". Supported models are: ${SUPPORTED_AI_IMAGE_MODELS.join(", ")}.`,
+      },
+      400,
+    );
+  }
+
+  if (!requestOptions.allowedModels.includes(modelId)) {
+    return jsonResponse(
+      {
+        error: `AI Image Plugin does not allow the model "${modelId}" for this installation.`,
+      },
+      400,
+    );
+  }
+
+  const selectedModel = resolveAllowedAiImageModel(
+    modelId,
+    requestOptions.allowedModels,
+  );
+  const referenceImageError = getReferenceImageValidationError({
+    maxReferenceFileBytes: requestOptions.maxReferenceFileBytes,
+    maxTotalReferenceBytes: requestOptions.maxTotalReferenceBytes,
+    model: selectedModel,
+    referenceImages,
+  });
+
+  if (referenceImageError) {
+    return jsonResponse(
+      {
+        error: referenceImageError.error,
+      },
+      referenceImageError.status,
+    );
+  }
+
+  // Pick the provider credentials that match the selected model family.
+  const apiKey = getProviderApiKey(selectedModel, options);
+
+  if (!apiKey) {
+    return jsonResponse(
+      {
+        error: getMissingApiKeyErrorMessage(selectedModel),
+      },
+      500,
+    );
+  }
+
+  // Delegate the actual image generation call and translate provider failures
+  // into a stable API response shape for the Studio client.
+  try {
+    const generatedImage = await generateImageWithModel({
+      apiKey,
+      model: selectedModel,
+      prompt,
+      referenceImages,
+      ...(options.geminiApiUrl ? { geminiApiUrl: options.geminiApiUrl } : {}),
+    });
+
+    if (!generatedImage) {
+      return jsonResponse(
+        {
+          error:
+            "AI Image Plugin returned a response, but no generated image was found.",
+        },
+        502,
+      );
+    }
+
+    return jsonResponse({
+      ...generatedImage,
+      model: selectedModel,
+    } satisfies SuccessResponse);
+  } catch (error) {
+    return jsonResponse(
+      {
+        error:
+          getErrorMessage(error) ||
+          `AI Image Plugin could not reach ${getProviderDisplayName(selectedModel)}.`,
+      },
+      getErrorStatusCode(error) || 502,
+    );
+  }
+}

package/src/server/types.ts

@@ -0,0 +1,30 @@
+import type { SupportedAiImageModelId } from "../utils/models";
+
+export type GenerateImageFunction = (options: Record<string, unknown>) => Promise<{
+  image?: unknown;
+}>;
+
+export type GeneratedImagePayload = {
+  base64?: string;
+  mediaType?: string;
+  uint8Array?: Uint8Array;
+};
+
+export type SuccessResponse = {
+  data: string;
+  mimeType: string;
+  model: string;
+};
+
+export type RequestOptions = {
+  allowedModels?: SupportedAiImageModelId[];
+  apiKey?: string;
+  enforceSameOrigin?: boolean;
+  geminiApiUrl?: string;
+  googleApiKey?: string;
+  maxReferenceFileBytes?: number;
+  maxReferences?: number;
+  maxTotalReferenceBytes?: number;
+  model?: SupportedAiImageModelId;
+  openAiApiKey?: string;
+};