@jhb.software/payload-alt-text-plugin 0.10.0 → 0.11.0

package/dist/plugin.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/plugin.ts"],"sourcesContent":["import type { Config, Widget } from 'payload'\n\nimport type {\n  AltTextPluginConfig,\n  IncomingAltTextPluginConfig,\n} from './types/AltTextPluginConfig.js'\n\nimport { PLUGIN_SLUG } from './constants.js'\nimport { altTextHealthEndpoint } from './endpoints/altTextHealth.js'\nimport { bulkGenerateAltTextsEndpoint } from './endpoints/bulkGenerateAltTexts.js'\nimport { generateAltTextEndpoint } from './endpoints/generateAltText.js'\nimport { altTextField } from './fields/altTextField.js'\nimport { keywordsField } from './fields/keywordsField.js'\nimport {\n  createRevalidateAltTextHealthAfterChangeHook,\n  createRevalidateAltTextHealthAfterDeleteHook,\n} from './hooks/revalidateAltTextHealth.js'\nimport { translations } from './translations/index.js'\nimport { isValidMimeType, normalizeCollectionsConfig } from './utilities/mimeTypes.js'\nimport { deepMergeSimple } from './utils/deepMergeSimple.js'\n\nconst altTextHealthWidgetDefinition = {\n  slug: 'alt-text-health',\n  // `Component` was renamed from `ComponentPath` in Payload 3.79.0. Set both for backward compatibility.\n  Component: '@jhb.software/payload-alt-text-plugin/server#AltTextHealthWidget',\n  ComponentPath: '@jhb.software/payload-alt-text-plugin/server#AltTextHealthWidget',\n  label: {\n    de: 'Alternativtexte Zustand',\n    en: 'Alt text health',\n  },\n  maxWidth: 'full',\n  minWidth: 'medium',\n} satisfies { ComponentPath: string } & Widget\n\nexport const payloadAltTextPlugin =\n  (incomingPluginConfig: IncomingAltTextPluginConfig) =>\n  (incomingConfig: Config): Config => {\n    const config = { ...incomingConfig }\n\n    // If the plugin is disabled, return the config without modifying it\n    if (incomingPluginConfig.enabled === false) {\n      return config\n    }\n\n    const locales = config.localization\n      ? config.localization.locales.map((localeConfig) =>\n          typeof localeConfig === 'string' ? localeConfig : localeConfig.code,\n        )\n      : []\n\n    const enableHealthCheck = incomingPluginConfig.healthCheck !== false\n\n    const normalizedCollections = normalizeCollectionsConfig(incomingPluginConfig.collections, {\n      imageThumbnailMimeType: incomingPluginConfig.imageThumbnailMimeType,\n    })\n\n    // A declared thumbnail MIME type replaces the per-document source check, so a\n    // wrong one fails at boot rather than as a silently missing guard or a 500 per\n    // image.\n    const supportedMimeTypes = incomingPluginConfig.resolver.supportedMimeTypes\n    for (const collection of normalizedCollections) {\n      const declared = collection.imageThumbnailMimeType\n      if (declared === undefined) {\n        continue\n      }\n\n      if (!isValidMimeType(declared)) {\n        throw new Error(\n          `The alt-text plugin is configured with imageThumbnailMimeType \"${declared}\" for the \"${collection.slug}\" collection, ` +\n            'but that is not a valid MIME type. Expected something like \"image/webp\".',\n        )\n      }\n\n      if (supportedMimeTypes && !supportedMimeTypes.includes(declared)) {\n        throw new Error(\n          `The alt-text plugin is configured with imageThumbnailMimeType \"${declared}\" for the \"${collection.slug}\" collection, ` +\n            `but the \"${incomingPluginConfig.resolver.key}\" resolver does not support it. ` +\n            `Supported types: ${supportedMimeTypes.join(', ')}. ` +\n            \"Either change the transformation in getImageThumbnail, or remove the declaration to fall back to checking each document's own mime type.\",\n        )\n      }\n    }\n\n    const access = incomingPluginConfig.access ?? (({ req }) => !!req.user)\n\n    // A function form of `healthCheck` doubles as the health report's access\n    // gate; otherwise it falls back to the shared `access`.\n    const healthCheckAccess =\n      typeof incomingPluginConfig.healthCheck === 'function'\n        ? incomingPluginConfig.healthCheck\n        : access\n\n    const pluginConfig: AltTextPluginConfig = {\n      access,\n      collections: normalizedCollections,\n      enabled: incomingPluginConfig.enabled ?? true,\n      fieldsOverride: incomingPluginConfig.fieldsOverride,\n      getImageThumbnail: incomingPluginConfig.getImageThumbnail,\n      healthCheck: enableHealthCheck,\n      healthCheckAccess,\n      locale: incomingPluginConfig.locale,\n      locales,\n      maxBulkGenerateConcurrency: incomingPluginConfig.maxBulkGenerateConcurrency ?? 16,\n      maxBulkGenerateIds: incomingPluginConfig.maxBulkGenerateIds ?? 100,\n      resolver: incomingPluginConfig.resolver,\n    }\n\n    // Validate locale requirement for non-localized mode\n    if (locales.length === 0 && !incomingPluginConfig.locale) {\n      throw new Error(\n        'The alt-text plugin requires a \"locale\" option when Payload localization is disabled. ' +\n          'Please add { locale: \"en\" } (or your preferred locale) to your plugin configuration.',\n      )\n    }\n\n    const collectionConfigBySlug = new Map<string, (typeof normalizedCollections)[number]>(\n      normalizedCollections.map((entry) => [entry.slug, entry]),\n    )\n\n    // Ensure collections array exists\n    config.collections = config.collections || []\n\n    // Map over collections and inject AI alt text fields into specified ones\n    config.collections = config.collections.map((collectionConfig) => {\n      const altTextCollectionConfig = collectionConfigBySlug.get(collectionConfig.slug)\n\n      if (altTextCollectionConfig) {\n        if (!collectionConfig.upload) {\n          console.warn(\n            `AI Alt Text Plugin: Collection \"${collectionConfig.slug}\" is not an upload collection. Skipping field injection.`,\n          )\n          return collectionConfig\n        }\n\n        const defaultFields = [\n          altTextField({\n            localized: Boolean(config.localization),\n            // When the collection declares what getImageThumbnail delivers, the\n            // document's own mime type says nothing about whether generation can\n            // succeed — so don't let the admin UI disable the button on it.\n            supportedMimeTypes: altTextCollectionConfig.imageThumbnailMimeType\n              ? undefined\n              : pluginConfig.resolver.supportedMimeTypes,\n            trackedMimeTypes: altTextCollectionConfig.mimeTypes,\n            validate: altTextCollectionConfig.validate,\n          }),\n          keywordsField({\n            localized: Boolean(config.localization),\n          }),\n        ]\n\n        const fields =\n          incomingPluginConfig.fieldsOverride &&\n          typeof incomingPluginConfig.fieldsOverride === 'function'\n            ? incomingPluginConfig.fieldsOverride({ defaultFields })\n            : defaultFields\n\n        return {\n          ...collectionConfig,\n          admin: {\n            ...collectionConfig.admin,\n            components: {\n              ...(collectionConfig.admin?.components ?? {}),\n              // TODO: use the beforeBulkAction custom component slot once available: https://github.com/payloadcms/payload/pull/11719\n              beforeListTable: [\n                ...(collectionConfig.admin?.components?.beforeListTable ?? []),\n                {\n                  path: '@jhb.software/payload-alt-text-plugin/client#BulkGenerateAltTextsButton',\n                  props: {\n                    collectionSlug: collectionConfig.slug,\n                  },\n                },\n              ],\n            },\n            // enhance the search by adding the filename, keywords and alt fields (if the user has not provided their own listSearchableFields)\n            listSearchableFields: collectionConfig.admin?.listSearchableFields ?? [\n              'filename',\n              'keywords',\n              'alt',\n            ],\n          },\n          fields: [...(collectionConfig.fields ?? []), ...fields],\n          hooks: {\n            ...collectionConfig.hooks,\n            ...(enableHealthCheck && {\n              afterChange: [\n                ...(collectionConfig.hooks?.afterChange ?? []),\n                createRevalidateAltTextHealthAfterChangeHook(collectionConfig.slug),\n              ],\n              afterDelete: [\n                ...(collectionConfig.hooks?.afterDelete ?? []),\n                createRevalidateAltTextHealthAfterDeleteHook(collectionConfig.slug),\n              ],\n            }),\n          },\n        }\n      }\n\n      return collectionConfig\n    })\n\n    const existingWidgets = config.admin?.dashboard?.widgets ?? []\n    const widgets =\n      !enableHealthCheck || existingWidgets.some((widget) => widget.slug === 'alt-text-health')\n        ? existingWidgets\n        : [...existingWidgets, altTextHealthWidgetDefinition]\n\n    return {\n      ...config,\n      admin: {\n        ...config.admin,\n        dashboard: {\n          ...config.admin?.dashboard,\n          widgets,\n        },\n      },\n      custom: {\n        ...config.custom,\n        // Make plugin config available in hooks/actions\n        altTextPluginConfig: pluginConfig,\n      },\n      endpoints: [\n        ...(config.endpoints ?? []),\n        {\n          handler: generateAltTextEndpoint(pluginConfig.access),\n          method: 'post',\n          path: `/${PLUGIN_SLUG}/generate`,\n        },\n        {\n          handler: bulkGenerateAltTextsEndpoint(pluginConfig.access),\n          method: 'post',\n          path: `/${PLUGIN_SLUG}/generate/bulk`,\n        },\n        ...(enableHealthCheck\n          ? [\n              {\n                handler: altTextHealthEndpoint(pluginConfig.healthCheckAccess),\n                method: 'get' as const,\n                path: `/${PLUGIN_SLUG}/health`,\n              },\n            ]\n          : []),\n      ],\n      i18n: {\n        ...config.i18n,\n        translations: deepMergeSimple(translations, incomingConfig.i18n?.translations ?? {}),\n      },\n    }\n  }\n"],"names":["PLUGIN_SLUG","altTextHealthEndpoint","bulkGenerateAltTextsEndpoint","generateAltTextEndpoint","altTextField","keywordsField","createRevalidateAltTextHealthAfterChangeHook","createRevalidateAltTextHealthAfterDeleteHook","translations","isValidMimeType","normalizeCollectionsConfig","deepMergeSimple","altTextHealthWidgetDefinition","slug","Component","ComponentPath","label","de","en","maxWidth","minWidth","payloadAltTextPlugin","incomingPluginConfig","incomingConfig","config","enabled","locales","localization","map","localeConfig","code","enableHealthCheck","healthCheck","normalizedCollections","collections","imageThumbnailMimeType","supportedMimeTypes","resolver","collection","declared","undefined","Error","includes","key","join","access","req","user","healthCheckAccess","pluginConfig","fieldsOverride","getImageThumbnail","locale","maxBulkGenerateConcurrency","maxBulkGenerateIds","length","collectionConfigBySlug","Map","entry","collectionConfig","altTextCollectionConfig","get","upload","console","warn","defaultFields","localized","Boolean","trackedMimeTypes","mimeTypes","validate","fields","admin","components","beforeListTable","path","props","collectionSlug","listSearchableFields","hooks","afterChange","afterDelete","existingWidgets","dashboard","widgets","some","widget","custom","altTextPluginConfig","endpoints","handler","method","i18n"],"mappings":"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"}
+{"version":3,"sources":["../src/plugin.ts"],"sourcesContent":["import type { Config, Widget } from 'payload'\n\nimport type {\n  AltTextPluginConfig,\n  IncomingAltTextPluginConfig,\n} from './types/AltTextPluginConfig.js'\n\nimport { PLUGIN_SLUG } from './constants.js'\nimport { altTextHealthEndpoint } from './endpoints/altTextHealth.js'\nimport { bulkGenerateAltTextsEndpoint } from './endpoints/bulkGenerateAltTexts.js'\nimport { generateAltTextEndpoint } from './endpoints/generateAltText.js'\nimport { altTextField } from './fields/altTextField.js'\nimport { keywordsField } from './fields/keywordsField.js'\nimport {\n  createRevalidateAltTextHealthAfterChangeHook,\n  createRevalidateAltTextHealthAfterDeleteHook,\n} from './hooks/revalidateAltTextHealth.js'\nimport { translations } from './translations/index.js'\nimport { isValidMimeType, normalizeCollectionsConfig } from './utilities/mimeTypes.js'\nimport { deepMergeSimple } from './utils/deepMergeSimple.js'\n\nconst altTextHealthWidgetDefinition = {\n  slug: 'alt-text-health',\n  // `Component` was renamed from `ComponentPath` in Payload 3.79.0. Set both for backward compatibility.\n  Component: '@jhb.software/payload-alt-text-plugin/server#AltTextHealthWidget',\n  ComponentPath: '@jhb.software/payload-alt-text-plugin/server#AltTextHealthWidget',\n  label: {\n    de: 'Alternativtexte Zustand',\n    en: 'Alt text health',\n  },\n  maxWidth: 'full',\n  minWidth: 'medium',\n} satisfies { ComponentPath: string } & Widget\n\nexport const payloadAltTextPlugin =\n  (incomingPluginConfig: IncomingAltTextPluginConfig) =>\n  (incomingConfig: Config): Config => {\n    const config = { ...incomingConfig }\n\n    // If the plugin is disabled, return the config without modifying it\n    if (incomingPluginConfig.enabled === false) {\n      return config\n    }\n\n    const locales = config.localization\n      ? config.localization.locales.map((localeConfig) =>\n          typeof localeConfig === 'string' ? localeConfig : localeConfig.code,\n        )\n      : []\n\n    const enableHealthCheck = incomingPluginConfig.healthCheck !== false\n\n    const normalizedCollections = normalizeCollectionsConfig(incomingPluginConfig.collections, {\n      imageThumbnailMimeType: incomingPluginConfig.imageThumbnailMimeType,\n    })\n\n    // A declared thumbnail MIME type replaces the per-document source check, so a\n    // wrong one fails at boot rather than as a silently missing guard or a 500 per\n    // image.\n    const supportedMimeTypes = incomingPluginConfig.resolver.supportedMimeTypes\n    for (const collection of normalizedCollections) {\n      const declared = collection.imageThumbnailMimeType\n      if (declared === undefined) {\n        continue\n      }\n\n      if (!isValidMimeType(declared)) {\n        throw new Error(\n          `The alt-text plugin is configured with imageThumbnailMimeType \"${declared}\" for the \"${collection.slug}\" collection, ` +\n            'but that is not a valid MIME type. Expected something like \"image/webp\".',\n        )\n      }\n\n      if (supportedMimeTypes && !supportedMimeTypes.includes(declared)) {\n        throw new Error(\n          `The alt-text plugin is configured with imageThumbnailMimeType \"${declared}\" for the \"${collection.slug}\" collection, ` +\n            `but the \"${incomingPluginConfig.resolver.key}\" resolver does not support it. ` +\n            `Supported types: ${supportedMimeTypes.join(', ')}. ` +\n            \"Either change the transformation in getImageThumbnail, or remove the declaration to fall back to checking each document's own mime type.\",\n        )\n      }\n    }\n\n    const access = incomingPluginConfig.access ?? (({ req }) => !!req.user)\n\n    // The former function form was the health report's access gate. Accepting it\n    // silently would widen that gate to the plugin's `access`, so it fails at boot.\n    if (typeof incomingPluginConfig.healthCheck === 'function') {\n      throw new Error(\n        'The alt-text plugin no longer accepts a function for `healthCheck`. ' +\n          'Move the access check to `healthCheck: { access: ({ req }) => ... }`.',\n      )\n    }\n\n    const healthCheckConfig =\n      typeof incomingPluginConfig.healthCheck === 'object' ? incomingPluginConfig.healthCheck : {}\n\n    // The health report's own gate, falling back to the shared `access`.\n    const healthCheckAccess = healthCheckConfig.access ?? access\n\n    const pluginConfig: AltTextPluginConfig = {\n      access,\n      collections: normalizedCollections,\n      enabled: incomingPluginConfig.enabled ?? true,\n      fieldsOverride: incomingPluginConfig.fieldsOverride,\n      getImageThumbnail: incomingPluginConfig.getImageThumbnail,\n      healthCheck: enableHealthCheck,\n      healthCheckAccess,\n      healthCheckBaseFilter: healthCheckConfig.baseFilter,\n      locale: incomingPluginConfig.locale,\n      locales,\n      maxBulkGenerateConcurrency: incomingPluginConfig.maxBulkGenerateConcurrency ?? 16,\n      maxBulkGenerateIds: incomingPluginConfig.maxBulkGenerateIds ?? 100,\n      resolver: incomingPluginConfig.resolver,\n    }\n\n    // Validate locale requirement for non-localized mode\n    if (locales.length === 0 && !incomingPluginConfig.locale) {\n      throw new Error(\n        'The alt-text plugin requires a \"locale\" option when Payload localization is disabled. ' +\n          'Please add { locale: \"en\" } (or your preferred locale) to your plugin configuration.',\n      )\n    }\n\n    const collectionConfigBySlug = new Map<string, (typeof normalizedCollections)[number]>(\n      normalizedCollections.map((entry) => [entry.slug, entry]),\n    )\n\n    // Collected while collections are mapped and flushed in `onInit`: no Payload instance —\n    // and therefore no logger — exists while the config is still being built.\n    const configWarnings: string[] = []\n\n    // Ensure collections array exists\n    config.collections = config.collections || []\n\n    // Map over collections and inject AI alt text fields into specified ones\n    config.collections = config.collections.map((collectionConfig) => {\n      const altTextCollectionConfig = collectionConfigBySlug.get(collectionConfig.slug)\n\n      if (altTextCollectionConfig) {\n        if (!collectionConfig.upload) {\n          configWarnings.push(\n            `AI Alt Text Plugin: Collection \"${collectionConfig.slug}\" is not an upload collection. Skipping field injection.`,\n          )\n          return collectionConfig\n        }\n\n        const defaultFields = [\n          altTextField({\n            localized: Boolean(config.localization),\n            // When the collection declares what getImageThumbnail delivers, the\n            // document's own mime type says nothing about whether generation can\n            // succeed — so don't let the admin UI disable the button on it.\n            supportedMimeTypes: altTextCollectionConfig.imageThumbnailMimeType\n              ? undefined\n              : pluginConfig.resolver.supportedMimeTypes,\n            trackedMimeTypes: altTextCollectionConfig.mimeTypes,\n            validate: altTextCollectionConfig.validate,\n          }),\n          keywordsField({\n            localized: Boolean(config.localization),\n          }),\n        ]\n\n        const fields =\n          incomingPluginConfig.fieldsOverride &&\n          typeof incomingPluginConfig.fieldsOverride === 'function'\n            ? incomingPluginConfig.fieldsOverride({ defaultFields })\n            : defaultFields\n\n        return {\n          ...collectionConfig,\n          admin: {\n            ...collectionConfig.admin,\n            components: {\n              ...(collectionConfig.admin?.components ?? {}),\n              // TODO: use the beforeBulkAction custom component slot once available: https://github.com/payloadcms/payload/pull/11719\n              beforeListTable: [\n                ...(collectionConfig.admin?.components?.beforeListTable ?? []),\n                {\n                  path: '@jhb.software/payload-alt-text-plugin/client#BulkGenerateAltTextsButton',\n                  props: {\n                    collectionSlug: collectionConfig.slug,\n                  },\n                },\n              ],\n            },\n            // enhance the search by adding the filename, keywords and alt fields (if the user has not provided their own listSearchableFields)\n            listSearchableFields: collectionConfig.admin?.listSearchableFields ?? [\n              'filename',\n              'keywords',\n              'alt',\n            ],\n          },\n          fields: [...(collectionConfig.fields ?? []), ...fields],\n          hooks: {\n            ...collectionConfig.hooks,\n            ...(enableHealthCheck && {\n              afterChange: [\n                ...(collectionConfig.hooks?.afterChange ?? []),\n                createRevalidateAltTextHealthAfterChangeHook(collectionConfig.slug),\n              ],\n              afterDelete: [\n                ...(collectionConfig.hooks?.afterDelete ?? []),\n                createRevalidateAltTextHealthAfterDeleteHook(collectionConfig.slug),\n              ],\n            }),\n          },\n        }\n      }\n\n      return collectionConfig\n    })\n\n    const existingWidgets = config.admin?.dashboard?.widgets ?? []\n    const widgets =\n      !enableHealthCheck || existingWidgets.some((widget) => widget.slug === 'alt-text-health')\n        ? existingWidgets\n        : [...existingWidgets, altTextHealthWidgetDefinition]\n\n    return {\n      ...config,\n      admin: {\n        ...config.admin,\n        dashboard: {\n          ...config.admin?.dashboard,\n          widgets,\n        },\n      },\n      custom: {\n        ...config.custom,\n        // Make plugin config available in hooks/actions\n        altTextPluginConfig: pluginConfig,\n      },\n      endpoints: [\n        ...(config.endpoints ?? []),\n        {\n          handler: generateAltTextEndpoint(pluginConfig.access),\n          method: 'post',\n          path: `/${PLUGIN_SLUG}/generate`,\n        },\n        {\n          handler: bulkGenerateAltTextsEndpoint(pluginConfig.access),\n          method: 'post',\n          path: `/${PLUGIN_SLUG}/generate/bulk`,\n        },\n        ...(enableHealthCheck\n          ? [\n              {\n                handler: altTextHealthEndpoint(pluginConfig.healthCheckAccess),\n                method: 'get' as const,\n                path: `/${PLUGIN_SLUG}/health`,\n              },\n            ]\n          : []),\n      ],\n      i18n: {\n        ...config.i18n,\n        translations: deepMergeSimple(translations, incomingConfig.i18n?.translations ?? {}),\n      },\n      onInit: async (payload) => {\n        for (const warning of configWarnings) {\n          payload.logger.warn(warning)\n        }\n\n        await config.onInit?.(payload)\n      },\n    }\n  }\n"],"names":["PLUGIN_SLUG","altTextHealthEndpoint","bulkGenerateAltTextsEndpoint","generateAltTextEndpoint","altTextField","keywordsField","createRevalidateAltTextHealthAfterChangeHook","createRevalidateAltTextHealthAfterDeleteHook","translations","isValidMimeType","normalizeCollectionsConfig","deepMergeSimple","altTextHealthWidgetDefinition","slug","Component","ComponentPath","label","de","en","maxWidth","minWidth","payloadAltTextPlugin","incomingPluginConfig","incomingConfig","config","enabled","locales","localization","map","localeConfig","code","enableHealthCheck","healthCheck","normalizedCollections","collections","imageThumbnailMimeType","supportedMimeTypes","resolver","collection","declared","undefined","Error","includes","key","join","access","req","user","healthCheckConfig","healthCheckAccess","pluginConfig","fieldsOverride","getImageThumbnail","healthCheckBaseFilter","baseFilter","locale","maxBulkGenerateConcurrency","maxBulkGenerateIds","length","collectionConfigBySlug","Map","entry","configWarnings","collectionConfig","altTextCollectionConfig","get","upload","push","defaultFields","localized","Boolean","trackedMimeTypes","mimeTypes","validate","fields","admin","components","beforeListTable","path","props","collectionSlug","listSearchableFields","hooks","afterChange","afterDelete","existingWidgets","dashboard","widgets","some","widget","custom","altTextPluginConfig","endpoints","handler","method","i18n","onInit","payload","warning","logger","warn"],"mappings":"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"}

package/dist/resolvers/anthropic.d.ts

@@ -0,0 +1,65 @@
+import type { VisionInstructions } from './createVisionResolver.js';
+import type { AltTextResolver } from './types.js';
+export type AnthropicResolverConfig = {
+    /** Anthropic API key for authentication */
+    apiKey: string;
+    /**
+     * Base URL of the Anthropic API.
+     * @default 'https://api.anthropic.com'
+     */
+    baseUrl?: string;
+    /**
+     * Caps how long Claude thinks before answering. Lower effort still thinks on a
+     * difficult image, just less than a higher setting would.
+     *
+     * Describing an image is not a reasoning-heavy task, so `'low'` keeps the
+     * spend down on the models that accept it. Omitted, the field is not sent and
+     * Claude uses its default (`'high'`) — which also keeps models without effort
+     * support, such as `claude-haiku-4-5`, usable.
+     */
+    effort?: 'high' | 'low' | 'max' | 'medium' | 'xhigh';
+    /**
+     * Builds the instructions from the default ones, e.g. to append a house style
+     * rule. Sent as the system prompt, separately from the image.
+     *
+     * @default ({ defaultInstructions }) => defaultInstructions
+     */
+    instructions?: VisionInstructions;
+    /**
+     * The Claude model to use for alt text generation.
+     *
+     * Must be able to read images. `claude-sonnet-5` is the cheaper choice for a
+     * large media library; `claude-haiku-4-5` works too, but only without
+     * `effort`.
+     *
+     * @default 'claude-opus-5'
+     */
+    model?: string;
+    /**
+     * Abort after this many milliseconds. Covers downloading the image and the
+     * message call together.
+     * @default 30000
+     */
+    timeoutMs?: number;
+};
+/**
+ * Creates a Claude-based resolver for alt text generation.
+ *
+ * The image is downloaded and sent as bytes. Claude can fetch an image URL
+ * itself, but that path is not dependable for a CMS: it requires the file to be
+ * reachable from the public internet — never true in local development, and not
+ * true for private buckets. Sending the bytes removes that whole class of
+ * failure for the price of one extra download, and supplies the `media_type`
+ * that a base64 image block requires and a URL cannot carry.
+ *
+ * @example
+ * ```typescript
+ * import { anthropicResolver } from '@jhb.software/payload-alt-text-plugin'
+ *
+ * anthropicResolver({
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ *   model: 'claude-opus-5', // optional, this is the default
+ * })
+ * ```
+ */
+export declare const anthropicResolver: ({ apiKey, baseUrl, effort, instructions, model, timeoutMs, }: AnthropicResolverConfig) => AltTextResolver;

package/dist/resolvers/anthropic.js

@@ -0,0 +1,141 @@
+import { createVisionResolver, VisionProviderError } from './createVisionResolver.js';
+/**
+ * Image formats the Messages API accepts.
+ *
+ * Narrower than what an upload collection may hold — SVG and AVIF are missing,
+ * so the endpoint rejects those documents and their generate button stays
+ * disabled instead of failing at the provider.
+ *
+ * @see https://platform.claude.com/docs/en/build-with-claude/vision
+ */ const SUPPORTED_MIME_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp'
+];
+/**
+ * Claude's 10 MB ceiling is measured on the base64 payload, which inflates the
+ * raw bytes by roughly 4/3 — so the guard has to sit at ~7.5 MB of raw image to
+ * mean 10 MB on the wire. Checking the raw length against 10 MB would wave
+ * through a 9 MB photo that arrives as ~12 MB and is rejected by the provider,
+ * costing the download and replacing a readable message with a raw 400.
+ */ const MAX_IMAGE_BYTES = Math.floor(10 * 1024 * 1024 * 3 / 4);
+/**
+ * Room for one alt text and its keywords per locale, plus the thinking tokens
+ * Claude spends before answering. A budget sized for the answer alone would be
+ * exhausted while reasoning, and the response would be cut off mid-JSON.
+ */ const MAX_TOKENS_PER_LOCALE = 2000;
+/**
+ * Creates a Claude-based resolver for alt text generation.
+ *
+ * The image is downloaded and sent as bytes. Claude can fetch an image URL
+ * itself, but that path is not dependable for a CMS: it requires the file to be
+ * reachable from the public internet — never true in local development, and not
+ * true for private buckets. Sending the bytes removes that whole class of
+ * failure for the price of one extra download, and supplies the `media_type`
+ * that a base64 image block requires and a URL cannot carry.
+ *
+ * @example
+ * ```typescript
+ * import { anthropicResolver } from '@jhb.software/payload-alt-text-plugin'
+ *
+ * anthropicResolver({
+ *   apiKey: process.env.ANTHROPIC_API_KEY,
+ *   model: 'claude-opus-5', // optional, this is the default
+ * })
+ * ```
+ */ export const anthropicResolver = ({ apiKey, baseUrl = 'https://api.anthropic.com', effort, instructions, model = 'claude-opus-5', timeoutMs = 30_000 })=>createVisionResolver({
+        apiKey,
+        generate: async ({ filename, image, instructions: resolvedInstructions, maxTokens, responseSchema, signal })=>{
+            if (!image) {
+                throw new Error('The image was not downloaded');
+            }
+            const response = await fetch(`${baseUrl}/v1/messages`, {
+                body: JSON.stringify({
+                    max_tokens: maxTokens,
+                    messages: [
+                        {
+                            content: [
+                                // Claude works best when the image comes before the text.
+                                {
+                                    type: 'image',
+                                    source: {
+                                        type: 'base64',
+                                        data: image.base64,
+                                        media_type: image.mediaType
+                                    }
+                                },
+                                ...filename ? [
+                                    {
+                                        type: 'text',
+                                        text: filename
+                                    }
+                                ] : []
+                            ],
+                            role: 'user'
+                        }
+                    ],
+                    model,
+                    // `format` constrains the response to the schema the plugin needs;
+                    // `effort` caps how long Claude thinks before producing it. Only sent
+                    // when configured: some models reject the field outright.
+                    output_config: {
+                        ...effort ? {
+                            effort
+                        } : {},
+                        format: {
+                            type: 'json_schema',
+                            schema: responseSchema
+                        }
+                    },
+                    // The instructions are an operator instruction, not a turn in the
+                    // conversation, so they travel as the top-level system prompt.
+                    system: resolvedInstructions
+                }),
+                headers: {
+                    'anthropic-version': '2023-06-01',
+                    'content-type': 'application/json',
+                    'x-api-key': apiKey
+                },
+                method: 'POST',
+                signal
+            });
+            if (!response.ok) {
+                // Bounded: unbounded provider text would land in the log as-is.
+                const body = (await response.text().catch(()=>'')).slice(0, 500);
+                throw new VisionProviderError({
+                    body,
+                    label: 'Anthropic',
+                    status: response.status
+                });
+            }
+            const message = await response.json();
+            // A refusal and a truncated answer both arrive as a 200 with unusable
+            // content, so they are named rather than surfacing as a JSON parse error.
+            if (message.stop_reason === 'refusal') {
+                throw new Error('Claude declined to describe this image');
+            }
+            if (message.stop_reason === 'max_tokens') {
+                throw new Error(`Claude ran out of tokens before finishing the alt text (max_tokens: ${maxTokens})`);
+            }
+            const text = message.content?.find((block)=>block.type === 'text')?.text;
+            if (typeof text !== 'string') {
+                throw new Error('No result from Anthropic');
+            }
+            try {
+                return JSON.parse(text);
+            } catch  {
+                throw new Error('Claude returned a response that was not valid JSON');
+            }
+        },
+        inlineImage: true,
+        instructions,
+        key: 'anthropic',
+        label: 'Anthropic',
+        maxImageBytes: MAX_IMAGE_BYTES,
+        maxTokensPerLocale: MAX_TOKENS_PER_LOCALE,
+        supportedMimeTypes: SUPPORTED_MIME_TYPES,
+        timeoutMs
+    });
+
+//# sourceMappingURL=anthropic.js.map

