@basementstudio/sanity-ai-image-plugin 0.0.1 → 0.1.1

package/README.md

@@ -1,257 +1,300 @@
-# `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
-```
-
+# `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,
+      frontendRateLimit: {
+        maxRequests: 3,
+        windowSecs: 60,
+      },
+      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,
+    sharedSecret: process.env.AI_IMAGE_PLUGIN_SHARED_SECRET!,
+    // Shared-secret auth and same-origin protection are 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_PLUGIN_SHARED_SECRET` is required for the app-owned route
+- `AI_IMAGE_MODEL` is optional and can still override the server default
+
+### 4. Configure the shared secret in Studio
+
+Open the AI Image Plugin settings tool and configure the same shared secret
+value there.
+
+The plugin stores that Studio-side value with `@sanity/studio-secrets`, so it
+is fetched at runtime for logged-in Studio users instead of being bundled into
+the Studio source code.
+
+## 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 fallback
+default 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 requires a valid shared secret and same-origin browser
+requests by default.
+
+That means requests are accepted only when:
+
+1. the request includes the correct `x-ai-image-plugin-secret` header
+2. the browser `Origin` matches the API route origin exactly
+
+Same-origin matches look like this:
+
+- `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. The shared secret is
+managed from the plugin settings tool and stored separately from the plugin's
+normal prompt/reference-image settings document.
+
+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.
+
+### Frontend rate limit
+
+The Studio UI applies a browser-side rolling-window limiter by default across
+both generation entrypoints in the same browser profile.
+
+Default behavior:
+
+- `3` generation attempts per `60` seconds
+- shared through `localStorage`, so refreshes and other tabs see the same block
+- configurable with `frontendRateLimit` in `sanity.config`
+- disabled entirely with `frontendRateLimit: false`
+
+Only requests that are actually sent to the plugin API route consume quota.
+Local validation failures inside Studio do not.
+
+### 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 asset-source model picker starts on:
+
+1. `settings.globalModel` when it is present and allowed
+2. otherwise the first configured `allowedModels` entry
+
+Editors can override that selection for the current request before generating.
+
+### 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.
+
+The generate dialog also includes a model picker. It starts from the same
+global default resolution as the asset source, but editors can switch to a
+different allowed model for that one generation request.
+
+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/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SUPPORTED_AI_IMAGE_MODELS } from "./utils/models";
+export { aiImagePlugin } from "./studio/plugin";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { SUPPORTED_AI_IMAGE_MODELS } from "./utils/models";
+export { aiImagePlugin } from "./studio/plugin";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/presets/article-featured-image.d.ts

@@ -0,0 +1,3 @@
+import type { GenerateButtonTarget } from "../utils/shared";
+export declare function createArticleFeaturedImageTarget(options?: Partial<Omit<GenerateButtonTarget, "type">>): GenerateButtonTarget;
+//# sourceMappingURL=article-featured-image.d.ts.map

package/dist/presets/article-featured-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"article-featured-image.d.ts","sourceRoot":"","sources":["../../src/presets/article-featured-image.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAE3D,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAM,GACxD,oBAAoB,CAkBtB"}

package/dist/presets/article-featured-image.js

@@ -0,0 +1,17 @@
+export function createArticleFeaturedImageTarget(options = {}) {
+    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"],
+    };
+}
+//# sourceMappingURL=article-featured-image.js.map

package/dist/presets/article-featured-image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"article-featured-image.js","sourceRoot":"","sources":["../../src/presets/article-featured-image.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gCAAgC,CAC9C,UAAuD,EAAE;IAEzD,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,wBAAwB;QAC1C,IAAI,EAAE,gBAAgB;QACtB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,wBAAwB;QAChD,WAAW,EACT,OAAO,CAAC,WAAW;YACnB,4GAA4G;QAC9G,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,yBAAyB;QAC7D,YAAY,EAAE,OAAO,CAAC,YAAY,IAAI,SAAS;QAC/C,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,eAAe;QAC/C,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,eAAe;QACnD,iBAAiB,EACf,OAAO,CAAC,iBAAiB;YACzB,sDAAsD;QACxD,0BAA0B,EACxB,OAAO,CAAC,0BAA0B,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC;KAC7D,CAAA;AACH,CAAC"}

package/dist/server/constants.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_MODEL: "gemini-2.5-flash-image" | "gemini-3.1-flash-image-preview" | "gpt-image-1";
+export declare const DEFAULT_PROVIDER_API_URL = "https://generativelanguage.googleapis.com/v1beta";
+export declare const DEFAULT_MAX_REFERENCE_FILE_BYTES: number;
+export declare const SUPPORTED_REFERENCE_IMAGE_TYPES: Set<string>;
+export declare const OPENAI_SUPPORTED_REFERENCE_IMAGE_TYPES: Set<string>;
+//# sourceMappingURL=constants.d.ts.map

package/dist/server/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/server/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,6EAAmC,CAAC;AAC9D,eAAO,MAAM,wBAAwB,qDACe,CAAC;AACrD,eAAO,MAAM,gCAAgC,QAAkB,CAAC;AAEhE,eAAO,MAAM,+BAA+B,aAM1C,CAAC;AAEH,eAAO,MAAM,sCAAsC,aAIjD,CAAC"}

package/{src/server/constants.ts → dist/server/constants.js}

@@ -1,20 +1,17 @@
-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",
-]);
+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",
+]);
+//# sourceMappingURL=constants.js.map