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

package/dist/resolvers/anthropic.js

@@ -0,0 +1,140 @@
+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. Sending the bytes removes that whole class
+ * of failure for the price of one extra download. The `media_type` a base64 image block carries
+ * comes from the download, which reads it off what the thumbnail URL served.
+ *
+ * @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. Sending the bytes removes that whole class\n * of failure for the price of one extra download. The `media_type` a base64 image block carries\n * comes from the download, which reads it off what the thumbnail URL served.\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;;;;;;;;;;;;;;;;;;CAkBC,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.
+     */
+    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;

package/dist/resolvers/createVisionResolver.js

@@ -0,0 +1,300 @@
+import { z } from 'zod';
+/**
+ * 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 class VisionProviderError extends Error {
+    /** The provider's response body, for the log only — never for `message`. */ body;
+    status;
+    constructor({ body, label, status }){
+        super(`${label} responded with status ${status}`);
+        this.body = body;
+        this.name = 'VisionProviderError';
+        this.status = status;
+    }
+    /** Rate limits and server-side failures are transient; a 4xx is not. */ get isTransient() {
+        return this.status === 429 || this.status >= 500;
+    }
+}
+/** Attempts after the first, for a provider error that may pass on a retry. */ const MAX_RETRIES = 2;
+/** Backs off between attempts, bounded by the resolver's own deadline. */ const retryDelayMs = (attempt)=>250 * 2 ** (attempt - 1);
+const altTextSchema = z.object({
+    altText: z.string().describe('A concise, descriptive alt text for the image'),
+    keywords: z.array(z.string()).describe('Keywords that describe the content of the image')
+});
+/** One schema entry per requested locale, so the model must answer for all of them. */ export const schemaForLocales = (locales)=>z.object(Object.fromEntries(locales.map((locale)=>[
+            locale,
+            altTextSchema
+        ])));
+/**
+ * Rules dictated by the plugin rather than by the provider: one entry per
+ * configured locale, describing what is visible rather than guessing at it.
+ */ const buildDefaultInstructions = ({ locales })=>[
+        `You are an expert at analyzing images and creating descriptive image alt text.`,
+        `Please analyze the given image and provide the following in ${locales.join(', ')}:`,
+        `- A concise, localized descriptive alt text (1-2 sentences) as "altText". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.`,
+        `- A localized list of keywords that describe the content (e.g., ["Camel", "Palm trees", "Desert"]) as "keywords"`,
+        `If a context is provided, use it to enhance the alt text.`,
+        `Format your response as a JSON object with ${locales.map((locale)=>`"${locale}"`).join(', ')} keys, each containing "altText" and "keywords".`
+    ].join('\n\n');
+/**
+ * Downloads the image and returns its bytes.
+ *
+ * The document's mime type is checked by the endpoint before the resolver runs,
+ * but `getImageThumbnail` may point at a derivative in a different format, so
+ * what was actually served is what counts. Only when the host names no usable
+ * type at all — no header, or a generic `application/octet-stream` as private
+ * buckets and signed URLs often send — does the collection's declared
+ * `imageThumbnailMimeType` stand in for it.
+ */ async function fetchImage({ declaredMediaType, label, maxImageBytes, signal, supportedMimeTypes, url }) {
+    let response;
+    try {
+        response = await fetch(url, {
+            signal
+        });
+    } catch (error) {
+        return {
+            error: `Could not download the image from ${url}: ${error instanceof Error ? error.message : 'unknown error'}`
+        };
+    }
+    if (!response.ok) {
+        return {
+            error: `Could not download the image from ${url}: status ${response.status}`
+        };
+    }
+    const served = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
+    const mediaType = served && served !== 'application/octet-stream' ? served : declaredMediaType?.toLowerCase();
+    if (!mediaType) {
+        return {
+            error: `The image at ${url} was served as ${served ? `"${served}"` : 'no content type at all'}, which does not name an image format. Declare imageThumbnailMimeType for the collection so ${label} knows what it is reading.`
+        };
+    }
+    if (supportedMimeTypes && !supportedMimeTypes.includes(mediaType)) {
+        return {
+            error: `The image at ${url} was served as "${mediaType}", which ${label} cannot read. Supported types: ${supportedMimeTypes.join(', ')}.`
+        };
+    }
+    const tooLarge = (byteLength)=>`The image at ${url} is ${Math.round(byteLength / 1024 / 1024)} MB, above ${label}'s ${Math.round(maxImageBytes / 1024 / 1024)} MB limit. Point getImageThumbnail at a smaller image size.`;
+    // Measuring by reading is work the header already answers, and the file is on
+    // its way to being rejected: `getImageThumbnail` may point at the original
+    // upload, which can be far above the provider's limit.
+    const declaredLength = Number(response.headers.get('content-length'));
+    if (Number.isInteger(declaredLength) && declaredLength > maxImageBytes) {
+        return {
+            error: tooLarge(declaredLength)
+        };
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.byteLength === 0) {
+        return {
+            error: `The image at ${url} was empty.`
+        };
+    }
+    if (bytes.byteLength > maxImageBytes) {
+        return {
+            error: tooLarge(bytes.byteLength)
+        };
+    }
+    const base64 = bytes.toString('base64');
+    return {
+        image: {
+            base64,
+            dataUri: `data:${mediaType};base64,${base64}`,
+            mediaType
+        }
+    };
+}
+/**
+ * Runs the provider call, retrying a transient failure.
+ *
+ * Every bundled resolver reaches its provider over `fetch`, which retries
+ * nothing by itself. Without this, a bulk generation that trips a rate limit
+ * gives up on the first 429 and leaves those images without an alt text. The
+ * resolver's `timeoutMs` covers the attempts together, so a deadline still
+ * bounds the whole call.
+ */ async function generateWithRetry({ args, generate }) {
+    for(let attempt = 0;; attempt++){
+        try {
+            return await generate(args);
+        } catch (error) {
+            const isRetryable = error instanceof VisionProviderError && error.isTransient;
+            if (!isRetryable || attempt >= MAX_RETRIES || args.signal?.aborted) {
+                throw error;
+            }
+            await new Promise((resolve)=>setTimeout(resolve, retryDelayMs(attempt + 1)));
+        }
+    }
+}
+/**
+ * Reads the model's response.
+ *
+ * Deliberately strict about a blank `altText`: the field is required on the
+ * collection, so an empty string would satisfy that requirement while telling a
+ * screen reader nothing — and nobody looks at an alt text again once it is set.
+ */ function parseResults(content, locales) {
+    const parsed = schemaForLocales(locales).safeParse(content);
+    if (!parsed.success) {
+        return null;
+    }
+    const results = {};
+    for (const locale of locales){
+        const entry = parsed.data[locale];
+        if (entry.altText.trim().length === 0) {
+            return null;
+        }
+        results[locale] = {
+            altText: entry.altText.trim(),
+            keywords: entry.keywords
+        };
+    }
+    return results;
+}
+/**
+ * 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 const createVisionResolver = ({ apiKey, generate, inlineImage = false, instructions = ({ defaultInstructions })=>defaultInstructions, key, label, maxImageBytes = 20 * 1024 * 1024, maxTokensPerLocale = 300, supportedMimeTypes, timeoutMs })=>{
+    const run = async ({ filename, imageThumbnailMimeType, imageThumbnailUrl, locales, req })=>{
+        if (!apiKey) {
+            return {
+                error: `No ${label} API key configured`,
+                success: false
+            };
+        }
+        if (locales.length === 0) {
+            return {
+                error: 'No locale requested',
+                success: false
+            };
+        }
+        const signal = timeoutMs === undefined ? undefined : AbortSignal.timeout(timeoutMs);
+        let image;
+        if (inlineImage) {
+            const downloaded = await fetchImage({
+                declaredMediaType: imageThumbnailMimeType,
+                label,
+                maxImageBytes,
+                signal,
+                supportedMimeTypes,
+                url: imageThumbnailUrl
+            });
+            if ('error' in downloaded) {
+                return {
+                    error: downloaded.error,
+                    success: false
+                };
+            }
+            image = downloaded.image;
+        }
+        try {
+            const defaultInstructions = buildDefaultInstructions({
+                locales
+            });
+            const content = await generateWithRetry({
+                args: {
+                    filename,
+                    image,
+                    imageThumbnailMimeType,
+                    imageThumbnailUrl,
+                    instructions: await instructions({
+                        defaultInstructions,
+                        filename,
+                        locales
+                    }),
+                    locales,
+                    maxTokens: maxTokensPerLocale * locales.length,
+                    req,
+                    responseSchema: z.toJSONSchema(schemaForLocales(locales), {
+                        target: 'draft-7'
+                    }),
+                    signal
+                },
+                generate
+            });
+            const results = parseResults(content, locales);
+            if (!results) {
+                return {
+                    error: `${label} did not return a usable alt text for every requested locale (${locales.join(', ')})`,
+                    success: false
+                };
+            }
+            return {
+                results,
+                success: true
+            };
+        } catch (error) {
+            req.payload.logger.error({
+                err: error,
+                msg: 'Error generating alt text',
+                // Logged separately: it is deliberately absent from the error message
+                // the admin panel shows, and is what a misconfiguration is diagnosed from.
+                providerResponse: error instanceof VisionProviderError ? error.body : undefined,
+                resolver: key
+            });
+            return {
+                error: error instanceof Error ? error.message : 'Unknown error',
+                success: false
+            };
+        }
+    };
+    return {
+        key,
+        resolve: async ({ filename, imageThumbnailMimeType, imageThumbnailUrl, locale, req })=>{
+            const result = await run({
+                filename,
+                imageThumbnailMimeType,
+                imageThumbnailUrl,
+                locales: [
+                    locale
+                ],
+                req
+            });
+            if (!result.success) {
+                return {
+                    error: result.error,
+                    success: false
+                };
+            }
+            return {
+                result: result.results[locale],
+                success: true
+            };
+        },
+        resolveBulk: async ({ filename, imageThumbnailMimeType, imageThumbnailUrl, locales, req })=>{
+            const result = await run({
+                filename,
+                imageThumbnailMimeType,
+                imageThumbnailUrl,
+                locales,
+                req
+            });
+            if (!result.success) {
+                return {
+                    error: result.error,
+                    success: false
+                };
+            }
+            return {
+                results: result.results,
+                success: true
+            };
+        },
+        supportedMimeTypes
+    };
+};
+
+//# sourceMappingURL=createVisionResolver.js.map