@basementstudio/sanity-ai-image-plugin 0.0.0

package/src/studio/settings-data.ts

@@ -0,0 +1,172 @@
+import type { ImageValue, SanityClient } from "sanity"
+import {
+  resolveAllowedAiImageModel,
+  type SupportedAiImageModelId,
+} from "../utils/models"
+import {
+  MAX_REFERENCE_IMAGES,
+  type SettingsTargetConfigValue,
+  type SettingsValue,
+  type StoredImage,
+} from "../utils/shared"
+import { convertImageFileToPng, fileExtensionFromMimeType } from "./files"
+
+export type ToolReferenceImage = {
+  assetId?: string
+  id: string
+  name: string
+  previewUrl?: string
+  sourceFile?: File
+}
+
+export function createImageReferenceValue(assetId: string): ImageValue {
+  return {
+    _type: "image",
+    asset: {
+      _type: "reference",
+      _ref: assetId,
+    },
+  }
+}
+
+export function getErrorMessage(
+  error: unknown,
+  fallback = "Unable to generate an image right now."
+): string {
+  if (error instanceof Error && error.message.trim()) {
+    return error.message
+  }
+
+  return fallback
+}
+
+export function findTargetSettings(
+  settings: SettingsValue | null,
+  targetId: string
+): SettingsTargetConfigValue | undefined {
+  return settings?.targetConfigs?.find((target) => target.targetId === targetId)
+}
+
+export function resolveSettingsModel(options: {
+  allowedModels: SupportedAiImageModelId[]
+  settings: SettingsValue | null
+}): SupportedAiImageModelId {
+  return resolveAllowedAiImageModel(
+    options.settings?.globalModel,
+    options.allowedModels
+  )
+}
+
+export async function fetchSettingsDocument(
+  client: SanityClient,
+  documentId: string,
+  schemaType: string
+): Promise<SettingsValue | null> {
+  return client.fetch<SettingsValue | null>(
+    `*[_type == $type && _id == $id][0]{
+      globalModel,
+      globalPrompt,
+      globalReferenceImages[]{
+        "asset": {
+          "_ref": asset._ref,
+          "_id": asset->_id,
+          "originalFilename": asset->originalFilename,
+          "url": asset->url
+        }
+      },
+      targetConfigs[]{
+        targetId,
+        prompt,
+        referenceImages[]{
+          "asset": {
+            "_ref": asset._ref,
+            "_id": asset->_id,
+            "originalFilename": asset->originalFilename,
+            "url": asset->url
+          }
+        }
+      }
+    }`,
+    {
+      id: documentId,
+      type: schemaType,
+    }
+  )
+}
+
+export async function downloadReferenceImageAsPng(
+  image: StoredImage,
+  index: number
+): Promise<File | null> {
+  if (!image.asset?.url) {
+    return null
+  }
+
+  const response = await fetch(image.asset.url)
+
+  if (!response.ok) {
+    throw new Error("Failed to download AI Image Plugin reference images.")
+  }
+
+  const blob = await response.blob()
+  const fallbackName = `reference-${index + 1}.${fileExtensionFromMimeType(
+    blob.type || "image/png"
+  )}`
+  const filename = image.asset.originalFilename || fallbackName
+  const file = new File([blob], filename, { type: blob.type || "image/png" })
+
+  return convertImageFileToPng(file)
+}
+
+export async function buildSettingsReferenceImages(
+  settings: SettingsValue | null,
+  targetId?: string,
+  maxReferenceImages = MAX_REFERENCE_IMAGES
+): Promise<File[]> {
+  const targetSettings = targetId ? findTargetSettings(settings, targetId) : null
+  const images = [
+    ...(settings?.globalReferenceImages || []),
+    ...(targetSettings?.referenceImages || []),
+  ].slice(0, maxReferenceImages)
+
+  return (
+    await Promise.all(images.map(downloadReferenceImageAsPng))
+  ).filter((image): image is File => image instanceof File)
+}
+
+export function createToolReferenceImageFromStoredImage(
+  image: StoredImage,
+  index: number
+): ToolReferenceImage | null {
+  const asset = image.asset
+  const assetId = asset?._ref || asset?._id
+
+  if (!assetId) {
+    return null
+  }
+
+  return {
+    id: assetId,
+    assetId,
+    name: asset?.originalFilename || `reference-${index + 1}.png`,
+    ...(asset?.url ? { previewUrl: asset.url } : {}),
+  }
+}
+
+export function createToolReferenceImageFromFile(file: File): ToolReferenceImage {
+  return {
+    id: `${file.name}-${file.size}-${file.lastModified}`,
+    name: file.name,
+    sourceFile: file,
+  }
+}
+
+export function appendReferenceImages(
+  currentImages: ToolReferenceImage[],
+  nextFiles: File[]
+): ToolReferenceImage[] {
+  return [...currentImages, ...nextFiles.map(createToolReferenceImageFromFile)].slice(
+    0,
+    MAX_REFERENCE_IMAGES
+  )
+}