package/dist/resolvers/anthropic.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/resolvers/anthropic.ts"],"sourcesContent":["import type { VisionInstructions } from './createVisionResolver.js'\nimport type { AltTextResolver } from './types.js'\n\nimport { createVisionResolver, VisionProviderError } from './createVisionResolver.js'\n\nexport type AnthropicResolverConfig = {\n  /** Anthropic API key for authentication */\n  apiKey: string\n  /**\n   * Base URL of the Anthropic API.\n   * @default 'https://api.anthropic.com'\n   */\n  baseUrl?: string\n  /**\n   * Caps how long Claude thinks before answering. Lower effort still thinks on a\n   * difficult image, just less than a higher setting would.\n   *\n   * Describing an image is not a reasoning-heavy task, so `'low'` keeps the\n   * spend down on the models that accept it. Omitted, the field is not sent and\n   * Claude uses its default (`'high'`) — which also keeps models without effort\n   * support, such as `claude-haiku-4-5`, usable.\n   */\n  effort?: 'high' | 'low' | 'max' | 'medium' | 'xhigh'\n  /**\n   * Builds the instructions from the default ones, e.g. to append a house style\n   * rule. Sent as the system prompt, separately from the image.\n   *\n   * @default ({ defaultInstructions }) => defaultInstructions\n   */\n  instructions?: VisionInstructions\n  /**\n   * The Claude model to use for alt text generation.\n   *\n   * Must be able to read images. `claude-sonnet-5` is the cheaper choice for a\n   * large media library; `claude-haiku-4-5` works too, but only without\n   * `effort`.\n   *\n   * @default 'claude-opus-5'\n   */\n  model?: string\n  /**\n   * Abort after this many milliseconds. Covers downloading the image and the\n   * message call together.\n   * @default 30000\n   */\n  timeoutMs?: number\n}\n\n/**\n * Image formats the Messages API accepts.\n *\n * Narrower than what an upload collection may hold — SVG and AVIF are missing,\n * so the endpoint rejects those documents and their generate button stays\n * disabled instead of failing at the provider.\n *\n * @see https://platform.claude.com/docs/en/build-with-claude/vision\n */\nconst SUPPORTED_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n\n/**\n * Claude's 10 MB ceiling is measured on the base64 payload, which inflates the\n * raw bytes by roughly 4/3 — so the guard has to sit at ~7.5 MB of raw image to\n * mean 10 MB on the wire. Checking the raw length against 10 MB would wave\n * through a 9 MB photo that arrives as ~12 MB and is rejected by the provider,\n * costing the download and replacing a readable message with a raw 400.\n */\nconst MAX_IMAGE_BYTES = Math.floor((10 * 1024 * 1024 * 3) / 4)\n\n/**\n * Room for one alt text and its keywords per locale, plus the thinking tokens\n * Claude spends before answering. A budget sized for the answer alone would be\n * exhausted while reasoning, and the response would be cut off mid-JSON.\n */\nconst MAX_TOKENS_PER_LOCALE = 2000\n\ntype AnthropicMessage = {\n  content?: { text?: string; type: string }[]\n  stop_reason?: string\n}\n\n/**\n * Creates a Claude-based resolver for alt text generation.\n *\n * The image is downloaded and sent as bytes. Claude can fetch an image URL\n * itself, but that path is not dependable for a CMS: it requires the file to be\n * reachable from the public internet — never true in local development, and not\n * true for private buckets. Sending the bytes removes that whole class of\n * failure for the price of one extra download, and supplies the `media_type`\n * that a base64 image block requires and a URL cannot carry.\n *\n * @example\n * ```typescript\n * import { anthropicResolver } from '@jhb.software/payload-alt-text-plugin'\n *\n * anthropicResolver({\n *   apiKey: process.env.ANTHROPIC_API_KEY,\n *   model: 'claude-opus-5', // optional, this is the default\n * })\n * ```\n */\nexport const anthropicResolver = ({\n  apiKey,\n  baseUrl = 'https://api.anthropic.com',\n  effort,\n  instructions,\n  model = 'claude-opus-5',\n  timeoutMs = 30_000,\n}: AnthropicResolverConfig): AltTextResolver =>\n  createVisionResolver({\n    apiKey,\n    generate: async ({\n      filename,\n      image,\n      instructions: resolvedInstructions,\n      maxTokens,\n      responseSchema,\n      signal,\n    }) => {\n      if (!image) {\n        throw new Error('The image was not downloaded')\n      }\n\n      const response = await fetch(`${baseUrl}/v1/messages`, {\n        body: JSON.stringify({\n          max_tokens: maxTokens,\n          messages: [\n            {\n              content: [\n                // Claude works best when the image comes before the text.\n                {\n                  type: 'image',\n                  source: { type: 'base64', data: image.base64, media_type: image.mediaType },\n                },\n                ...(filename ? [{ type: 'text', text: filename }] : []),\n              ],\n              role: 'user',\n            },\n          ],\n          model,\n          // `format` constrains the response to the schema the plugin needs;\n          // `effort` caps how long Claude thinks before producing it. Only sent\n          // when configured: some models reject the field outright.\n          output_config: {\n            ...(effort ? { effort } : {}),\n            format: { type: 'json_schema', schema: responseSchema },\n          },\n          // The instructions are an operator instruction, not a turn in the\n          // conversation, so they travel as the top-level system prompt.\n          system: resolvedInstructions,\n        }),\n        headers: {\n          'anthropic-version': '2023-06-01',\n          'content-type': 'application/json',\n          'x-api-key': apiKey,\n        },\n        method: 'POST',\n        signal,\n      })\n\n      if (!response.ok) {\n        // Bounded: unbounded provider text would land in the log as-is.\n        const body = (await response.text().catch(() => '')).slice(0, 500)\n\n        throw new VisionProviderError({ body, label: 'Anthropic', status: response.status })\n      }\n\n      const message = (await response.json()) as AnthropicMessage\n\n      // A refusal and a truncated answer both arrive as a 200 with unusable\n      // content, so they are named rather than surfacing as a JSON parse error.\n      if (message.stop_reason === 'refusal') {\n        throw new Error('Claude declined to describe this image')\n      }\n\n      if (message.stop_reason === 'max_tokens') {\n        throw new Error(\n          `Claude ran out of tokens before finishing the alt text (max_tokens: ${maxTokens})`,\n        )\n      }\n\n      const text = message.content?.find((block) => block.type === 'text')?.text\n\n      if (typeof text !== 'string') {\n        throw new Error('No result from Anthropic')\n      }\n\n      try {\n        return JSON.parse(text)\n      } catch {\n        throw new Error('Claude returned a response that was not valid JSON')\n      }\n    },\n    inlineImage: true,\n    instructions,\n    key: 'anthropic',\n    label: 'Anthropic',\n    maxImageBytes: MAX_IMAGE_BYTES,\n    maxTokensPerLocale: MAX_TOKENS_PER_LOCALE,\n    supportedMimeTypes: SUPPORTED_MIME_TYPES,\n    timeoutMs,\n  })\n"],"names":["createVisionResolver","VisionProviderError","SUPPORTED_MIME_TYPES","MAX_IMAGE_BYTES","Math","floor","MAX_TOKENS_PER_LOCALE","anthropicResolver","apiKey","baseUrl","effort","instructions","model","timeoutMs","generate","filename","image","resolvedInstructions","maxTokens","responseSchema","signal","Error","response","fetch","body","JSON","stringify","max_tokens","messages","content","type","source","data","base64","media_type","mediaType","text","role","output_config","format","schema","system","headers","method","ok","catch","slice","label","status","message","json","stop_reason","find","block","parse","inlineImage","key","maxImageBytes","maxTokensPerLocale","supportedMimeTypes"],"mappings":"AAGA,SAASA,oBAAoB,EAAEC,mBAAmB,QAAQ,4BAA2B;AA6CrF;;;;;;;;CAQC,GACD,MAAMC,uBAAuB;IAAC;IAAc;IAAa;IAAa;CAAa;AAEnF;;;;;;CAMC,GACD,MAAMC,kBAAkBC,KAAKC,KAAK,CAAC,AAAC,KAAK,OAAO,OAAO,IAAK;AAE5D;;;;CAIC,GACD,MAAMC,wBAAwB;AAO9B;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,MAAMC,oBAAoB,CAAC,EAChCC,MAAM,EACNC,UAAU,2BAA2B,EACrCC,MAAM,EACNC,YAAY,EACZC,QAAQ,eAAe,EACvBC,YAAY,MAAM,EACM,GACxBb,qBAAqB;QACnBQ;QACAM,UAAU,OAAO,EACfC,QAAQ,EACRC,KAAK,EACLL,cAAcM,oBAAoB,EAClCC,SAAS,EACTC,cAAc,EACdC,MAAM,EACP;YACC,IAAI,CAACJ,OAAO;gBACV,MAAM,IAAIK,MAAM;YAClB;YAEA,MAAMC,WAAW,MAAMC,MAAM,GAAGd,QAAQ,YAAY,CAAC,EAAE;gBACrDe,MAAMC,KAAKC,SAAS,CAAC;oBACnBC,YAAYT;oBACZU,UAAU;wBACR;4BACEC,SAAS;gCACP,0DAA0D;gCAC1D;oCACEC,MAAM;oCACNC,QAAQ;wCAAED,MAAM;wCAAUE,MAAMhB,MAAMiB,MAAM;wCAAEC,YAAYlB,MAAMmB,SAAS;oCAAC;gCAC5E;mCACIpB,WAAW;oCAAC;wCAAEe,MAAM;wCAAQM,MAAMrB;oCAAS;iCAAE,GAAG,EAAE;6BACvD;4BACDsB,MAAM;wBACR;qBACD;oBACDzB;oBACA,mEAAmE;oBACnE,sEAAsE;oBACtE,0DAA0D;oBAC1D0B,eAAe;wBACb,GAAI5B,SAAS;4BAAEA;wBAAO,IAAI,CAAC,CAAC;wBAC5B6B,QAAQ;4BAAET,MAAM;4BAAeU,QAAQrB;wBAAe;oBACxD;oBACA,kEAAkE;oBAClE,+DAA+D;oBAC/DsB,QAAQxB;gBACV;gBACAyB,SAAS;oBACP,qBAAqB;oBACrB,gBAAgB;oBAChB,aAAalC;gBACf;gBACAmC,QAAQ;gBACRvB;YACF;YAEA,IAAI,CAACE,SAASsB,EAAE,EAAE;gBAChB,gEAAgE;gBAChE,MAAMpB,OAAO,AAAC,CAAA,MAAMF,SAASc,IAAI,GAAGS,KAAK,CAAC,IAAM,GAAE,EAAGC,KAAK,CAAC,GAAG;gBAE9D,MAAM,IAAI7C,oBAAoB;oBAAEuB;oBAAMuB,OAAO;oBAAaC,QAAQ1B,SAAS0B,MAAM;gBAAC;YACpF;YAEA,MAAMC,UAAW,MAAM3B,SAAS4B,IAAI;YAEpC,sEAAsE;YACtE,0EAA0E;YAC1E,IAAID,QAAQE,WAAW,KAAK,WAAW;gBACrC,MAAM,IAAI9B,MAAM;YAClB;YAEA,IAAI4B,QAAQE,WAAW,KAAK,cAAc;gBACxC,MAAM,IAAI9B,MACR,CAAC,oEAAoE,EAAEH,UAAU,CAAC,CAAC;YAEvF;YAEA,MAAMkB,OAAOa,QAAQpB,OAAO,EAAEuB,KAAK,CAACC,QAAUA,MAAMvB,IAAI,KAAK,SAASM;YAEtE,IAAI,OAAOA,SAAS,UAAU;gBAC5B,MAAM,IAAIf,MAAM;YAClB;YAEA,IAAI;gBACF,OAAOI,KAAK6B,KAAK,CAAClB;YACpB,EAAE,OAAM;gBACN,MAAM,IAAIf,MAAM;YAClB;QACF;QACAkC,aAAa;QACb5C;QACA6C,KAAK;QACLT,OAAO;QACPU,eAAetD;QACfuD,oBAAoBpD;QACpBqD,oBAAoBzD;QACpBW;IACF,GAAE"}

package/dist/resolvers/createVisionResolver.d.ts

@@ -0,0 +1,148 @@
+import type { PayloadRequest } from 'payload';
+import { z } from 'zod';
+import type { AltTextResolver } from './types.js';
+export type VisionInstructionsArgs = {
+    /** The instructions the resolver would send on its own, stating the rules the plugin depends on */
+    defaultInstructions: string;
+    /** The uploaded file's name, when the endpoint could supply one */
+    filename?: string;
+    /** The locales the response must cover, as configured in Payload */
+    locales: string[];
+};
+export type VisionInstructions = (args: VisionInstructionsArgs) => Promise<string> | string;
+/** The thumbnail's bytes, handed to providers that declared `inlineImage`. */
+export type VisionImage = {
+    /** Base64-encoded bytes, without a data URI prefix */
+    base64: string;
+    /** `data:<mediaType>;base64,<base64>`, for providers that take a data URI */
+    dataUri: string;
+    /** The format actually served at the thumbnail URL, not the document's stored one */
+    mediaType: string;
+};
+export type VisionGenerateArgs = {
+    /** The uploaded file's name, when the endpoint could supply one */
+    filename?: string;
+    /** The downloaded thumbnail — present only when the resolver declared `inlineImage` */
+    image?: VisionImage;
+    /**
+     * The format the collection declares `getImageThumbnail` delivers, or
+     * undefined when nothing was declared. Resolvers that inline the bytes should
+     * use `image.mediaType`, which is what the URL actually served, with this
+     * declaration already standing in when the host named no usable type.
+     */
+    imageThumbnailMimeType?: string;
+    /** URL of the image thumbnail, for providers that fetch it themselves */
+    imageThumbnailUrl: string;
+    /** The instructions to send, e.g. as the system prompt */
+    instructions: string;
+    /** The locales the response must cover */
+    locales: string[];
+    /** Token budget for the response, scaled by the number of requested locales */
+    maxTokens: number;
+    req: PayloadRequest;
+    /** Draft-7 JSON Schema of the object the provider must return */
+    responseSchema: Record<string, unknown>;
+    /**
+     * Aborts once `timeoutMs` has elapsed, already covering the image download.
+     * Undefined when the resolver declares no `timeoutMs`, leaving the deadline to
+     * the provider client.
+     */
+    signal?: AbortSignal;
+};
+/**
+ * A non-ok HTTP response from a provider.
+ *
+ * Carries the status so the factory can tell a rate limit or an outage — worth
+ * another attempt — from a malformed request, which would fail identically every
+ * time.
+ *
+ * The response body is kept off `message` deliberately. That message is shown in
+ * the admin panel to anyone allowed to generate an alt text, while the body is
+ * text the provider chose: OpenAI echoes a masked form of the rejected API key
+ * into a 401, and providers routinely name organization ids, project ids and
+ * internal endpoints. It goes to the server log, where the person debugging the
+ * configuration is, and not to an editor's screen.
+ */
+export declare class VisionProviderError extends Error {
+    /** The provider's response body, for the log only — never for `message`. */
+    readonly body?: string;
+    readonly status: number;
+    constructor({ body, label, status }: {
+        body?: string;
+        label: string;
+        status: number;
+    });
+    /** Rate limits and server-side failures are transient; a 4xx is not. */
+    get isTransient(): boolean;
+}
+export type VisionResolverConfig = {
+    /**
+     * Checked before any work happens, so a plugin wired as
+     * `enabled: !!process.env.X_API_KEY` fails with a readable message instead of
+     * a provider error — or, worse, a paid-for image download.
+     */
+    apiKey: string;
+    /**
+     * Sends one request to the provider and resolves with its parsed JSON
+     * response. Rejecting fails the generation, so provider errors need no
+     * special handling beyond throwing a readable message.
+     */
+    generate: (args: VisionGenerateArgs) => Promise<unknown>;
+    /**
+     * Download the thumbnail and hand `generate` the bytes rather than the URL.
+     *
+     * Needed by every provider whose own fetcher requires a publicly reachable
+     * file — never true in local development, not true for private buckets.
+     */
+    inlineImage?: boolean;
+    /**
+     * Builds the instructions from the default ones, e.g. to append a house style
+     * rule. Called once per generation. The image and the required response shape
+     * are not part of the instructions and cannot be altered here.
+     *
+     * @default ({ defaultInstructions }) => defaultInstructions
+     */
+    instructions?: VisionInstructions;
+    /** Identifies the resolver, e.g. in log entries */
+    key: string;
+    /** Provider name used in error messages shown in the admin UI */
+    label: string;
+    /**
+     * Rejects an inlined image above this size before it is sent.
+     * @default 20971520 (20 MB)
+     */
+    maxImageBytes?: number;
+    /**
+     * Token budget granted per requested locale. A ceiling, not a reservation, so
+     * headroom is free; the default keeps the pre-factory bulk budget of 300 for
+     * every locale count rather than only for two or more.
+     * @default 300
+     */
+    maxTokensPerLocale?: number;
+    /** @see AltTextResolver.supportedMimeTypes */
+    supportedMimeTypes?: string[];
+    /**
+     * Abort after this many milliseconds, covering the image download and the
+     * provider call together. Omit it to impose no deadline of the factory's own —
+     * appropriate when the provider's own client already has one.
+     */
+    timeoutMs?: number;
+};
+/** One schema entry per requested locale, so the model must answer for all of them. */
+export declare const schemaForLocales: (locales: string[]) => z.ZodObject<{
+    [x: string]: z.ZodObject<{
+        altText: z.ZodString;
+        keywords: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Creates a resolver for a vision (LLM) provider, leaving only the provider call
+ * to `generate`: the prompt, the required response schema, the optional image
+ * download and the strict reading of the response are handled here.
+ *
+ * All locales go into a single call rather than one call each: the image is
+ * uploaded and analyzed once — the expensive part — and every language ends up
+ * describing the same reading of it. `resolve` is that same call with one
+ * locale.
+ */
+export declare const createVisionResolver: ({ apiKey, generate, inlineImage, instructions, key, label, maxImageBytes, maxTokensPerLocale, supportedMimeTypes, timeoutMs, }: VisionResolverConfig) => AltTextResolver;