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

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;

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

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 — never true in local development, not true for private buckets.\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

@@ -0,0 +1,53 @@
+import type { VisionInstructions } from './createVisionResolver.js';
+import type { AltTextResolver } from './types.js';
+export type MistralResolverConfig = {
+    /** Mistral API key for authentication */
+    apiKey: string;
+    /**
+     * Base URL of the Mistral API.
+     * @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.
+     *
+     * Must be able to read images — `mistral-medium-latest`,
+     * `mistral-large-latest`, `mistral-small-latest` and the `ministral-*` models
+     * all are.
+     *
+     * @default 'mistral-medium-latest'
+     */
+    model?: string;
+    /**
+     * Abort after this many milliseconds. Covers downloading the image and the
+     * completion call together.
+     * @default 30000
+     */
+    timeoutMs?: number;
+};
+/**
+ * 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 — never true in
+ * local development, and not true for private buckets — and some hosts refuse it
+ * outright, which surfaces as `File could not be fetched from url` (error 3310).
+ *
+ * @example
+ * ```typescript
+ * import { mistralResolver } from '@jhb.software/payload-alt-text-plugin'
+ *
+ * mistralResolver({
+ *   apiKey: process.env.MISTRAL_API_KEY,
+ *   model: 'mistral-medium-latest', // optional, this is the default
+ * })
+ * ```
+ */
+export declare const mistralResolver: ({ apiKey, baseUrl, instructions, model, timeoutMs, }: MistralResolverConfig) => AltTextResolver;

package/dist/resolvers/mistral.js

@@ -0,0 +1,114 @@
+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'
+];
+/**
+ * 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 — never true in
+ * local development, and not true for private buckets — and some hosts refuse it
+ * outright, which surfaces as `File could not be fetched from url` (error 3310).
+ *
+ * @example
+ * ```typescript
+ * import { mistralResolver } from '@jhb.software/payload-alt-text-plugin'
+ *
+ * mistralResolver({
+ *   apiKey: process.env.MISTRAL_API_KEY,
+ *   model: 'mistral-medium-latest', // optional, this is the default
+ * })
+ * ```
+ */ 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');
+            }
+            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 (!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');
+            }
+        },
+        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