package/src/utils/config.ts

@@ -0,0 +1,55 @@
+import { normalizeAllowedAiImageModels } from "./models"
+import {
+  DEFAULT_API_ENDPOINT,
+  DEFAULT_ASSET_SOURCE_TARGET_ID,
+  SETTINGS_TOOL_NAME,
+  SETTINGS_TOOL_TITLE,
+  type PluginOptions,
+  type ResolvedOptions,
+} from "./shared"
+
+export function normalizeOptions(options: PluginOptions): ResolvedOptions {
+  const assetSource =
+    options.assetSource === false ||
+    (typeof options.assetSource === "object" &&
+      options.assetSource.enabled === false)
+      ? null
+      : {
+          id:
+            typeof options.assetSource === "object"
+              ? options.assetSource.id || DEFAULT_ASSET_SOURCE_TARGET_ID
+              : DEFAULT_ASSET_SOURCE_TARGET_ID,
+          type: "assetSource" as const,
+          title:
+            typeof options.assetSource === "object"
+              ? options.assetSource.title || "Image Asset Source"
+              : "Image Asset Source",
+          ...(typeof options.assetSource === "object" &&
+          options.assetSource.description
+            ? { description: options.assetSource.description }
+            : {
+                description: "Adds AI Image Plugin to the image asset picker.",
+              }),
+          promptLabel:
+            typeof options.assetSource === "object"
+              ? options.assetSource.promptLabel || "Prompt"
+              : "Prompt",
+          promptPlaceholder:
+            typeof options.assetSource === "object"
+              ? options.assetSource.promptPlaceholder ||
+                "Turn these references into a clean homepage hero image with warm daylight and subtle depth."
+              : "Turn these references into a clean homepage hero image with warm daylight and subtle depth.",
+        }
+
+  return {
+    apiEndpoint: options.apiEndpoint || DEFAULT_API_ENDPOINT,
+    apiVersion: options.apiVersion,
+    allowedModels: normalizeAllowedAiImageModels(options.allowedModels),
+    assetSourceTarget: assetSource,
+    registerSettingsSchemaType:
+      options.settingsTool?.registerSchemaType === true,
+    settingsToolName: options.settingsTool?.name || SETTINGS_TOOL_NAME,
+    settingsToolTitle: options.settingsTool?.title || SETTINGS_TOOL_TITLE,
+    targets: options.targets || [],
+  }
+}

package/src/utils/context-fields.ts

