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

package/dist/resolvers/createVisionResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/resolvers/createVisionResolver.ts"],"sourcesContent":["import type { PayloadRequest } from 'payload'\n\nimport { z } from 'zod'\n\nimport type {\n  AltTextBulkResolverArgs,\n  AltTextBulkResolverResponse,\n  AltTextResolver,\n  AltTextResolverArgs,\n  AltTextResolverResponse,\n  AltTextResult,\n} from './types.js'\n\nexport type VisionInstructionsArgs = {\n  /** The instructions the resolver would send on its own, stating the rules the plugin depends on */\n  defaultInstructions: string\n  /** The uploaded file's name, when the endpoint could supply one */\n  filename?: string\n  /** The locales the response must cover, as configured in Payload */\n  locales: string[]\n}\n\nexport type VisionInstructions = (args: VisionInstructionsArgs) => Promise<string> | string\n\n/** The thumbnail's bytes, handed to providers that declared `inlineImage`. */\nexport type VisionImage = {\n  /** Base64-encoded bytes, without a data URI prefix */\n  base64: string\n  /** `data:<mediaType>;base64,<base64>`, for providers that take a data URI */\n  dataUri: string\n  /** The format actually served at the thumbnail URL, not the document's stored one */\n  mediaType: string\n}\n\nexport type VisionGenerateArgs = {\n  /** The uploaded file's name, when the endpoint could supply one */\n  filename?: string\n  /** The downloaded thumbnail — present only when the resolver declared `inlineImage` */\n  image?: VisionImage\n  /**\n   * The format the collection declares `getImageThumbnail` delivers, or\n   * undefined when nothing was declared. Resolvers that inline the bytes should\n   * use `image.mediaType`, which is what the URL actually served, with this\n   * declaration already standing in when the host named no usable type.\n   */\n  imageThumbnailMimeType?: string\n  /** URL of the image thumbnail, for providers that fetch it themselves */\n  imageThumbnailUrl: string\n  /** The instructions to send, e.g. as the system prompt */\n  instructions: string\n  /** The locales the response must cover */\n  locales: string[]\n  /** Token budget for the response, scaled by the number of requested locales */\n  maxTokens: number\n  req: PayloadRequest\n  /** Draft-7 JSON Schema of the object the provider must return */\n  responseSchema: Record<string, unknown>\n  /**\n   * Aborts once `timeoutMs` has elapsed, already covering the image download.\n   * Undefined when the resolver declares no `timeoutMs`, leaving the deadline to\n   * the provider client.\n   */\n  signal?: AbortSignal\n}\n\n/**\n * A non-ok HTTP response from a provider.\n *\n * Carries the status so the factory can tell a rate limit or an outage — worth\n * another attempt — from a malformed request, which would fail identically every\n * time.\n *\n * The response body is kept off `message` deliberately. That message is shown in\n * the admin panel to anyone allowed to generate an alt text, while the body is\n * text the provider chose: OpenAI echoes a masked form of the rejected API key\n * into a 401, and providers routinely name organization ids, project ids and\n * internal endpoints. It goes to the server log, where the person debugging the\n * configuration is, and not to an editor's screen.\n */\nexport class VisionProviderError extends Error {\n  /** The provider's response body, for the log only — never for `message`. */\n  readonly body?: string\n  readonly status: number\n\n  constructor({ body, label, status }: { body?: string; label: string; status: number }) {\n    super(`${label} responded with status ${status}`)\n    this.body = body\n    this.name = 'VisionProviderError'\n    this.status = status\n  }\n\n  /** Rate limits and server-side failures are transient; a 4xx is not. */\n  get isTransient(): boolean {\n    return this.status === 429 || this.status >= 500\n  }\n}\n\n/** Attempts after the first, for a provider error that may pass on a retry. */\nconst MAX_RETRIES = 2\n\n/** Backs off between attempts, bounded by the resolver's own deadline. */\nconst retryDelayMs = (attempt: number) => 250 * 2 ** (attempt - 1)\n\nexport type VisionResolverConfig = {\n  /**\n   * Checked before any work happens, so a plugin wired as\n   * `enabled: !!process.env.X_API_KEY` fails with a readable message instead of\n   * a provider error — or, worse, a paid-for image download.\n   */\n  apiKey: string\n  /**\n   * Sends one request to the provider and resolves with its parsed JSON\n   * response. Rejecting fails the generation, so provider errors need no\n   * special handling beyond throwing a readable message.\n   */\n  generate: (args: VisionGenerateArgs) => Promise<unknown>\n  /**\n   * Download the thumbnail and hand `generate` the bytes rather than the URL.\n   *\n   * Needed by every provider whose own fetcher requires a publicly reachable\n   * file.\n   */\n  inlineImage?: boolean\n  /**\n   * Builds the instructions from the default ones, e.g. to append a house style\n   * rule. Called once per generation. The image and the required response shape\n   * are not part of the instructions and cannot be altered here.\n   *\n   * @default ({ defaultInstructions }) => defaultInstructions\n   */\n  instructions?: VisionInstructions\n  /** Identifies the resolver, e.g. in log entries */\n  key: string\n  /** Provider name used in error messages shown in the admin UI */\n  label: string\n  /**\n   * Rejects an inlined image above this size before it is sent.\n   * @default 20971520 (20 MB)\n   */\n  maxImageBytes?: number\n  /**\n   * Token budget granted per requested locale. A ceiling, not a reservation, so\n   * headroom is free; the default keeps the pre-factory bulk budget of 300 for\n   * every locale count rather than only for two or more.\n   * @default 300\n   */\n  maxTokensPerLocale?: number\n  /** @see AltTextResolver.supportedMimeTypes */\n  supportedMimeTypes?: string[]\n  /**\n   * Abort after this many milliseconds, covering the image download and the\n   * provider call together. Omit it to impose no deadline of the factory's own —\n   * appropriate when the provider's own client already has one.\n   */\n  timeoutMs?: number\n}\n\nconst altTextSchema = z.object({\n  altText: z.string().describe('A concise, descriptive alt text for the image'),\n  keywords: z.array(z.string()).describe('Keywords that describe the content of the image'),\n})\n\n/** One schema entry per requested locale, so the model must answer for all of them. */\nexport const schemaForLocales = (locales: string[]) =>\n  z.object(Object.fromEntries(locales.map((locale) => [locale, altTextSchema])))\n\n/**\n * Rules dictated by the plugin rather than by the provider: one entry per\n * configured locale, describing what is visible rather than guessing at it.\n */\nconst buildDefaultInstructions = ({ locales }: { locales: string[] }): string =>\n  [\n    `You are an expert at analyzing images and creating descriptive image alt text.`,\n\n    `Please analyze the given image and provide the following in ${locales.join(', ')}:`,\n\n    `- 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.`,\n\n    `- A localized list of keywords that describe the content (e.g., [\"Camel\", \"Palm trees\", \"Desert\"]) as \"keywords\"`,\n\n    `If a context is provided, use it to enhance the alt text.`,\n\n    `Format your response as a JSON object with ${locales.map((locale) => `\"${locale}\"`).join(', ')} keys, each containing \"altText\" and \"keywords\".`,\n  ].join('\\n\\n')\n\n/**\n * Downloads the image and returns its bytes.\n *\n * The document's mime type is checked by the endpoint before the resolver runs,\n * but `getImageThumbnail` may point at a derivative in a different format, so\n * what was actually served is what counts. Only when the host names no usable\n * type at all — no header, or a generic `application/octet-stream` as private\n * buckets and signed URLs often send — does the collection's declared\n * `imageThumbnailMimeType` stand in for it.\n */\nasync function fetchImage({\n  declaredMediaType,\n  label,\n  maxImageBytes,\n  signal,\n  supportedMimeTypes,\n  url,\n}: {\n  declaredMediaType?: string\n  label: string\n  maxImageBytes: number\n  signal?: AbortSignal\n  supportedMimeTypes?: string[]\n  url: string\n}): Promise<{ error: string } | { image: VisionImage }> {\n  let response: Response\n\n  try {\n    response = await fetch(url, { signal })\n  } catch (error) {\n    return {\n      error: `Could not download the image from ${url}: ${error instanceof Error ? error.message : 'unknown error'}`,\n    }\n  }\n\n  if (!response.ok) {\n    return { error: `Could not download the image from ${url}: status ${response.status}` }\n  }\n\n  const served = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase()\n  const mediaType =\n    served && served !== 'application/octet-stream' ? served : declaredMediaType?.toLowerCase()\n\n  if (!mediaType) {\n    return {\n      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.`,\n    }\n  }\n\n  if (supportedMimeTypes && !supportedMimeTypes.includes(mediaType)) {\n    return {\n      error: `The image at ${url} was served as \"${mediaType}\", which ${label} cannot read. Supported types: ${supportedMimeTypes.join(', ')}.`,\n    }\n  }\n\n  const tooLarge = (byteLength: number) =>\n    `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.`\n\n  // Measuring by reading is work the header already answers, and the file is on\n  // its way to being rejected: `getImageThumbnail` may point at the original\n  // upload, which can be far above the provider's limit.\n  const declaredLength = Number(response.headers.get('content-length'))\n\n  if (Number.isInteger(declaredLength) && declaredLength > maxImageBytes) {\n    return { error: tooLarge(declaredLength) }\n  }\n\n  const bytes = Buffer.from(await response.arrayBuffer())\n\n  if (bytes.byteLength === 0) {\n    return { error: `The image at ${url} was empty.` }\n  }\n\n  if (bytes.byteLength > maxImageBytes) {\n    return { error: tooLarge(bytes.byteLength) }\n  }\n\n  const base64 = bytes.toString('base64')\n\n  return { image: { base64, dataUri: `data:${mediaType};base64,${base64}`, mediaType } }\n}\n\n/**\n * Runs the provider call, retrying a transient failure.\n *\n * Every bundled resolver reaches its provider over `fetch`, which retries\n * nothing by itself. Without this, a bulk generation that trips a rate limit\n * gives up on the first 429 and leaves those images without an alt text. The\n * resolver's `timeoutMs` covers the attempts together, so a deadline still\n * bounds the whole call.\n */\nasync function generateWithRetry({\n  args,\n  generate,\n}: {\n  args: VisionGenerateArgs\n  generate: (args: VisionGenerateArgs) => Promise<unknown>\n}): Promise<unknown> {\n  for (let attempt = 0; ; attempt++) {\n    try {\n      return await generate(args)\n    } catch (error) {\n      const isRetryable = error instanceof VisionProviderError && error.isTransient\n\n      if (!isRetryable || attempt >= MAX_RETRIES || args.signal?.aborted) {\n        throw error\n      }\n\n      await new Promise((resolve) => setTimeout(resolve, retryDelayMs(attempt + 1)))\n    }\n  }\n}\n\n/**\n * Reads the model's response.\n *\n * Deliberately strict about a blank `altText`: the field is required on the\n * collection, so an empty string would satisfy that requirement while telling a\n * screen reader nothing — and nobody looks at an alt text again once it is set.\n */\nfunction parseResults(content: unknown, locales: string[]): null | Record<string, AltTextResult> {\n  const parsed = schemaForLocales(locales).safeParse(content)\n\n  if (!parsed.success) {\n    return null\n  }\n\n  const results: Record<string, AltTextResult> = {}\n\n  for (const locale of locales) {\n    const entry = parsed.data[locale]\n\n    if (entry.altText.trim().length === 0) {\n      return null\n    }\n\n    results[locale] = { altText: entry.altText.trim(), keywords: entry.keywords }\n  }\n\n  return results\n}\n\n/**\n * Creates a resolver for a vision (LLM) provider, leaving only the provider call\n * to `generate`: the prompt, the required response schema, the optional image\n * download and the strict reading of the response are handled here.\n *\n * All locales go into a single call rather than one call each: the image is\n * uploaded and analyzed once — the expensive part — and every language ends up\n * describing the same reading of it. `resolve` is that same call with one\n * locale.\n */\nexport const createVisionResolver = ({\n  apiKey,\n  generate,\n  inlineImage = false,\n  instructions = ({ defaultInstructions }) => defaultInstructions,\n  key,\n  label,\n  maxImageBytes = 20 * 1024 * 1024,\n  maxTokensPerLocale = 300,\n  supportedMimeTypes,\n  timeoutMs,\n}: VisionResolverConfig): AltTextResolver => {\n  const run = async ({\n    filename,\n    imageThumbnailMimeType,\n    imageThumbnailUrl,\n    locales,\n    req,\n  }: {\n    filename?: string\n    imageThumbnailMimeType?: string\n    imageThumbnailUrl: string\n    locales: string[]\n    req: PayloadRequest\n  }): Promise<\n    { error: string; success: false } | { results: Record<string, AltTextResult>; success: true }\n  > => {\n    if (!apiKey) {\n      return { error: `No ${label} API key configured`, success: false }\n    }\n\n    if (locales.length === 0) {\n      return { error: 'No locale requested', success: false }\n    }\n\n    const signal = timeoutMs === undefined ? undefined : AbortSignal.timeout(timeoutMs)\n\n    let image: undefined | VisionImage\n\n    if (inlineImage) {\n      const downloaded = await fetchImage({\n        declaredMediaType: imageThumbnailMimeType,\n        label,\n        maxImageBytes,\n        signal,\n        supportedMimeTypes,\n        url: imageThumbnailUrl,\n      })\n\n      if ('error' in downloaded) {\n        return { error: downloaded.error, success: false }\n      }\n\n      image = downloaded.image\n    }\n\n    try {\n      const defaultInstructions = buildDefaultInstructions({ locales })\n\n      const content = await generateWithRetry({\n        args: {\n          filename,\n          image,\n          imageThumbnailMimeType,\n          imageThumbnailUrl,\n          instructions: await instructions({ defaultInstructions, filename, locales }),\n          locales,\n          maxTokens: maxTokensPerLocale * locales.length,\n          req,\n          responseSchema: z.toJSONSchema(schemaForLocales(locales), { target: 'draft-7' }),\n          signal,\n        },\n        generate,\n      })\n\n      const results = parseResults(content, locales)\n\n      if (!results) {\n        return {\n          error: `${label} did not return a usable alt text for every requested locale (${locales.join(', ')})`,\n          success: false,\n        }\n      }\n\n      return { results, success: true }\n    } catch (error) {\n      req.payload.logger.error({\n        err: error,\n        msg: 'Error generating alt text',\n        // Logged separately: it is deliberately absent from the error message\n        // the admin panel shows, and is what a misconfiguration is diagnosed from.\n        providerResponse: error instanceof VisionProviderError ? error.body : undefined,\n        resolver: key,\n      })\n\n      return { error: error instanceof Error ? error.message : 'Unknown error', success: false }\n    }\n  }\n\n  return {\n    key,\n    resolve: async ({\n      filename,\n      imageThumbnailMimeType,\n      imageThumbnailUrl,\n      locale,\n      req,\n    }: AltTextResolverArgs): Promise<AltTextResolverResponse> => {\n      const result = await run({\n        filename,\n        imageThumbnailMimeType,\n        imageThumbnailUrl,\n        locales: [locale],\n        req,\n      })\n\n      if (!result.success) {\n        return { error: result.error, success: false }\n      }\n\n      return { result: result.results[locale], success: true }\n    },\n    resolveBulk: async ({\n      filename,\n      imageThumbnailMimeType,\n      imageThumbnailUrl,\n      locales,\n      req,\n    }: AltTextBulkResolverArgs): Promise<AltTextBulkResolverResponse> => {\n      const result = await run({\n        filename,\n        imageThumbnailMimeType,\n        imageThumbnailUrl,\n        locales,\n        req,\n      })\n\n      if (!result.success) {\n        return { error: result.error, success: false }\n      }\n\n      return { results: result.results, success: true }\n    },\n    supportedMimeTypes,\n  }\n}\n"],"names":["z","VisionProviderError","Error","body","status","label","name","isTransient","MAX_RETRIES","retryDelayMs","attempt","altTextSchema","object","altText","string","describe","keywords","array","schemaForLocales","locales","Object","fromEntries","map","locale","buildDefaultInstructions","join","fetchImage","declaredMediaType","maxImageBytes","signal","supportedMimeTypes","url","response","fetch","error","message","ok","served","headers","get","split","trim","toLowerCase","mediaType","includes","tooLarge","byteLength","Math","round","declaredLength","Number","isInteger","bytes","Buffer","from","arrayBuffer","base64","toString","image","dataUri","generateWithRetry","args","generate","isRetryable","aborted","Promise","resolve","setTimeout","parseResults","content","parsed","safeParse","success","results","entry","data","length","createVisionResolver","apiKey","inlineImage","instructions","defaultInstructions","key","maxTokensPerLocale","timeoutMs","run","filename","imageThumbnailMimeType","imageThumbnailUrl","req","undefined","AbortSignal","timeout","downloaded","maxTokens","responseSchema","toJSONSchema","target","payload","logger","err","msg","providerResponse","resolver","result","resolveBulk"],"mappings":"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"}