@@ -0,0 +1,172 @@
+import { getValueAtPath } from "./document-paths"
+
+const SUPPORTED_CONTEXT_FIELD_TYPES = new Set([
+  "string",
+  "text",
+  "number",
+  "boolean",
+  "date",
+  "datetime",
+  "slug",
+])
+
+type DocumentSchemaFieldMember = {
+  name?: string
+  type?: {
+    name?: string
+  }
+}
+
+type DocumentSchemaField = {
+  name?: string
+  title?: string
+  type?: {
+    name?: string
+    of?: DocumentSchemaFieldMember[]
+  }
+}
+
+export type SelectableContextField = {
+  label: string
+  path: string
+  typeName: string
+}
+
+function getDocumentSchemaFields(documentSchema: unknown): DocumentSchemaField[] {
+  if (!documentSchema || typeof documentSchema !== "object") {
+    return []
+  }
+
+  const fields = (documentSchema as { fields?: unknown }).fields
+
+  return Array.isArray(fields) ? (fields as DocumentSchemaField[]) : []
+}
+
+function formatFieldNameAsLabel(fieldName: string): string {
+  const normalizedFieldName = fieldName
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[_-]+/g, " ")
+    .trim()
+    .replace(/\s+/g, " ")
+
+  if (!normalizedFieldName) {
+    return fieldName
+  }
+
+  return (
+    normalizedFieldName.charAt(0).toUpperCase() +
+    normalizedFieldName.slice(1).toLowerCase()
+  )
+}
+
+function isSimpleStringArrayField(field: DocumentSchemaField): boolean {
+  if (field.type?.name !== "array" || !Array.isArray(field.type.of)) {
+    return false
+  }
+
+  if (field.type.of.length === 0) {
+    return false
+  }
+
+  return field.type.of.every((member) => {
+    const memberTypeName = member?.type?.name || member?.name
+
+    return memberTypeName === "string"
+  })
+}
+
+export function getSelectableContextFields(
+  documentSchema: unknown
+): SelectableContextField[] {
+  return getDocumentSchemaFields(documentSchema).flatMap((field) => {
+    if (!field?.name || !field.type?.name) {
+      return []
+    }
+
+    const isSupportedScalarField = SUPPORTED_CONTEXT_FIELD_TYPES.has(
+      field.type.name
+    )
+
+    if (!isSupportedScalarField && !isSimpleStringArrayField(field)) {
+      return []
+    }
+
+    return [
+      {
+        label: field.title || formatFieldNameAsLabel(field.name),
+        path: field.name,
+        typeName: field.type.name,
+      },
+    ]
+  })
+}
+
+export function getDefaultSelectedContextFieldPaths(options: {
+  selectableContextFields: SelectableContextField[]
+  suggestedContextFieldPaths: string[] | undefined
+}): string[] {
+  const suggestedFieldPaths = new Set(
+    (options.suggestedContextFieldPaths || []).filter(Boolean)
+  )
+
+  return options.selectableContextFields
+    .filter((field) => suggestedFieldPaths.has(field.path))
+    .map((field) => field.path)
+}
+
+export function serializeContextFieldValue(value: unknown): string | null {
+  if (typeof value === "string") {
+    const trimmedValue = value.trim()
+
+    return trimmedValue || null
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value)
+  }
+
+  if (Array.isArray(value)) {
+    const serializedValues = value
+      .map((item) => (typeof item === "string" ? item.trim() : null))
+      .filter((item): item is string => Boolean(item))
+
+    return serializedValues.length > 0 ? serializedValues.join(", ") : null
+  }
+
+  if (value && typeof value === "object") {
+    const currentValue = (value as Record<string, unknown>).current
+
+    if (typeof currentValue === "string") {
+      const trimmedValue = currentValue.trim()
+
+      return trimmedValue || null
+    }
+  }
+
+  return null
+}
+
+export function buildContextFieldPrompt(options: {
+  contextFieldPaths: string[]
+  documentValue: Record<string, unknown> | undefined
+}): string | null {
+  if (!options.documentValue || options.contextFieldPaths.length === 0) {
+    return null
+  }
+
+  const promptLines = options.contextFieldPaths
+    .map((fieldPath) => {
+      const serializedValue = serializeContextFieldValue(
+        getValueAtPath(options.documentValue, fieldPath)
+      )
+
+      if (!serializedValue) {
+        return `The field titled "${fieldPath}" is empty.`
+      }
+
+      return `The value of field "${fieldPath}" is '${serializedValue}'.`
+    })
+    .filter((line): line is string => Boolean(line))
+
+  return promptLines.length > 0 ? promptLines.join("\n") : null
+}

package/src/utils/document-paths.ts

@@ -0,0 +1,51 @@
+import type { Path } from "sanity"
+import type { GenerateButtonTarget } from "./shared"
+
+export function pathToFieldPath(path: Path): string {
+  return path
+    .map((segment) => {
+      if (typeof segment === "string" || typeof segment === "number") {
+        return String(segment)
+      }
+
+      if (segment && typeof segment === "object" && "_key" in segment) {
+        return String(segment._key)
+      }
+
+      return ""
+    })
+    .filter(Boolean)
+    .join(".")
+}
+
+export function getValueAtPath(
+  value: Record<string, unknown> | undefined,
+  path: string | undefined
+): unknown {
+  if (!value || !path) {
+    return undefined
+  }
+
+  return path.split(".").reduce<unknown>((currentValue, segment) => {
+    if (!currentValue || typeof currentValue !== "object") {
+      return undefined
+    }
+
+    return (currentValue as Record<string, unknown>)[segment]
+  }, value)
+}
+
+export function doesTargetMatchField(options: {
+  documentType: string | undefined
+  path: Path
+  target: GenerateButtonTarget
+}): boolean {
+  if (!options.documentType) {
+    return false
+  }
+
+  return (
+    options.documentType === options.target.documentType &&
+    pathToFieldPath(options.path) === options.target.fieldPath
+  )
+}

package/src/utils/models.ts

@@ -0,0 +1,126 @@
+export const SUPPORTED_AI_IMAGE_MODELS = [
+  "gemini-2.5-flash-image",
+  "gemini-3.1-flash-image-preview",
+  "gpt-image-1",
+] as const
+
+export type SupportedAiImageModelId = (typeof SUPPORTED_AI_IMAGE_MODELS)[number]
+
+export type SupportedAiImageProvider = "google" | "openai"
+
+export type SupportedAiImageModelDefinition = {
+  defaultAspectRatio?: string
+  defaultSize?: string
+  id: SupportedAiImageModelId
+  provider: SupportedAiImageProvider
+  supportsReferenceImages: boolean
+  title: string
+}
+
+export const DEFAULT_SUPPORTED_AI_IMAGE_MODEL: SupportedAiImageModelId =
+  "gemini-2.5-flash-image"
+
+const SUPPORTED_AI_IMAGE_MODEL_DEFINITIONS = [
+  {
+    defaultAspectRatio: "1:1",
+    id: "gemini-2.5-flash-image",
+    provider: "google",
+    supportsReferenceImages: true,
+    title: "Google Gemini 2.5 Flash Image",
+  },
+  {
+    defaultAspectRatio: "1:1",
+    id: "gemini-3.1-flash-image-preview",
+    provider: "google",
+    supportsReferenceImages: true,
+    title: "Google Gemini 3.1 Flash Image Preview",
+  },
+  {
+    defaultSize: "1024x1024",
+    id: "gpt-image-1",
+    provider: "openai",
+    supportsReferenceImages: true,
+    title: "OpenAI GPT Image 1",
+  },
+] as const satisfies readonly SupportedAiImageModelDefinition[]
+
+const SUPPORTED_AI_IMAGE_MODEL_DEFINITION_MAP = Object.fromEntries(
+  SUPPORTED_AI_IMAGE_MODEL_DEFINITIONS.map((modelDefinition) => [
+    modelDefinition.id,
+    modelDefinition,
+  ])
+) as Record<SupportedAiImageModelId, SupportedAiImageModelDefinition>
+
+export function getSupportedAiImageModelDefinition(
+  modelId: SupportedAiImageModelId
+): SupportedAiImageModelDefinition {
+  return SUPPORTED_AI_IMAGE_MODEL_DEFINITION_MAP[modelId]
+}
+
+export function getSupportedAiImageModelOptions(
+  modelIds: readonly SupportedAiImageModelId[]
+): Array<{ title: string; value: SupportedAiImageModelId }> {
+  return modelIds.map((modelId) => {
+    const modelDefinition = getSupportedAiImageModelDefinition(modelId)
+
+    return {
+      title: modelDefinition.title,
+      value: modelDefinition.id,
+    }
+  })
+}
+
+export function isSupportedAiImageModelId(
+  value: string
+): value is SupportedAiImageModelId {
+  return (
+    SUPPORTED_AI_IMAGE_MODELS as readonly string[]
+  ).includes(value)
+}
+
+export function normalizeAllowedAiImageModels(
+  allowedModels?: readonly string[]
+): SupportedAiImageModelId[] {
+  if (!allowedModels) {
+    return [DEFAULT_SUPPORTED_AI_IMAGE_MODEL]
+  }
+
+  if (allowedModels.length === 0) {
+    throw new Error(
+      "AI Image Plugin requires at least one allowed model in allowedModels."
+    )
+  }
+
+  const normalizedAllowedModels: SupportedAiImageModelId[] = []
+
+  for (const allowedModel of allowedModels) {
+    if (!isSupportedAiImageModelId(allowedModel)) {
+      throw new Error(
+        `AI Image Plugin does not support the model "${allowedModel}".`
+      )
+    }
+
+    if (!normalizedAllowedModels.includes(allowedModel)) {
+      normalizedAllowedModels.push(allowedModel)
+    }
+  }
+
+  return normalizedAllowedModels
+}
+
+export function getDefaultAllowedAiImageModel(
+  allowedModels: readonly SupportedAiImageModelId[]
+): SupportedAiImageModelId {
+  return allowedModels[0] ?? DEFAULT_SUPPORTED_AI_IMAGE_MODEL
+}
+
+export function resolveAllowedAiImageModel(
+  modelId: string | null | undefined,
+  allowedModels: readonly SupportedAiImageModelId[]
+): SupportedAiImageModelId {
+  if (modelId && allowedModels.includes(modelId as SupportedAiImageModelId)) {
+    return modelId as SupportedAiImageModelId
+  }
+
+  return getDefaultAllowedAiImageModel(allowedModels)
+}