package/dist/resolvers/mistral.d.ts

@@ -1,3 +1,4 @@
+import type { VisionInstructions } from './createVisionResolver.js';
 import type { AltTextResolver } from './types.js';
 export type MistralResolverConfig = {
     /** Mistral API key for authentication */
@@ -7,6 +8,13 @@ export type MistralResolverConfig = {
      * @default 'https://api.mistral.ai/v1'
      */
     baseUrl?: string;
+    /**
+     * Builds the instructions from the default ones, e.g. to append a house style
+     * rule. Sent as the system message, separately from the image.
+     *
+     * @default ({ defaultInstructions }) => defaultInstructions
+     */
+    instructions?: VisionInstructions;
     /**
      * The vision-capable Mistral model to use for alt text generation.
      *
@@ -27,6 +35,12 @@ export type MistralResolverConfig = {
 /**
  * Creates a Mistral-based resolver for alt text generation.
  *
+ * The image is downloaded and sent as bytes rather than handed to Mistral as a
+ * URL. Mistral's own fetcher requires a publicly reachable file, and even that is
+ * not sufficient: hosts serving the image fine to everyone else were observed
+ * refusing it with `File could not be fetched from url` (error 3310). See #184
+ * for the reproduction.
+ *
  * @example
  * ```typescript
  * import { mistralResolver } from '@jhb.software/payload-alt-text-plugin'
@@ -37,4 +51,4 @@ export type MistralResolverConfig = {
  * })
  * ```
  */
-export declare const mistralResolver: (config: MistralResolverConfig) => AltTextResolver;
+export declare const mistralResolver: ({ apiKey, baseUrl, instructions, model, timeoutMs, }: MistralResolverConfig) => AltTextResolver;

package/dist/resolvers/mistral.js

@@ -1,220 +1,27 @@
-import { z } from 'zod';
+import { createVisionResolver, VisionProviderError } from './createVisionResolver.js';
 /**
  * Image formats the Mistral 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://docs.mistral.ai/capabilities/vision/
  */ const SUPPORTED_MIME_TYPES = [
     'image/jpeg',
     'image/png',
     'image/gif',
     'image/webp'
 ];
-/** Mistral rejects images above 20 MB. */ const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
-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. */ const schemaForLocales = (locales)=>z.object(Object.fromEntries(locales.map((locale)=>[
-            locale,
-            altTextSchema
-        ])));
-/**
- * Downloads the image and returns it as a data URI.
- *
- * Mistral 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 — and some hosts
- * refuse Mistral's fetcher outright, which surfaces as `File could not be
- * fetched from url` (error 3310). Sending the bytes removes that whole class of
- * failure for the price of one extra download.
- */ async function fetchImageAsDataUri(url, signal) {
-    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}`
-        };
-    }
-    // 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 trust what was actually served.
-    const contentType = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase();
-    if (!contentType || !SUPPORTED_MIME_TYPES.includes(contentType)) {
-        return {
-            error: `The image at ${url} was served as "${contentType ?? 'an unknown type'}", which Mistral cannot read. Supported types: ${SUPPORTED_MIME_TYPES.join(', ')}.`
-        };
-    }
-    const bytes = Buffer.from(await response.arrayBuffer());
-    if (bytes.byteLength === 0) {
-        return {
-            error: `The image at ${url} was empty.`
-        };
-    }
-    if (bytes.byteLength > MAX_IMAGE_BYTES) {
-        return {
-            error: `The image at ${url} is ${Math.round(bytes.byteLength / 1024 / 1024)} MB, above Mistral's 20 MB limit. Point getImageThumbnail at a smaller image size.`
-        };
-    }
-    return {
-        dataUri: `data:${contentType};base64,${bytes.toString('base64')}`
-    };
-}
-function buildPrompt(locales) {
-    const languages = locales.join(', ');
-    return `
-      You are an expert at analyzing images and creating descriptive image alt text.
-
-      Please analyze the given image and provide the following in ${languages}:
-      - A concise, 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 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".
-    `;
-}
-/**
- * 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;
-}
-/**
- * One request, one or more locales.
- *
- * 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.
- */ async function generate({ apiKey, baseUrl, filename, imageThumbnailUrl, locales, model, timeoutMs }) {
-    if (!apiKey) {
-        return {
-            error: 'No Mistral API key configured',
-            success: false
-        };
-    }
-    if (locales.length === 0) {
-        return {
-            error: 'No locale requested',
-            success: false
-        };
-    }
-    const signal = AbortSignal.timeout(timeoutMs);
-    const image = await fetchImageAsDataUri(imageThumbnailUrl, signal);
-    if ('error' in image) {
-        return {
-            error: image.error,
-            success: false
-        };
-    }
-    try {
-        const response = await fetch(`${baseUrl}/chat/completions`, {
-            body: JSON.stringify({
-                max_tokens: 150 * locales.length,
-                messages: [
-                    {
-                        content: buildPrompt(locales),
-                        role: 'system'
-                    },
-                    {
-                        content: [
-                            {
-                                type: 'image_url',
-                                image_url: image.dataUri
-                            },
-                            ...filename ? [
-                                {
-                                    type: 'text',
-                                    text: filename
-                                }
-                            ] : []
-                        ],
-                        role: 'user'
-                    }
-                ],
-                model,
-                response_format: {
-                    type: 'json_schema',
-                    json_schema: {
-                        name: 'data',
-                        schema: z.toJSONSchema(schemaForLocales(locales), {
-                            target: 'draft-7'
-                        }),
-                        strict: true
-                    }
-                }
-            }),
-            headers: {
-                Authorization: `Bearer ${apiKey}`,
-                'Content-Type': 'application/json'
-            },
-            method: 'POST',
-            signal
-        });
-        if (!response.ok) {
-            const body = await response.text().catch(()=>'');
-            return {
-                error: `Mistral responded with status ${response.status}${body ? `: ${body}` : ''}`,
-                success: false
-            };
-        }
-        const completion = await response.json();
-        const content = completion.choices?.[0]?.message?.content;
-        if (typeof content !== 'string') {
-            return {
-                error: 'No result from Mistral',
-                success: false
-            };
-        }
-        const results = parseResults(JSON.parse(content), locales);
-        if (!results) {
-            return {
-                error: `Mistral did not return a usable alt text for every requested locale (${locales.join(', ')})`,
-                success: false
-            };
-        }
-        return {
-            results,
-            success: true
-        };
-    } catch (error) {
-        console.error('Error generating alt text:', error);
-        return {
-            error: error instanceof Error ? error.message : 'Unknown error',
-            success: false
-        };
-    }
-}
 /**
  * Creates a Mistral-based resolver for alt text generation.
  *
+ * The image is downloaded and sent as bytes rather than handed to Mistral as a
+ * URL. Mistral's own fetcher requires a publicly reachable file, and even that is
+ * not sufficient: hosts serving the image fine to everyone else were observed
+ * refusing it with `File could not be fetched from url` (error 3310). See #184
+ * for the reproduction.
+ *
  * @example
  * ```typescript
  * import { mistralResolver } from '@jhb.software/payload-alt-text-plugin'
@@ -224,57 +31,85 @@ function buildPrompt(locales) {
  *   model: 'mistral-medium-latest', // optional, this is the default
  * })
  * ```
- */ export const mistralResolver = (config)=>{
-    const { apiKey, baseUrl = 'https://api.mistral.ai/v1', model = 'mistral-medium-latest', timeoutMs = 30_000 } = config;
-    return {
-        key: 'mistral',
-        resolve: async ({ filename, imageThumbnailUrl, locale })=>{
-            const result = await generate({
-                apiKey,
-                baseUrl,
-                filename,
-                imageThumbnailUrl,
-                locales: [
-                    locale
-                ],
-                model,
-                timeoutMs
-            });
-            if (!result.success) {
-                return {
-                    error: result.error,
-                    success: false
-                };
+ */ export const mistralResolver = ({ apiKey, baseUrl = 'https://api.mistral.ai/v1', instructions, model = 'mistral-medium-latest', timeoutMs = 30_000 })=>createVisionResolver({
+        apiKey,
+        generate: async ({ filename, image, instructions: resolvedInstructions, maxTokens, responseSchema, signal })=>{
+            if (!image) {
+                throw new Error('The image was not downloaded');
             }
-            return {
-                result: result.results[locale],
-                success: true
-            };
-        },
-        resolveBulk: async ({ filename, imageThumbnailUrl, locales })=>{
-            const result = await generate({
-                apiKey,
-                baseUrl,
-                filename,
-                imageThumbnailUrl,
-                locales,
-                model,
-                timeoutMs
+            const response = await fetch(`${baseUrl}/chat/completions`, {
+                body: JSON.stringify({
+                    max_tokens: maxTokens,
+                    messages: [
+                        {
+                            content: resolvedInstructions,
+                            role: 'system'
+                        },
+                        {
+                            content: [
+                                {
+                                    type: 'image_url',
+                                    image_url: image.dataUri
+                                },
+                                ...filename ? [
+                                    {
+                                        type: 'text',
+                                        text: filename
+                                    }
+                                ] : []
+                            ],
+                            role: 'user'
+                        }
+                    ],
+                    model,
+                    response_format: {
+                        type: 'json_schema',
+                        json_schema: {
+                            name: 'data',
+                            schema: responseSchema,
+                            strict: true
+                        }
+                    }
+                }),
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json'
+                },
+                method: 'POST',
+                signal
             });
-            if (!result.success) {
-                return {
-                    error: result.error,
-                    success: false
-                };
+            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: 'Mistral',
+                    status: response.status
+                });
+            }
+            const completion = await response.json();
+            const choice = completion.choices?.[0];
+            if (choice?.finish_reason === 'length') {
+                throw new Error(`Mistral ran out of tokens before finishing the alt text (max_tokens: ${maxTokens})`);
+            }
+            const content = choice?.message?.content;
+            if (typeof content !== 'string') {
+                throw new Error('No result from Mistral');
+            }
+            try {
+                return JSON.parse(content);
+            } catch  {
+                throw new Error('Mistral returned a response that was not valid JSON');
             }
-            return {
-                results: result.results,
-                success: true
-            };
         },
-        // https://docs.mistral.ai/capabilities/vision/
-        supportedMimeTypes: SUPPORTED_MIME_TYPES
-    };
-};
+        inlineImage: true,
+        instructions,
+        key: 'mistral',
+        label: 'Mistral',
+        // Mistral rejects images above 20 MB.
+        maxImageBytes: 20 * 1024 * 1024,
+        supportedMimeTypes: SUPPORTED_MIME_TYPES,
+        timeoutMs
+    });
 
 //# sourceMappingURL=mistral.js.map

package/dist/resolvers/mistral.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/resolvers/mistral.ts"],"sourcesContent":["import { z } from 'zod'\n\nimport type {\n  AltTextBulkResolverArgs,\n  AltTextBulkResolverResponse,\n  AltTextResolver,\n  AltTextResolverArgs,\n  AltTextResolverResponse,\n  AltTextResult,\n} from './types.js'\n\nexport type MistralResolverConfig = {\n  /** Mistral API key for authentication */\n  apiKey: string\n  /**\n   * Base URL of the Mistral API.\n   * @default 'https://api.mistral.ai/v1'\n   */\n  baseUrl?: string\n  /**\n   * The vision-capable Mistral model to use for alt text generation.\n   *\n   * Must be able to read images — `mistral-medium-latest`,\n   * `mistral-large-latest`, `mistral-small-latest` and the `ministral-*` models\n   * all are.\n   *\n   * @default 'mistral-medium-latest'\n   */\n  model?: string\n  /**\n   * Abort after this many milliseconds. Covers downloading the image and the\n   * completion call together.\n   * @default 30000\n   */\n  timeoutMs?: number\n}\n\n/**\n * Image formats the Mistral 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 */\nconst SUPPORTED_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n\n/** Mistral rejects images above 20 MB. */\nconst MAX_IMAGE_BYTES = 20 * 1024 * 1024\n\nconst altTextSchema = z.object({\n  altText: z.string().describe('A concise, descriptive alt text for the image'),\n  keywords: z.array(z.string()).describe('Keywords that describe the content of the image'),\n})\n\n/** One schema entry per requested locale, so the model must answer for all of them. */\nconst schemaForLocales = (locales: string[]) =>\n  z.object(Object.fromEntries(locales.map((locale) => [locale, altTextSchema])))\n\n/**\n * Downloads the image and returns it as a data URI.\n *\n * Mistral can fetch an image URL itself, but that path is not dependable for a\n * CMS. It requires the file to be reachable from the public internet — never\n * true in local development, and not true for private buckets — and some hosts\n * refuse Mistral's fetcher outright, which surfaces as `File could not be\n * fetched from url` (error 3310). Sending the bytes removes that whole class of\n * failure for the price of one extra download.\n */\nasync function fetchImageAsDataUri(\n  url: string,\n  signal: AbortSignal,\n): Promise<{ dataUri: string } | { error: string }> {\n  let response: Response\n\n  try {\n    response = await fetch(url, { signal })\n  } catch (error) {\n    return {\n      error: `Could not download the image from ${url}: ${error instanceof Error ? error.message : 'unknown error'}`,\n    }\n  }\n\n  if (!response.ok) {\n    return { error: `Could not download the image from ${url}: status ${response.status}` }\n  }\n\n  // The document's mime type is checked by the endpoint before the resolver\n  // runs, but `getImageThumbnail` may point at a derivative in a different\n  // format, so trust what was actually served.\n  const contentType = response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase()\n\n  if (!contentType || !SUPPORTED_MIME_TYPES.includes(contentType)) {\n    return {\n      error: `The image at ${url} was served as \"${contentType ?? 'an unknown type'}\", which Mistral cannot read. Supported types: ${SUPPORTED_MIME_TYPES.join(', ')}.`,\n    }\n  }\n\n  const bytes = Buffer.from(await response.arrayBuffer())\n\n  if (bytes.byteLength === 0) {\n    return { error: `The image at ${url} was empty.` }\n  }\n\n  if (bytes.byteLength > MAX_IMAGE_BYTES) {\n    return {\n      error: `The image at ${url} is ${Math.round(bytes.byteLength / 1024 / 1024)} MB, above Mistral's 20 MB limit. Point getImageThumbnail at a smaller image size.`,\n    }\n  }\n\n  return { dataUri: `data:${contentType};base64,${bytes.toString('base64')}` }\n}\n\nfunction buildPrompt(locales: string[]): string {\n  const languages = locales.join(', ')\n\n  return `\n      You are an expert at analyzing images and creating descriptive image alt text.\n\n      Please analyze the given image and provide the following in ${languages}:\n      - A concise, 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.\n      - A list of keywords that describe the content (e.g., [\"Camel\", \"Palm trees\", \"Desert\"]) as \"keywords\"\n\n      If a context is provided, use it to enhance the alt text.\n\n      Format your response as a JSON object with ${locales.map((locale) => `\"${locale}\"`).join(', ')} keys, each containing \"altText\" and \"keywords\".\n    `\n}\n\n/**\n * Reads the model's response.\n *\n * Deliberately strict about a blank `altText`: the field is required on the\n * collection, so an empty string would satisfy that requirement while telling a\n * screen reader nothing — and nobody looks at an alt text again once it is set.\n */\nfunction parseResults(content: unknown, locales: string[]): null | Record<string, AltTextResult> {\n  const parsed = schemaForLocales(locales).safeParse(content)\n\n  if (!parsed.success) {\n    return null\n  }\n\n  const results: Record<string, AltTextResult> = {}\n\n  for (const locale of locales) {\n    const entry = parsed.data[locale]\n\n    if (entry.altText.trim().length === 0) {\n      return null\n    }\n\n    results[locale] = { altText: entry.altText.trim(), keywords: entry.keywords }\n  }\n\n  return results\n}\n\n/**\n * One request, one or more locales.\n *\n * All locales go into a single call rather than one call each: the image is\n * uploaded and analyzed once — the expensive part — and every language ends up\n * describing the same reading of it.\n */\nasync function generate({\n  apiKey,\n  baseUrl,\n  filename,\n  imageThumbnailUrl,\n  locales,\n  model,\n  timeoutMs,\n}: {\n  apiKey: string\n  baseUrl: string\n  filename?: string\n  imageThumbnailUrl: string\n  locales: string[]\n  model: string\n  timeoutMs: number\n}): Promise<\n  { error: string; success: false } | { results: Record<string, AltTextResult>; success: true }\n> {\n  if (!apiKey) {\n    return { error: 'No Mistral API key configured', success: false }\n  }\n\n  if (locales.length === 0) {\n    return { error: 'No locale requested', success: false }\n  }\n\n  const signal = AbortSignal.timeout(timeoutMs)\n  const image = await fetchImageAsDataUri(imageThumbnailUrl, signal)\n\n  if ('error' in image) {\n    return { error: image.error, success: false }\n  }\n\n  try {\n    const response = await fetch(`${baseUrl}/chat/completions`, {\n      body: JSON.stringify({\n        max_tokens: 150 * locales.length,\n        messages: [\n          { content: buildPrompt(locales), role: 'system' },\n          {\n            content: [\n              { type: 'image_url', image_url: image.dataUri },\n              ...(filename ? [{ type: 'text', text: filename }] : []),\n            ],\n            role: 'user',\n          },\n        ],\n        model,\n        response_format: {\n          type: 'json_schema',\n          json_schema: {\n            name: 'data',\n            schema: z.toJSONSchema(schemaForLocales(locales), { target: 'draft-7' }),\n            strict: true,\n          },\n        },\n      }),\n      headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },\n      method: 'POST',\n      signal,\n    })\n\n    if (!response.ok) {\n      const body = await response.text().catch(() => '')\n\n      return {\n        error: `Mistral responded with status ${response.status}${body ? `: ${body}` : ''}`,\n        success: false,\n      }\n    }\n\n    const completion = (await response.json()) as {\n      choices?: { message?: { content?: unknown } }[]\n    }\n    const content = completion.choices?.[0]?.message?.content\n\n    if (typeof content !== 'string') {\n      return { error: 'No result from Mistral', success: false }\n    }\n\n    const results = parseResults(JSON.parse(content), locales)\n\n    if (!results) {\n      return {\n        error: `Mistral did not return a usable alt text for every requested locale (${locales.join(', ')})`,\n        success: false,\n      }\n    }\n\n    return { results, success: true }\n  } catch (error) {\n    console.error('Error generating alt text:', error)\n\n    return { error: error instanceof Error ? error.message : 'Unknown error', success: false }\n  }\n}\n\n/**\n * Creates a Mistral-based resolver for alt text generation.\n *\n * @example\n * ```typescript\n * import { mistralResolver } from '@jhb.software/payload-alt-text-plugin'\n *\n * mistralResolver({\n *   apiKey: process.env.MISTRAL_API_KEY,\n *   model: 'mistral-medium-latest', // optional, this is the default\n * })\n * ```\n */\nexport const mistralResolver = (config: MistralResolverConfig): AltTextResolver => {\n  const {\n    apiKey,\n    baseUrl = 'https://api.mistral.ai/v1',\n    model = 'mistral-medium-latest',\n    timeoutMs = 30_000,\n  } = config\n\n  return {\n    key: 'mistral',\n    resolve: async ({\n      filename,\n      imageThumbnailUrl,\n      locale,\n    }: AltTextResolverArgs): Promise<AltTextResolverResponse> => {\n      const result = await generate({\n        apiKey,\n        baseUrl,\n        filename,\n        imageThumbnailUrl,\n        locales: [locale],\n        model,\n        timeoutMs,\n      })\n\n      if (!result.success) {\n        return { error: result.error, success: false }\n      }\n\n      return { result: result.results[locale], success: true }\n    },\n    resolveBulk: async ({\n      filename,\n      imageThumbnailUrl,\n      locales,\n    }: AltTextBulkResolverArgs): Promise<AltTextBulkResolverResponse> => {\n      const result = await generate({\n        apiKey,\n        baseUrl,\n        filename,\n        imageThumbnailUrl,\n        locales,\n        model,\n        timeoutMs,\n      })\n\n      if (!result.success) {\n        return { error: result.error, success: false }\n      }\n\n      return { results: result.results, success: true }\n    },\n    // https://docs.mistral.ai/capabilities/vision/\n    supportedMimeTypes: SUPPORTED_MIME_TYPES,\n  }\n}\n"],"names":["z","SUPPORTED_MIME_TYPES","MAX_IMAGE_BYTES","altTextSchema","object","altText","string","describe","keywords","array","schemaForLocales","locales","Object","fromEntries","map","locale","fetchImageAsDataUri","url","signal","response","fetch","error","Error","message","ok","status","contentType","headers","get","split","trim","toLowerCase","includes","join","bytes","Buffer","from","arrayBuffer","byteLength","Math","round","dataUri","toString","buildPrompt","languages","parseResults","content","parsed","safeParse","success","results","entry","data","length","generate","apiKey","baseUrl","filename","imageThumbnailUrl","model","timeoutMs","AbortSignal","timeout","image","body","JSON","stringify","max_tokens","messages","role","type","image_url","text","response_format","json_schema","name","schema","toJSONSchema","target","strict","Authorization","method","catch","completion","json","choices","parse","console","mistralResolver","config","key","resolve","result","resolveBulk","supportedMimeTypes"],"mappings":"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"}
+{"version":3,"sources":["../../src/resolvers/mistral.ts"],"sourcesContent":["import type { VisionInstructions } from './createVisionResolver.js'\nimport type { AltTextResolver } from './types.js'\n\nimport { createVisionResolver, VisionProviderError } from './createVisionResolver.js'\n\nexport type MistralResolverConfig = {\n  /** Mistral API key for authentication */\n  apiKey: string\n  /**\n   * Base URL of the Mistral API.\n   * @default 'https://api.mistral.ai/v1'\n   */\n  baseUrl?: string\n  /**\n   * Builds the instructions from the default ones, e.g. to append a house style\n   * rule. Sent as the system message, separately from the image.\n   *\n   * @default ({ defaultInstructions }) => defaultInstructions\n   */\n  instructions?: VisionInstructions\n  /**\n   * The vision-capable Mistral model to use for alt text generation.\n   *\n   * Must be able to read images — `mistral-medium-latest`,\n   * `mistral-large-latest`, `mistral-small-latest` and the `ministral-*` models\n   * all are.\n   *\n   * @default 'mistral-medium-latest'\n   */\n  model?: string\n  /**\n   * Abort after this many milliseconds. Covers downloading the image and the\n   * completion call together.\n   * @default 30000\n   */\n  timeoutMs?: number\n}\n\n/**\n * Image formats the Mistral 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://docs.mistral.ai/capabilities/vision/\n */\nconst SUPPORTED_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n\n/**\n * Creates a Mistral-based resolver for alt text generation.\n *\n * The image is downloaded and sent as bytes rather than handed to Mistral as a\n * URL. Mistral's own fetcher requires a publicly reachable file, and even that is\n * not sufficient: hosts serving the image fine to everyone else were observed\n * refusing it with `File could not be fetched from url` (error 3310). See #184\n * for the reproduction.\n *\n * @example\n * ```typescript\n * import { mistralResolver } from '@jhb.software/payload-alt-text-plugin'\n *\n * mistralResolver({\n *   apiKey: process.env.MISTRAL_API_KEY,\n *   model: 'mistral-medium-latest', // optional, this is the default\n * })\n * ```\n */\nexport const mistralResolver = ({\n  apiKey,\n  baseUrl = 'https://api.mistral.ai/v1',\n  instructions,\n  model = 'mistral-medium-latest',\n  timeoutMs = 30_000,\n}: MistralResolverConfig): 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}/chat/completions`, {\n        body: JSON.stringify({\n          max_tokens: maxTokens,\n          messages: [\n            { content: resolvedInstructions, role: 'system' },\n            {\n              content: [\n                { type: 'image_url', image_url: image.dataUri },\n                ...(filename ? [{ type: 'text', text: filename }] : []),\n              ],\n              role: 'user',\n            },\n          ],\n          model,\n          response_format: {\n            type: 'json_schema',\n            json_schema: { name: 'data', schema: responseSchema, strict: true },\n          },\n        }),\n        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },\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: 'Mistral', status: response.status })\n      }\n\n      const completion = (await response.json()) as {\n        choices?: { finish_reason?: string; message?: { content?: unknown } }[]\n      }\n      const choice = completion.choices?.[0]\n\n      if (choice?.finish_reason === 'length') {\n        throw new Error(\n          `Mistral ran out of tokens before finishing the alt text (max_tokens: ${maxTokens})`,\n        )\n      }\n\n      const content = choice?.message?.content\n\n      if (typeof content !== 'string') {\n        throw new Error('No result from Mistral')\n      }\n\n      try {\n        return JSON.parse(content)\n      } catch {\n        throw new Error('Mistral returned a response that was not valid JSON')\n      }\n    },\n    inlineImage: true,\n    instructions,\n    key: 'mistral',\n    label: 'Mistral',\n    // Mistral rejects images above 20 MB.\n    maxImageBytes: 20 * 1024 * 1024,\n    supportedMimeTypes: SUPPORTED_MIME_TYPES,\n    timeoutMs,\n  })\n"],"names":["createVisionResolver","VisionProviderError","SUPPORTED_MIME_TYPES","mistralResolver","apiKey","baseUrl","instructions","model","timeoutMs","generate","filename","image","resolvedInstructions","maxTokens","responseSchema","signal","Error","response","fetch","body","JSON","stringify","max_tokens","messages","content","role","type","image_url","dataUri","text","response_format","json_schema","name","schema","strict","headers","Authorization","method","ok","catch","slice","label","status","completion","json","choice","choices","finish_reason","message","parse","inlineImage","key","maxImageBytes","supportedMimeTypes"],"mappings":"AAGA,SAASA,oBAAoB,EAAEC,mBAAmB,QAAQ,4BAA2B;AAmCrF;;;;;;;;CAQC,GACD,MAAMC,uBAAuB;IAAC;IAAc;IAAa;IAAa;CAAa;AAEnF;;;;;;;;;;;;;;;;;;CAkBC,GACD,OAAO,MAAMC,kBAAkB,CAAC,EAC9BC,MAAM,EACNC,UAAU,2BAA2B,EACrCC,YAAY,EACZC,QAAQ,uBAAuB,EAC/BC,YAAY,MAAM,EACI,GACtBR,qBAAqB;QACnBI;QACAK,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,GAAGb,QAAQ,iBAAiB,CAAC,EAAE;gBAC1Dc,MAAMC,KAAKC,SAAS,CAAC;oBACnBC,YAAYT;oBACZU,UAAU;wBACR;4BAAEC,SAASZ;4BAAsBa,MAAM;wBAAS;wBAChD;4BACED,SAAS;gCACP;oCAAEE,MAAM;oCAAaC,WAAWhB,MAAMiB,OAAO;gCAAC;mCAC1ClB,WAAW;oCAAC;wCAAEgB,MAAM;wCAAQG,MAAMnB;oCAAS;iCAAE,GAAG,EAAE;6BACvD;4BACDe,MAAM;wBACR;qBACD;oBACDlB;oBACAuB,iBAAiB;wBACfJ,MAAM;wBACNK,aAAa;4BAAEC,MAAM;4BAAQC,QAAQnB;4BAAgBoB,QAAQ;wBAAK;oBACpE;gBACF;gBACAC,SAAS;oBAAEC,eAAe,CAAC,OAAO,EAAEhC,QAAQ;oBAAE,gBAAgB;gBAAmB;gBACjFiC,QAAQ;gBACRtB;YACF;YAEA,IAAI,CAACE,SAASqB,EAAE,EAAE;gBAChB,gEAAgE;gBAChE,MAAMnB,OAAO,AAAC,CAAA,MAAMF,SAASY,IAAI,GAAGU,KAAK,CAAC,IAAM,GAAE,EAAGC,KAAK,CAAC,GAAG;gBAE9D,MAAM,IAAIvC,oBAAoB;oBAAEkB;oBAAMsB,OAAO;oBAAWC,QAAQzB,SAASyB,MAAM;gBAAC;YAClF;YAEA,MAAMC,aAAc,MAAM1B,SAAS2B,IAAI;YAGvC,MAAMC,SAASF,WAAWG,OAAO,EAAE,CAAC,EAAE;YAEtC,IAAID,QAAQE,kBAAkB,UAAU;gBACtC,MAAM,IAAI/B,MACR,CAAC,qEAAqE,EAAEH,UAAU,CAAC,CAAC;YAExF;YAEA,MAAMW,UAAUqB,QAAQG,SAASxB;YAEjC,IAAI,OAAOA,YAAY,UAAU;gBAC/B,MAAM,IAAIR,MAAM;YAClB;YAEA,IAAI;gBACF,OAAOI,KAAK6B,KAAK,CAACzB;YACpB,EAAE,OAAM;gBACN,MAAM,IAAIR,MAAM;YAClB;QACF;QACAkC,aAAa;QACb5C;QACA6C,KAAK;QACLV,OAAO;QACP,sCAAsC;QACtCW,eAAe,KAAK,OAAO;QAC3BC,oBAAoBnD;QACpBM;IACF,GAAE"}

package/dist/resolvers/openAI.d.ts

@@ -1,13 +1,21 @@
+import type { VisionInstructions } from './createVisionResolver.js';
 import type { AltTextResolver } from './types.js';
 export type OpenAIResolverConfig = {
     /** OpenAI API key for authentication */
     apiKey: string;
     /**
-     * Base URL for the OpenAI-compatible API.
+     * Base URL for the OpenAI-compatible API, including the version segment.
      * Use this to point at alternative providers (e.g. Azure, Nebius, local inference).
-     * @default undefined — the OpenAI SDK defaults to 'https://api.openai.com/v1'
+     * @default 'https://api.openai.com/v1'
      */
     baseUrl?: string;
+    /**
+     * Builds the instructions from the default ones, e.g. to append a house style
+     * rule. Sent as the system message, separately from the image.
+     *
+     * @default ({ defaultInstructions }) => defaultInstructions
+     */
+    instructions?: VisionInstructions;
     /**
      * The OpenAI LLM model to use for alt text generation.
      * @default 'gpt-4.1-nano'
@@ -23,10 +31,21 @@ export type OpenAIResolverConfig = {
      * @default ['image/jpeg', 'image/png', 'image/gif', 'image/webp']
      */
     supportedMimeTypes?: string[];
+    /**
+     * Abort after this many milliseconds, covering the completion call and the
+     * retries the factory makes within it.
+     * @default 30000
+     */
+    timeoutMs?: number;
 };
 /**
  * Creates an OpenAI-based resolver for alt text generation.
  *
+ * The thumbnail URL is handed to OpenAI, which fetches it itself — so the URL
+ * has to be reachable from the public internet. When it is not, reach for a
+ * resolver that inlines the bytes instead (`mistralResolver`,
+ * `anthropicResolver`).
+ *
  * @example
  * ```typescript
  * import { openAIResolver } from '@jhb.software/payload-alt-text-plugin'
@@ -45,4 +64,4 @@ export type OpenAIResolverConfig = {
  * })
  * ```
  */
-export declare const openAIResolver: (config: OpenAIResolverConfig) => AltTextResolver;
+export declare const openAIResolver: ({ apiKey, baseUrl, instructions, model, supportedMimeTypes, timeoutMs, }: OpenAIResolverConfig) => AltTextResolver;