package/src/utils/prompts.ts

@@ -0,0 +1,6 @@
+export function composePrompt(parts: Array<string | null | undefined>): string {
+  return parts
+    .map((part) => part?.trim())
+    .filter((part): part is string => Boolean(part))
+    .join("\n\n")
+}

package/src/utils/shared.ts

@@ -0,0 +1,88 @@
+import type { SupportedAiImageModelId } from "./models"
+
+export const SOURCE_NAME = "ai-image-plugin"
+export const SOURCE_TITLE = "AI Image Plugin"
+export const SETTINGS_DOCUMENT_ID = "aiImagePlugin.settings"
+export const SETTINGS_SCHEMA_TYPE = "aiImagePluginSettings"
+export const SETTINGS_TOOL_NAME = "ai-image-plugin-settings"
+export const SETTINGS_TOOL_TITLE = "AI Image Plugin"
+export const DEFAULT_API_ENDPOINT = "/api/ai-image-plugin"
+export const DEFAULT_ASSET_SOURCE_TARGET_ID = "ai-image-plugin-asset-source"
+export const MAX_REFERENCE_IMAGES = 5
+
+export type StoredImage = {
+  asset?: {
+    _id?: string
+    _ref?: string
+    originalFilename?: string
+    url?: string
+  }
+}
+
+export type SettingsTargetConfigValue = {
+  prompt?: string
+  referenceImages?: StoredImage[]
+  targetId?: string
+}
+
+export type SettingsValue = {
+  globalModel?: SupportedAiImageModelId
+  globalPrompt?: string
+  globalReferenceImages?: StoredImage[]
+  targetConfigs?: SettingsTargetConfigValue[]
+}
+
+export type GenerateButtonTarget = {
+  description?: string
+  dialogTitle?: string
+  documentType: string
+  fieldPath: string
+  id: string
+  promptLabel?: string
+  promptPlaceholder?: string
+  suggestedContextFieldPaths?: string[]
+  title?: string
+  type: "generateButton"
+}
+
+export type AssetSourceTarget = {
+  description?: string
+  id: string
+  promptLabel?: string
+  promptPlaceholder?: string
+  title?: string
+  type: "assetSource"
+}
+
+export type PluginOptions = {
+  apiEndpoint?: string
+  apiVersion: string
+  allowedModels?: SupportedAiImageModelId[]
+  assetSource?:
+    | boolean
+    | {
+        description?: string
+        enabled?: boolean
+        id?: string
+        promptLabel?: string
+        promptPlaceholder?: string
+        title?: string
+      }
+  settingsTool?: {
+    name?: string
+    registerSchemaType?: boolean
+    title?: string
+  }
+  targets?: GenerateButtonTarget[]
+}
+
+export type ResolvedOptions = {
+  apiEndpoint: string
+  apiVersion: string
+  allowedModels: SupportedAiImageModelId[]
+  assetSourceTarget: AssetSourceTarget | null
+  registerSettingsSchemaType: boolean
+  settingsToolName: string
+  settingsToolTitle: string
+  targets: GenerateButtonTarget[]
+}