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

package/README.md

@@ -6,11 +6,12 @@ A [Payload CMS](https://payloadcms.com/) plugin that adds AI-powered alt text ge
 
 - Generate alt text for images using AI in the Payload Admin UI
 - Supports any AI provider using a resolver pattern (e.g., OpenAI, Anthropic, etc.)
-- Comes with a ready-to-use OpenAI resolver out of the box
+- Comes with ready-to-use OpenAI, Anthropic and Mistral resolvers out of the box
 - Automatic keyword extraction for improved admin search
 - Bulk generation for processing multiple images at once
 - Full localization support
 - Dashboard health widget with cached coverage insights across all configured upload collections
+- Multi-tenant aware: the health report can be scoped to the tenant the request is for
 
 When the plugin is enabled for an upload collection, it will:
 
@@ -77,27 +78,43 @@ This is also the recommended escape hatch if you hit Payload's Postgres SQL-buil
 
 ### Plugin Options
 
-| Option                       | Type                                  | Required | Description                                                                                                                                                                                                                                                                                                               |
-| ---------------------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `collections`                | `(CollectionSlug \| CollectionObj)[]` | Yes      | Collections to enable alt text generation for (see [Per-collection options](#per-collection-options))                                                                                                                                                                                                                     |
-| `resolver`                   | `AltTextResolver`                     | Yes      | Alt text resolver to use (e.g., `openAIResolver`)                                                                                                                                                                                                                                                                         |
-| `getImageThumbnail`          | `Function`                            | Yes      | Function to get the thumbnail URL from an image document                                                                                                                                                                                                                                                                  |
-| `enabled`                    | `boolean`                             | No       | Whether to enable the plugin                                                                                                                                                                                                                                                                                              |
-| `locale`                     | `string`                              | No       | Locale for alt text generation (required when localization is disabled)                                                                                                                                                                                                                                                   |
-| `maxBulkGenerateConcurrency` | `number`                              | No       | Maximum concurrent API requests for bulk operations (default: 16)                                                                                                                                                                                                                                                         |
-| `maxBulkGenerateIds`         | `number`                              | No       | Maximum number of image IDs accepted per bulk generate request; larger requests are rejected with `400`. Duplicate IDs are collapsed before the limit is applied (default: 100)                                                                                                                                           |
-| `fieldsOverride`             | `Function`                            | No       | Override the default fields inserted by the plugin                                                                                                                                                                                                                                                                        |
-| `healthCheck`                | `boolean \| Function`                 | No       | Alt text health tracking (REST endpoint, cache revalidation hooks, dashboard widget). `false` disables it; `true` enables it gated by `access`; a `({ req }) => boolean` function enables it and gates both the endpoint and the widget — use it to restrict the collection-wide report, e.g. to admins (default: `true`) |
+| Option                       | Type                                       | Required | Description                                                                                                                                                                                                                                                                                           |
+| ---------------------------- | ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collections`                | `(CollectionSlug \| CollectionObj)[]`      | Yes      | Collections to enable alt text generation for (see [Per-collection options](#per-collection-options))                                                                                                                                                                                                 |
+| `resolver`                   | `AltTextResolver`                          | Yes      | Alt text resolver to use (e.g., `openAIResolver`)                                                                                                                                                                                                                                                     |
+| `getImageThumbnail`          | `Function`                                 | Yes      | Function to get the thumbnail URL from an image document                                                                                                                                                                                                                                              |
+| `enabled`                    | `boolean`                                  | No       | Whether to enable the plugin                                                                                                                                                                                                                                                                          |
+| `access`                     | `({ req }) => boolean \| Promise<boolean>` | No       | Access control for the plugin's REST endpoints. Defaults to `({ req }) => !!req.user` (any authenticated user) — see [Authentication](#authentication)                                                                                                                                                |
+| `locale`                     | `string`                                   | No       | Locale for alt text generation (required when localization is disabled)                                                                                                                                                                                                                               |
+| `maxBulkGenerateConcurrency` | `number`                                   | No       | Maximum concurrent API requests for bulk operations (default: 16)                                                                                                                                                                                                                                     |
+| `maxBulkGenerateIds`         | `number`                                   | No       | Maximum number of image IDs accepted per bulk generate request; larger requests are rejected with `400`. Duplicate IDs are collapsed before the limit is applied (default: 100)                                                                                                                       |
+| `fieldsOverride`             | `Function`                                 | No       | Override the default fields inserted by the plugin                                                                                                                                                                                                                                                    |
+| `healthCheck`                | `boolean \| AltTextHealthCheckConfig`      | No       | Alt text health tracking (REST endpoint, cache revalidation hooks, dashboard widget). `false` disables it; `true` enables it for every document, gated by `access`; an object enables it and configures its `access` gate and `baseFilter` (see [Health report](#dashboard-widget)) (default: `true`) |
+| `imageThumbnailMimeType`     | `string`                                   | No       | The MIME type `getImageThumbnail` delivers. Set it when your thumbnail URL transcodes the image, so the stored format no longer decides whether generation is possible (see [Transcoding thumbnails](#transcoding-thumbnails))                                                                        |
+
+`getImageThumbnail` receives the document and `{ collection, req }`, so a single function can build different URLs per collection:
+
+```ts
+getImageThumbnail: (doc, { collection }) =>
+  collection === 'media' ? cloudinaryThumbnail(doc) : String(doc.url)
+```
+
+It may also be async, so the URL can be signed on demand:
+
+```ts
+getImageThumbnail: async (doc, { req }) => await presignThumbnailUrl(String(doc.url), req)
+```
 
 ### Per-collection options
 
 Each entry in `collections` may be either a bare collection slug (shorthand, defaults to `['image/*']` for `mimeTypes`) or an object with the following fields:
 
-| Option      | Type                      | Required | Description                                                                                                                                                                                       |
-| ----------- | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `slug`      | `CollectionSlug`          | Yes      | The collection slug                                                                                                                                                                               |
-| `mimeTypes` | `string[]`                | No       | MIME types the plugin tracks, validates, and generates for. Supports wildcards like `image/*`. Defaults to `['image/*']`.                                                                         |
-| `validate`  | `TextareaFieldValidation` | No       | Custom validator that fully replaces the default required-alt check. Import `validateAltText` from the plugin to compose around the default behavior (see [Custom validator](#custom-validator)). |
+| Option                   | Type                      | Required | Description                                                                                                                                                                                       |
+| ------------------------ | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `slug`                   | `CollectionSlug`          | Yes      | The collection slug                                                                                                                                                                               |
+| `mimeTypes`              | `string[]`                | No       | MIME types the plugin tracks, validates, and generates for. Supports wildcards like `image/*`. Defaults to `['image/*']`.                                                                         |
+| `validate`               | `TextareaFieldValidation` | No       | Custom validator that fully replaces the default required-alt check. Import `validateAltText` from the plugin to compose around the default behavior (see [Custom validator](#custom-validator)). |
+| `imageThumbnailMimeType` | `string \| null`          | No       | Overrides the plugin-level option of the same name for this collection. `null` opts the collection out of a plugin-level default (see [Transcoding thumbnails](#transcoding-thumbnails)).         |
 
 ```ts
 payloadAltTextPlugin({
@@ -109,6 +126,39 @@ payloadAltTextPlugin({
 })
 ```
 
+#### Transcoding thumbnails
+
+The resolver never sees the stored file — it only receives the URL returned by `getImageThumbnail`. When a resolver declares `supportedMimeTypes`, the plugin checks a document's stored `mimeType` against that list, which is a safe default but wrong as soon as your thumbnail URL transcodes: an AVIF or HEIC upload served through a Cloudinary `f_webp` transformation reaches the provider as WebP, yet gets rejected on its stored format.
+
+Declare what your thumbnail URL actually delivers to remove the mismatch:
+
+```ts
+payloadAltTextPlugin({
+  collections: ['media'],
+  resolver: openAIResolver({ apiKey: process.env.OPENAI_API_KEY }),
+  // Always transcodes to WebP, whatever the source format is
+  getImageThumbnail: (doc) => String(doc.url).replace('/upload/', '/upload/w_600,f_webp/'),
+  imageThumbnailMimeType: 'image/webp',
+})
+```
+
+With the declaration in place, the source format no longer gates generation — the admin button stays enabled and the endpoints stop rejecting on `mimeType`. Which source formats get alt text at all is still governed by each collection's `mimeTypes`. The declaration is validated against the resolver's `supportedMimeTypes` once at config load, so transcoding into a format your resolver cannot handle fails at boot instead of once per image.
+
+Only declare a format your transformation **always** produces. A `f_auto`-style transformation negotiates the format from the fetching client's `Accept` header and may serve the source format back, so leave it unset there and let the conservative source check apply. If you want AVIF sources to work, transcode explicitly.
+
+Collections may override the plugin-level value, or opt out of it with `null` when they are served raw:
+
+```ts
+payloadAltTextPlugin({
+  collections: [
+    'media', // inherits image/webp
+    { slug: 'documents', imageThumbnailMimeType: null }, // checked on its stored mimeType
+  ],
+  imageThumbnailMimeType: 'image/webp',
+  // ...
+})
+```
+
 #### Custom validator
 
 The default validator requires alt text on every tracked document. Some workflows — folder moves, partial API updates, or localized setups with `fallback: false` where some locales are intentionally empty — need to skip that check when the request body does not touch `alt`. Pass a `validate` function to override the default, and compose around the exported `validateAltText` to keep the standard behavior for full updates:
@@ -156,6 +206,44 @@ buildConfig({
 
 Set `healthCheck: false` in the plugin config to disable the REST endpoint, cache revalidation hooks, and dashboard widget. If your project replaces the default dashboard via `admin.components.views.dashboard`, you need to integrate the widget into your custom dashboard yourself.
 
+#### Gating and scoping the report
+
+`healthCheck` also takes an object. The main use of `baseFilter` is multi-tenancy: scope the report to the tenant selected in the admin panel, whose id [@payloadcms/plugin-multi-tenant](https://payloadcms.com/docs/plugins/multi-tenant) keeps in the `payload-tenant` cookie.
+
+```ts
+import { getTenantFromCookie } from '@payloadcms/plugin-multi-tenant/utilities'
+
+healthCheck: {
+  // Restrict the collection-wide report more strictly than the per-document
+  // generate endpoints. Gates the REST endpoint and hides the widget.
+  access: ({ req }) => req.user?.role === 'admin',
+  // Narrow what the report counts, e.g. to the tenant selected in the admin panel.
+  baseFilter: ({ collection, req }) => {
+    const tenant = getTenantFromCookie(req.headers, req.payload.db.defaultIDType)
+
+    return tenant ? { tenant: { equals: tenant } } : {}
+  },
+}
+```
+
+`baseFilter` returns a `Where` that is ANDed onto the scan's MIME type filter. It is resolved once per configured collection, so a collection that does not carry the constraining field — a media library shared across tenants, say — can return `{}` and be scanned whole. Returning `{}` for every collection is the default behaviour.
+
+The scan is cached across requests, and its cache key is derived from the resolved filters: a narrowed scan always gets its own cache entry, so one tenant's counts can never be served to another. Cache invalidation stays per collection, so a write in one tenant refreshes the report for all of them.
+
+This scopes what the report counts, not who may see it — use `access` for that. Independently of both, the report always omits the collections the requesting user cannot read.
+
+#### Skipping cache revalidation for individual writes
+
+The plugin invalidates the cached health scan via `afterChange` and `afterDelete` hooks. For writes that don't need to invalidate the cache — typically seed data created from `payload.onInit`, batch imports, or migrations — pass `context: { disableRevalidate: true }` to skip the revalidation:
+
+```ts
+await payload.create({
+  collection: 'media',
+  data: {/* ... */},
+  context: { disableRevalidate: true },
+})
+```
+
 ### Resolvers
 
 This plugin is designed to work seamlessly with various AI providers by accepting a customizable resolver as a configuration option.
@@ -173,16 +261,166 @@ openAIResolver({
 })
 ```
 
+| Option               | Type       | Required | Description                                                                                                                                                                                 |
+| -------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`             | `string`   | Yes      | API key for authentication                                                                                                                                                                  |
+| `model`              | `string`   | No       | Model to use (default: `gpt-4.1-nano`)                                                                                                                                                      |
+| `baseUrl`            | `string`   | No       | Base URL for an OpenAI-compatible provider, version segment included (default: `https://api.openai.com/v1`; e.g. Nebius, Azure)                                                             |
+| `supportedMimeTypes` | `string[]` | No       | Image formats the provider accepts (default: `['image/jpeg', 'image/png', 'image/gif', 'image/webp']`, per OpenAI's vision docs). Override it when using a `baseUrl` whose provider differs |
+| `timeoutMs`          | `number`   | No       | Abort after this many milliseconds, retries included (default: `30000`)                                                                                                                     |
+| `instructions`       | `function` | No       | Customizes the prompt, see [Customizing the instructions](#customizing-the-instructions)                                                                                                    |
+
+#### Mistral Resolver
+
+```ts
+import { mistralResolver } from '@jhb.software/payload-alt-text-plugin'
+
+mistralResolver({
+  apiKey: process.env.MISTRAL_API_KEY,
+  model: 'mistral-medium-latest', // default; any vision-capable Mistral model works
+})
+```
+
+Unlike the OpenAI resolver, this one downloads the image and sends the bytes
+rather than handing Mistral the thumbnail URL. Mistral's own fetcher needs the
+file to be reachable from the public internet, which is never the case in local
+development and not the case for private buckets; some hosts also refuse it
+outright (`File could not be fetched from url`, error 3310). Sending the bytes
+costs one extra download and removes that whole class of failure.
+
+Because there is no image conversion step, `supportedMimeTypes` is limited to
+what the Mistral API accepts directly: JPEG, PNG, GIF and WebP. Documents in
+other formats — SVG or AVIF, for instance — keep their generate button disabled.
+
+| Option         | Type       | Required | Description                                                                              |
+| -------------- | ---------- | -------- | ---------------------------------------------------------------------------------------- |
+| `apiKey`       | `string`   | Yes      | API key for authentication                                                               |
+| `model`        | `string`   | No       | Model to use (default: `mistral-medium-latest`)                                          |
+| `baseUrl`      | `string`   | No       | Base URL of the Mistral API (default: `https://api.mistral.ai/v1`)                       |
+| `timeoutMs`    | `number`   | No       | Abort after this many milliseconds, image download included (default: `30000`)           |
+| `instructions` | `function` | No       | Customizes the prompt, see [Customizing the instructions](#customizing-the-instructions) |
+
+#### Anthropic Resolver
+
+```ts
+import { anthropicResolver } from '@jhb.software/payload-alt-text-plugin'
+
+anthropicResolver({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  model: 'claude-opus-5', // default; `claude-sonnet-5` is cheaper for a large library
+  effort: 'low', // optional; describing an image needs little thinking
+})
+```
+
+Like the Mistral resolver, this one downloads the image and sends the bytes.
+Claude can fetch an image URL itself, but that requires the file to be reachable
+from the public internet, which is never the case in local development and not
+the case for private buckets. Sending the bytes also supplies the `media_type`
+that a base64 image block requires and a URL cannot carry.
+
+`supportedMimeTypes` is limited to what the Messages API accepts: JPEG, PNG, GIF
+and WebP. Documents in other formats keep their generate button disabled.
+
+| Option         | Type                                              | Required | Description                                                                                                                                                                                                                  |
+| -------------- | ------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apiKey`       | `string`                                          | Yes      | API key for authentication                                                                                                                                                                                                   |
+| `model`        | `string`                                          | No       | Model to use (default: `claude-opus-5`). `claude-sonnet-5` is cheaper; `claude-haiku-4-5` works too, but only without `effort`                                                                                               |
+| `effort`       | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | No       | How long Claude thinks before answering. `low` is plenty for describing an image and keeps the spend down. Omitted, the field is not sent and Claude uses its default (`high`), so models without effort support stay usable |
+| `baseUrl`      | `string`                                          | No       | Base URL of the Anthropic API (default: `https://api.anthropic.com`)                                                                                                                                                         |
+| `timeoutMs`    | `number`                                          | No       | Abort after this many milliseconds, image download included (default: `30000`)                                                                                                                                               |
+| `instructions` | `function`                                        | No       | Customizes the prompt, see [Customizing the instructions](#customizing-the-instructions)                                                                                                                                     |
+
+### Customizing the instructions
+
+Every bundled resolver accepts an `instructions` function that receives the
+instructions the resolver would send on its own, so a house style rule can be
+appended without restating the rules the plugin depends on:
+
+```ts
+openAIResolver({
+  apiKey: process.env.OPENAI_API_KEY!,
+  instructions: ({ defaultInstructions }) =>
+    `${defaultInstructions}\n\nName the product line when its packaging is legible. Never guess at a person's role.`,
+})
+```
+
+It is called once per generation and receives `{ defaultInstructions, locales, filename }`.
+Returning something entirely different is allowed — the image and the required
+response shape travel separately from the instructions, so a replacement cannot
+break the resolver's contract with its provider.
+
 ## Custom Resolver
 
-You can create your own resolver by implementing the `AltTextResolver` interface.
+For another LLM provider, `createVisionResolver` is usually the shortest path: it
+owns the prompt, the per-locale response schema, the optional image download and
+the strict reading of the response, leaving only the provider call to `generate`.
+Every bundled resolver is built on it.
+
+```ts
+import { createVisionResolver, VisionProviderError } from '@jhb.software/payload-alt-text-plugin'
+
+export const myResolver = ({ apiKey }: { apiKey: string }) =>
+  createVisionResolver({
+    apiKey,
+    // `image` is only present when `inlineImage` is set; otherwise pass
+    // `imageThumbnailUrl` to the provider and let it fetch the file.
+    generate: async ({ image, instructions, maxTokens, responseSchema, signal }) => {
+      if (!image) {
+        throw new Error('The image was not downloaded')
+      }
+
+      const response = await fetch('https://api.example.com/v1/vision', {
+        body: JSON.stringify({ instructions, image: image.dataUri, schema: responseSchema }),
+        headers: { Authorization: `Bearer ${apiKey}` },
+        method: 'POST',
+        signal,
+      })
+
+      // A rate limit or an outage is worth another attempt: throwing
+      // `VisionProviderError` lets the factory retry it. Any other error fails
+      // the generation immediately, with its message shown in the admin panel.
+      if (!response.ok) {
+        throw new VisionProviderError({
+          body: await response.text(),
+          label: 'My Provider',
+          status: response.status,
+        })
+      }
+
+      // Return the parsed JSON object.
+      return await response.json()
+    },
+    inlineImage: true,
+    key: 'my-provider',
+    label: 'My Provider',
+    supportedMimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  })
+```
+
+A provider call that fails with `VisionProviderError` is retried twice, with a
+short backoff, when the status is a rate limit (`429`) or a server-side failure
+(`5xx`) — a bulk generation trips those routinely, and giving up on the first one
+leaves documents without an alt text. Any other status fails immediately: a `4xx`
+would fail identically on every attempt. The resolver's `timeoutMs` covers the
+attempts together.
+
+Pass the provider's response as `body` and it is written to the server log, never
+to the error the admin panel shows — that message reaches everyone allowed to
+generate an alt text, and a provider's error text is not written with them in
+mind: OpenAI quotes the rejected API key back in a 401. The panel gets the
+provider name and the status.
+
+For a provider that does not fit that shape at all, implement the
+`AltTextResolver` interface directly.
+
+Alongside `imageThumbnailUrl`, the resolver receives `imageThumbnailMimeType` — the format served at that URL, when the collection declares one via [`imageThumbnailMimeType`](#transcoding-thumbnails). Resolvers that hand the URL to the provider can ignore it. Resolvers that inline the bytes need it, because an explicit media type cannot be sniffed from a URL: Anthropic image blocks require `media_type` and Gemini's `inline_data` requires `mime_type`. It is `undefined` when nothing was declared. Resolvers built on `createVisionResolver` get this for free: `image.mediaType` is the type the host actually served, with the declaration standing in when the host sent none or a generic `application/octet-stream`.
 
 ```ts
 import type { AltTextResolver } from '@jhb.software/payload-alt-text-plugin'
 
 export const customResolver = (): AltTextResolver => ({
   key: 'custom',
-  resolve: async ({ imageThumbnailUrl, filename, locale, req }) => {
+  resolve: async ({ imageThumbnailUrl, imageThumbnailMimeType, filename, locale, req }) => {
     // Your custom alt text generation logic here
     const altText = await generateAltText(imageThumbnailUrl, filename, locale, req)
 
@@ -205,7 +443,24 @@ export const customResolver = (): AltTextResolver => ({
 
 ## REST API Endpoints
 
-The plugin registers the following REST API endpoints under `/api/alt-text/`. All endpoints require authentication by default (configurable via the `access` option). Beyond that gate, the generate endpoints enforce each collection's own access control on the documents they read and write, and the health endpoint reports only the collections the requesting user can read (and can be gated separately via the `healthCheck` function).
+The plugin registers the following REST API endpoints under `/api/alt-text/`.
+
+### Authentication
+
+The endpoints require an authenticated request and respond with `401` otherwise. By default any authenticated Payload user (admin session or API key) is allowed:
+
+```ts
+;({ req }) => !!req.user
+```
+
+That default fits a setup where every Payload user is trusted staff. Generating alt text spends money at the configured provider and the bulk endpoint writes to many documents at once, so projects with public sign-up, customer-facing accounts, or any user tier that should not incur provider cost must narrow it via the `access` option:
+
+```ts
+// Only allow editors to use the generate endpoints
+access: ({ req }) => req.user?.role === 'editor'
+```
+
+Beyond that gate, the generate endpoints enforce each collection's own access control on the documents they read and write, and the health endpoint reports only the collections the requesting user can read (and can be gated separately via `healthCheck.access`).
 
 ### `POST /api/alt-text/generate`
 

package/dist/endpoints/bulkGenerateAltTexts.js

@@ -2,7 +2,7 @@ import pMap from 'p-map';
 import { APIError, Forbidden } from 'payload';
 import { ZodError } from 'zod';
 import { localesFromConfig } from '../utilities/localesFromConfig.js';
-import { matchesMimeType } from '../utilities/mimeTypes.js';
+import { getUnsupportedSourceMimeTypeError, matchesMimeType } from '../utilities/mimeTypes.js';
 import { bulkGenerateAltTextsRequestSchema, formatZodError } from './schemas.js';
 /**
  * Generates and updates alt text for multiple images in all locales.
@@ -85,7 +85,7 @@ import { bulkGenerateAltTextsRequestSchema, formatZodError } from './schemas.js'
                         req
                     });
                     updatedDocs++;
-                    console.log(`${updatedDocs}/${uniqueIds.length} updated (${Math.round(updatedDocs / uniqueIds.length * 100)}%)`);
+                    req.payload.logger.info(`${updatedDocs}/${uniqueIds.length} updated (${Math.round(updatedDocs / uniqueIds.length * 100)}%)`);
                 } catch (error) {
                     // A Forbidden means the user has no read/update access to the
                     // collection at all — it applies to every id, so fail the whole
@@ -94,14 +94,16 @@ import { bulkGenerateAltTextsRequestSchema, formatZodError } from './schemas.js'
                     if (error instanceof Forbidden) {
                         throw error;
                     }
-                    console.error(`Error generating alt text for ${id}:`, error);
+                    req.payload.logger.error({
+                        err: error
+                    }, `Error generating alt text for ${id}`);
                     erroredDocs.push(id);
                 }
             }, {
                 concurrency
             });
             if (erroredDocs.length > 0) {
-                console.error(`Failed for: ${erroredDocs.join(', ')}`);
+                req.payload.logger.error(`Failed for: ${erroredDocs.join(', ')}`);
             }
             return Response.json({
                 erroredDocs,
@@ -123,7 +125,9 @@ import { bulkGenerateAltTextsRequestSchema, formatZodError } from './schemas.js'
                     status: error.status
                 });
             }
-            console.error('Error in bulk generation:', error);
+            req.payload.logger.error({
+                err: error
+            }, 'Error in bulk generation');
             return Response.json({
                 error: `Error generating alt text: ${error instanceof Error ? error.message : 'Unknown error'}`
             }, {
@@ -151,12 +155,21 @@ async function generateAndUpdateAltText({ id, collection, locales, payload, plug
     if (mimeType && !matchesMimeType(mimeType, collectionConfig.mimeTypes)) {
         throw new Error(`Alt text is not tracked for files of type "${mimeType}" in the "${collection}" collection. Tracked types: ${collectionConfig.mimeTypes.join(', ')}.`);
     }
-    if (mimeType && pluginConfig.resolver.supportedMimeTypes && !pluginConfig.resolver.supportedMimeTypes.includes(mimeType)) {
-        throw new Error(`Alt text generation is not supported for files of type "${mimeType}". Supported types: ${pluginConfig.resolver.supportedMimeTypes.join(', ')}.`);
+    const unsupportedSourceError = getUnsupportedSourceMimeTypeError({
+        declaredThumbnailMimeType: collectionConfig.imageThumbnailMimeType,
+        mimeType,
+        supportedMimeTypes: pluginConfig.resolver.supportedMimeTypes
+    });
+    if (unsupportedSourceError) {
+        throw new Error(unsupportedSourceError);
     }
-    const imageThumbnailUrl = pluginConfig.getImageThumbnail(imageDoc);
+    const imageThumbnailUrl = await pluginConfig.getImageThumbnail(imageDoc, {
+        collection,
+        req
+    });
     const result = await pluginConfig.resolver.resolveBulk({
         filename: 'filename' in imageDoc && typeof imageDoc.filename === 'string' ? imageDoc.filename : undefined,
+        imageThumbnailMimeType: collectionConfig.imageThumbnailMimeType,
         imageThumbnailUrl,
         locales,
         req

package/dist/endpoints/bulkGenerateAltTexts.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/endpoints/bulkGenerateAltTexts.ts"],"sourcesContent":["import type { BasePayload, CollectionSlug, PayloadHandler, PayloadRequest } from 'payload'\n\nimport pMap from 'p-map'\nimport { APIError, Forbidden } from 'payload'\nimport { ZodError } from 'zod'\n\nimport type { AltTextPluginConfig } from '../types/AltTextPluginConfig.js'\n\nimport { localesFromConfig } from '../utilities/localesFromConfig.js'\nimport { matchesMimeType } from '../utilities/mimeTypes.js'\nimport { bulkGenerateAltTextsRequestSchema, formatZodError } from './schemas.js'\n\n/**\n * Generates and updates alt text for multiple images in all locales.\n */\nexport const bulkGenerateAltTextsEndpoint =\n  (access: AltTextPluginConfig['access']): PayloadHandler =>\n  async (req: PayloadRequest) => {\n    try {\n      if (!(await access({ req }))) {\n        return Response.json({ error: 'Unauthorized' }, { status: 401 })\n      }\n\n      const data = 'json' in req && typeof req.json === 'function' ? await req.json() : null\n\n      const { collection, ids } = bulkGenerateAltTextsRequestSchema.parse(data)\n\n      let updatedDocs = 0\n      const erroredDocs: (number | string)[] = []\n\n      // Get plugin config from payload config\n      const pluginConfig = req.payload.config.custom?.altTextPluginConfig as\n        | AltTextPluginConfig\n        | undefined\n\n      if (!pluginConfig) {\n        return Response.json({ error: 'Plugin config not found' }, { status: 500 })\n      }\n\n      // Treat the configured collections as an allowlist. Reject any other\n      // collection before touching the Local API, so the endpoint can only ever\n      // operate on the upload collections the plugin manages.\n      const collectionConfig = pluginConfig.collections.find((entry) => entry.slug === collection)\n\n      if (!collectionConfig) {\n        return Response.json(\n          { error: `Collection \"${collection}\" is not managed by the alt text plugin.` },\n          { status: 403 },\n        )\n      }\n\n      if (!pluginConfig.resolver) {\n        return Response.json({ error: 'No alt text resolver configured' }, { status: 500 })\n      }\n\n      const concurrency = pluginConfig.maxBulkGenerateConcurrency\n\n      // De-duplicate so the same image is never generated (and billed) twice,\n      // then bound the batch so a single request cannot fan out into an\n      // unbounded number of paid resolver calls.\n      const uniqueIds = [...new Set(ids)]\n\n      if (uniqueIds.length > pluginConfig.maxBulkGenerateIds) {\n        return Response.json(\n          {\n            error: `Too many ids: ${uniqueIds.length} exceeds the maximum of ${pluginConfig.maxBulkGenerateIds} per request.`,\n          },\n          { status: 400 },\n        )\n      }\n\n      // determine target locales based on config\n      const locales = localesFromConfig(req.payload.config)\n      const targetLocales = locales ?? [pluginConfig.locale!]\n      if (!targetLocales) {\n        return Response.json(\n          {\n            error:\n              'Could not determine target locales for alt text generation. Please check your plugin configuration.',\n          },\n          { status: 500 },\n        )\n      }\n\n      await pMap(\n        uniqueIds,\n        async (id) => {\n          try {\n            await generateAndUpdateAltText({\n              id,\n              collection,\n              locales: targetLocales,\n              payload: req.payload,\n              pluginConfig,\n              req,\n            })\n            updatedDocs++\n            console.log(\n              `${updatedDocs}/${uniqueIds.length} updated (${Math.round((updatedDocs / uniqueIds.length) * 100)}%)`,\n            )\n          } catch (error) {\n            // A Forbidden means the user has no read/update access to the\n            // collection at all — it applies to every id, so fail the whole\n            // request with a real 403 instead of silently listing all ids as\n            // errored. Row-level NotFound stays a per-doc error (partial success).\n            if (error instanceof Forbidden) {\n              throw error\n            }\n            console.error(`Error generating alt text for ${id}:`, error)\n            erroredDocs.push(id)\n          }\n        },\n        { concurrency },\n      )\n\n      if (erroredDocs.length > 0) {\n        console.error(`Failed for: ${erroredDocs.join(', ')}`)\n      }\n\n      return Response.json({\n        erroredDocs,\n        totalDocs: uniqueIds.length,\n        updatedDocs,\n      })\n    } catch (error) {\n      if (error instanceof ZodError) {\n        return Response.json(formatZodError(error), { status: 400 })\n      }\n      // Surface Payload access errors (Forbidden 403) with their real status so\n      // an agent gets an accurate, non-retryable signal instead of a 500.\n      if (error instanceof APIError) {\n        return Response.json({ error: error.message }, { status: error.status })\n      }\n      console.error('Error in bulk generation:', error)\n      return Response.json(\n        {\n          error: `Error generating alt text: ${error instanceof Error ? error.message : 'Unknown error'}`,\n        },\n        { status: 500 },\n      )\n    }\n  }\n\nasync function generateAndUpdateAltText({\n  id,\n  collection,\n  locales,\n  payload,\n  pluginConfig,\n  req,\n}: {\n  collection: CollectionSlug\n  id: number | string\n  locales: string[]\n  payload: BasePayload\n  pluginConfig: AltTextPluginConfig\n  req: PayloadRequest\n}) {\n  const imageDoc = await payload.findByID({\n    id,\n    collection,\n    depth: 0,\n    // Run under the requesting user's access, not Payload's default\n    // `overrideAccess: true`, so collection-level access control applies.\n    overrideAccess: false,\n    user: req.user,\n  })\n\n  if (!imageDoc) {\n    throw new Error('Image not found')\n  }\n\n  const mimeType =\n    'mimeType' in imageDoc && typeof imageDoc.mimeType === 'string' ? imageDoc.mimeType : undefined\n\n  // The handler validates `collection` against the configured collections before\n  // reaching this helper, so a matching entry is guaranteed.\n  const collectionConfig = pluginConfig.collections.find((entry) => entry.slug === collection)!\n\n  if (mimeType && !matchesMimeType(mimeType, collectionConfig.mimeTypes)) {\n    throw new Error(\n      `Alt text is not tracked for files of type \"${mimeType}\" in the \"${collection}\" collection. Tracked types: ${collectionConfig.mimeTypes.join(', ')}.`,\n    )\n  }\n\n  if (\n    mimeType &&\n    pluginConfig.resolver.supportedMimeTypes &&\n    !pluginConfig.resolver.supportedMimeTypes.includes(mimeType)\n  ) {\n    throw new Error(\n      `Alt text generation is not supported for files of type \"${mimeType}\". Supported types: ${pluginConfig.resolver.supportedMimeTypes.join(', ')}.`,\n    )\n  }\n\n  const imageThumbnailUrl = pluginConfig.getImageThumbnail(imageDoc)\n\n  const result = await pluginConfig.resolver.resolveBulk({\n    filename:\n      'filename' in imageDoc && typeof imageDoc.filename === 'string'\n        ? imageDoc.filename\n        : undefined,\n    imageThumbnailUrl,\n    locales,\n    req,\n  })\n\n  if (!result.success) {\n    throw new Error(result.error || 'Failed to generate alt text')\n  }\n\n  for (const locale of locales) {\n    const localeResult = result.results[locale]\n    if (localeResult) {\n      await payload.update({\n        id,\n        collection,\n        data: {\n          alt: localeResult.altText,\n          keywords: localeResult.keywords,\n        },\n        locale,\n        // Run under the requesting user's access, not Payload's default\n        // `overrideAccess: true`, so collection-level access control applies.\n        overrideAccess: false,\n        user: req.user,\n      })\n    }\n  }\n}\n"],"names":["pMap","APIError","Forbidden","ZodError","localesFromConfig","matchesMimeType","bulkGenerateAltTextsRequestSchema","formatZodError","bulkGenerateAltTextsEndpoint","access","req","Response","json","error","status","data","collection","ids","parse","updatedDocs","erroredDocs","pluginConfig","payload","config","custom","altTextPluginConfig","collectionConfig","collections","find","entry","slug","resolver","concurrency","maxBulkGenerateConcurrency","uniqueIds","Set","length","maxBulkGenerateIds","locales","targetLocales","locale","id","generateAndUpdateAltText","console","log","Math","round","push","join","totalDocs","message","Error","imageDoc","findByID","depth","overrideAccess","user","mimeType","undefined","mimeTypes","supportedMimeTypes","includes","imageThumbnailUrl","getImageThumbnail","result","resolveBulk","filename","success","localeResult","results","update","alt","altText","keywords"],"mappings":"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"}
+{"version":3,"sources":["../../src/endpoints/bulkGenerateAltTexts.ts"],"sourcesContent":["import type { BasePayload, CollectionSlug, PayloadHandler, PayloadRequest } from 'payload'\n\nimport pMap from 'p-map'\nimport { APIError, Forbidden } from 'payload'\nimport { ZodError } from 'zod'\n\nimport type { AltTextPluginConfig } from '../types/AltTextPluginConfig.js'\n\nimport { localesFromConfig } from '../utilities/localesFromConfig.js'\nimport { getUnsupportedSourceMimeTypeError, matchesMimeType } from '../utilities/mimeTypes.js'\nimport { bulkGenerateAltTextsRequestSchema, formatZodError } from './schemas.js'\n\n/**\n * Generates and updates alt text for multiple images in all locales.\n */\nexport const bulkGenerateAltTextsEndpoint =\n  (access: AltTextPluginConfig['access']): PayloadHandler =>\n  async (req: PayloadRequest) => {\n    try {\n      if (!(await access({ req }))) {\n        return Response.json({ error: 'Unauthorized' }, { status: 401 })\n      }\n\n      const data = 'json' in req && typeof req.json === 'function' ? await req.json() : null\n\n      const { collection, ids } = bulkGenerateAltTextsRequestSchema.parse(data)\n\n      let updatedDocs = 0\n      const erroredDocs: (number | string)[] = []\n\n      // Get plugin config from payload config\n      const pluginConfig = req.payload.config.custom?.altTextPluginConfig as\n        AltTextPluginConfig | undefined\n\n      if (!pluginConfig) {\n        return Response.json({ error: 'Plugin config not found' }, { status: 500 })\n      }\n\n      // Treat the configured collections as an allowlist. Reject any other\n      // collection before touching the Local API, so the endpoint can only ever\n      // operate on the upload collections the plugin manages.\n      const collectionConfig = pluginConfig.collections.find((entry) => entry.slug === collection)\n\n      if (!collectionConfig) {\n        return Response.json(\n          { error: `Collection \"${collection}\" is not managed by the alt text plugin.` },\n          { status: 403 },\n        )\n      }\n\n      if (!pluginConfig.resolver) {\n        return Response.json({ error: 'No alt text resolver configured' }, { status: 500 })\n      }\n\n      const concurrency = pluginConfig.maxBulkGenerateConcurrency\n\n      // De-duplicate so the same image is never generated (and billed) twice,\n      // then bound the batch so a single request cannot fan out into an\n      // unbounded number of paid resolver calls.\n      const uniqueIds = [...new Set(ids)]\n\n      if (uniqueIds.length > pluginConfig.maxBulkGenerateIds) {\n        return Response.json(\n          {\n            error: `Too many ids: ${uniqueIds.length} exceeds the maximum of ${pluginConfig.maxBulkGenerateIds} per request.`,\n          },\n          { status: 400 },\n        )\n      }\n\n      // determine target locales based on config\n      const locales = localesFromConfig(req.payload.config)\n      const targetLocales = locales ?? [pluginConfig.locale!]\n      if (!targetLocales) {\n        return Response.json(\n          {\n            error:\n              'Could not determine target locales for alt text generation. Please check your plugin configuration.',\n          },\n          { status: 500 },\n        )\n      }\n\n      await pMap(\n        uniqueIds,\n        async (id) => {\n          try {\n            await generateAndUpdateAltText({\n              id,\n              collection,\n              locales: targetLocales,\n              payload: req.payload,\n              pluginConfig,\n              req,\n            })\n            updatedDocs++\n            req.payload.logger.info(\n              `${updatedDocs}/${uniqueIds.length} updated (${Math.round((updatedDocs / uniqueIds.length) * 100)}%)`,\n            )\n          } catch (error) {\n            // A Forbidden means the user has no read/update access to the\n            // collection at all — it applies to every id, so fail the whole\n            // request with a real 403 instead of silently listing all ids as\n            // errored. Row-level NotFound stays a per-doc error (partial success).\n            if (error instanceof Forbidden) {\n              throw error\n            }\n            req.payload.logger.error({ err: error }, `Error generating alt text for ${id}`)\n            erroredDocs.push(id)\n          }\n        },\n        { concurrency },\n      )\n\n      if (erroredDocs.length > 0) {\n        req.payload.logger.error(`Failed for: ${erroredDocs.join(', ')}`)\n      }\n\n      return Response.json({\n        erroredDocs,\n        totalDocs: uniqueIds.length,\n        updatedDocs,\n      })\n    } catch (error) {\n      if (error instanceof ZodError) {\n        return Response.json(formatZodError(error), { status: 400 })\n      }\n      // Surface Payload access errors (Forbidden 403) with their real status so\n      // an agent gets an accurate, non-retryable signal instead of a 500.\n      if (error instanceof APIError) {\n        return Response.json({ error: error.message }, { status: error.status })\n      }\n      req.payload.logger.error({ err: error }, 'Error in bulk generation')\n      return Response.json(\n        {\n          error: `Error generating alt text: ${error instanceof Error ? error.message : 'Unknown error'}`,\n        },\n        { status: 500 },\n      )\n    }\n  }\n\nasync function generateAndUpdateAltText({\n  id,\n  collection,\n  locales,\n  payload,\n  pluginConfig,\n  req,\n}: {\n  collection: CollectionSlug\n  id: number | string\n  locales: string[]\n  payload: BasePayload\n  pluginConfig: AltTextPluginConfig\n  req: PayloadRequest\n}) {\n  const imageDoc = await payload.findByID({\n    id,\n    collection,\n    depth: 0,\n    // Run under the requesting user's access, not Payload's default\n    // `overrideAccess: true`, so collection-level access control applies.\n    overrideAccess: false,\n    user: req.user,\n  })\n\n  if (!imageDoc) {\n    throw new Error('Image not found')\n  }\n\n  const mimeType =\n    'mimeType' in imageDoc && typeof imageDoc.mimeType === 'string' ? imageDoc.mimeType : undefined\n\n  // The handler validates `collection` against the configured collections before\n  // reaching this helper, so a matching entry is guaranteed.\n  const collectionConfig = pluginConfig.collections.find((entry) => entry.slug === collection)!\n\n  if (mimeType && !matchesMimeType(mimeType, collectionConfig.mimeTypes)) {\n    throw new Error(\n      `Alt text is not tracked for files of type \"${mimeType}\" in the \"${collection}\" collection. Tracked types: ${collectionConfig.mimeTypes.join(', ')}.`,\n    )\n  }\n\n  const unsupportedSourceError = getUnsupportedSourceMimeTypeError({\n    declaredThumbnailMimeType: collectionConfig.imageThumbnailMimeType,\n    mimeType,\n    supportedMimeTypes: pluginConfig.resolver.supportedMimeTypes,\n  })\n  if (unsupportedSourceError) {\n    throw new Error(unsupportedSourceError)\n  }\n\n  const imageThumbnailUrl = await pluginConfig.getImageThumbnail(imageDoc, { collection, req })\n\n  const result = await pluginConfig.resolver.resolveBulk({\n    filename:\n      'filename' in imageDoc && typeof imageDoc.filename === 'string'\n        ? imageDoc.filename\n        : undefined,\n    imageThumbnailMimeType: collectionConfig.imageThumbnailMimeType,\n    imageThumbnailUrl,\n    locales,\n    req,\n  })\n\n  if (!result.success) {\n    throw new Error(result.error || 'Failed to generate alt text')\n  }\n\n  for (const locale of locales) {\n    const localeResult = result.results[locale]\n    if (localeResult) {\n      await payload.update({\n        id,\n        collection,\n        data: {\n          alt: localeResult.altText,\n          keywords: localeResult.keywords,\n        },\n        locale,\n        // Run under the requesting user's access, not Payload's default\n        // `overrideAccess: true`, so collection-level access control applies.\n        overrideAccess: false,\n        user: req.user,\n      })\n    }\n  }\n}\n"],"names":["pMap","APIError","Forbidden","ZodError","localesFromConfig","getUnsupportedSourceMimeTypeError","matchesMimeType","bulkGenerateAltTextsRequestSchema","formatZodError","bulkGenerateAltTextsEndpoint","access","req","Response","json","error","status","data","collection","ids","parse","updatedDocs","erroredDocs","pluginConfig","payload","config","custom","altTextPluginConfig","collectionConfig","collections","find","entry","slug","resolver","concurrency","maxBulkGenerateConcurrency","uniqueIds","Set","length","maxBulkGenerateIds","locales","targetLocales","locale","id","generateAndUpdateAltText","logger","info","Math","round","err","push","join","totalDocs","message","Error","imageDoc","findByID","depth","overrideAccess","user","mimeType","undefined","mimeTypes","unsupportedSourceError","declaredThumbnailMimeType","imageThumbnailMimeType","supportedMimeTypes","imageThumbnailUrl","getImageThumbnail","result","resolveBulk","filename","success","localeResult","results","update","alt","altText","keywords"],"mappings":"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"}

package/dist/endpoints/generateAltText.js

@@ -1,6 +1,6 @@
 import { APIError } from 'payload';
 import { ZodError } from 'zod';
-import { matchesMimeType } from '../utilities/mimeTypes.js';
+import { getUnsupportedSourceMimeTypeError, matchesMimeType } from '../utilities/mimeTypes.js';
 import { formatZodError, generateAltTextRequestSchema } from './schemas.js';
 /**
  * Generates alt text for a single image using the configured resolver.
@@ -80,9 +80,14 @@ import { formatZodError, generateAltTextRequestSchema } from './schemas.js';
                     status: 400
                 });
             }
-            if (mimeType && pluginConfig.resolver.supportedMimeTypes && !pluginConfig.resolver.supportedMimeTypes.includes(mimeType)) {
+            const unsupportedSourceError = getUnsupportedSourceMimeTypeError({
+                declaredThumbnailMimeType: collectionConfig.imageThumbnailMimeType,
+                mimeType,
+                supportedMimeTypes: pluginConfig.resolver.supportedMimeTypes
+            });
+            if (unsupportedSourceError) {
                 return Response.json({
-                    error: `Alt text generation is not supported for files of type "${mimeType}". Supported types: ${pluginConfig.resolver.supportedMimeTypes.join(', ')}.`
+                    error: unsupportedSourceError
                 }, {
                     status: 400
                 });
@@ -106,9 +111,13 @@ import { formatZodError, generateAltTextRequestSchema } from './schemas.js';
                     status: 500
                 });
             }
-            const imageThumbnailUrl = pluginConfig.getImageThumbnail(imageDoc);
+            const imageThumbnailUrl = await pluginConfig.getImageThumbnail(imageDoc, {
+                collection,
+                req
+            });
             const result = await pluginConfig.resolver.resolve({
                 filename: 'filename' in imageDoc && typeof imageDoc.filename === 'string' ? imageDoc.filename : undefined,
+                imageThumbnailMimeType: collectionConfig.imageThumbnailMimeType,
                 imageThumbnailUrl,
                 locale: targetLocale,
                 req
@@ -156,7 +165,9 @@ import { formatZodError, generateAltTextRequestSchema } from './schemas.js';
                     status: error.status
                 });
             }
-            console.error('Error generating alt text:', error);
+            req.payload.logger.error({
+                err: error
+            }, 'Error generating alt text');
             return Response.json({
                 error: `Error generating alt text: ${error instanceof Error ? error.message : 'Unknown error'}`
             }, {

package/dist/endpoints/generateAltText.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/endpoints/generateAltText.ts"],"sourcesContent":["import type { PayloadHandler, PayloadRequest } from 'payload'\n\nimport { APIError } from 'payload'\nimport { ZodError } from 'zod'\n\nimport type { AltTextPluginConfig } from '../types/AltTextPluginConfig.js'\n\nimport { matchesMimeType } from '../utilities/mimeTypes.js'\nimport { formatZodError, generateAltTextRequestSchema } from './schemas.js'\n\n/**\n * Generates alt text for a single image using the configured resolver.\n *\n * By default, returns the result without updating the document (preview mode).\n * Pass `update: true` in the request body to also persist the generated alt text\n * and keywords to the document — useful for programmatic/agent workflows.\n *\n * The response always includes the `id` and `collection` for easy correlation.\n */\nexport const generateAltTextEndpoint =\n  (access: AltTextPluginConfig['access']): PayloadHandler =>\n  async (req: PayloadRequest) => {\n    try {\n      if (!(await access({ req }))) {\n        return Response.json({ error: 'Unauthorized' }, { status: 401 })\n      }\n\n      const data = 'json' in req && typeof req.json === 'function' ? await req.json() : null\n\n      const { id, collection, locale, update } = generateAltTextRequestSchema.parse(data)\n\n      const pluginConfig = req.payload.config.custom?.altTextPluginConfig as\n        | AltTextPluginConfig\n        | undefined\n\n      if (!pluginConfig) {\n        return Response.json({ error: 'Plugin config not found' }, { status: 500 })\n      }\n\n      // Treat the configured collections as an allowlist. Reject any other\n      // collection before touching the Local API, so the endpoint can only ever\n      // operate on the upload collections the plugin manages.\n      const collectionConfig = pluginConfig.collections.find((entry) => entry.slug === collection)\n\n      if (!collectionConfig) {\n        return Response.json(\n          { error: `Collection \"${collection}\" is not managed by the alt text plugin.` },\n          { status: 403 },\n        )\n      }\n\n      const imageDoc = await req.payload.findByID({\n        id,\n        collection,\n        depth: 0,\n        // Run under the requesting user's access, not Payload's default\n        // `overrideAccess: true`, so collection-level access control applies.\n        overrideAccess: false,\n        user: req.user,\n      })\n\n      if (!imageDoc) {\n        return Response.json({ error: 'Image not found' }, { status: 404 })\n      }\n\n      if (!pluginConfig.getImageThumbnail) {\n        return Response.json(\n          { error: 'getImageThumbnail function not configured' },\n          { status: 500 },\n        )\n      }\n\n      if (!pluginConfig.resolver) {\n        return Response.json({ error: 'No alt text resolver configured' }, { status: 500 })\n      }\n\n      const mimeType =\n        'mimeType' in imageDoc && typeof imageDoc.mimeType === 'string'\n          ? imageDoc.mimeType\n          : undefined\n\n      if (mimeType && !matchesMimeType(mimeType, collectionConfig.mimeTypes)) {\n        return Response.json(\n          {\n            error: `Alt text is not tracked for files of type \"${mimeType}\" in the \"${collection}\" collection. Tracked types: ${collectionConfig.mimeTypes.join(', ')}.`,\n          },\n          { status: 400 },\n        )\n      }\n\n      if (\n        mimeType &&\n        pluginConfig.resolver.supportedMimeTypes &&\n        !pluginConfig.resolver.supportedMimeTypes.includes(mimeType)\n      ) {\n        return Response.json(\n          {\n            error: `Alt text generation is not supported for files of type \"${mimeType}\". Supported types: ${pluginConfig.resolver.supportedMimeTypes.join(', ')}.`,\n          },\n          { status: 400 },\n        )\n      }\n\n      // When localization is enabled, the requested locale must be one of the\n      // configured locales. Reject anything else before it can be written to an\n      // unconfigured locale or interpolated into the resolver's prompt.\n      if (\n        locale != null &&\n        pluginConfig.locales.length > 0 &&\n        !pluginConfig.locales.includes(locale)\n      ) {\n        return Response.json(\n          {\n            error: `Locale \"${locale}\" is not configured. Configured locales: ${pluginConfig.locales.join(', ')}.`,\n          },\n          { status: 400 },\n        )\n      }\n\n      // determine target locale\n      const targetLocale = locale ?? pluginConfig.locale\n      if (!targetLocale) {\n        return Response.json(\n          {\n            error:\n              'Could not determine target locale for alt text generation. Please check your plugin configuration.',\n          },\n          { status: 500 },\n        )\n      }\n\n      const imageThumbnailUrl = pluginConfig.getImageThumbnail(imageDoc)\n\n      const result = await pluginConfig.resolver.resolve({\n        filename:\n          'filename' in imageDoc && typeof imageDoc.filename === 'string'\n            ? imageDoc.filename\n            : undefined,\n        imageThumbnailUrl,\n        locale: targetLocale,\n        req,\n      })\n\n      if (!result.success) {\n        return Response.json(\n          { error: result.error || 'Failed to generate alt text' },\n          { status: 500 },\n        )\n      }\n\n      if (update) {\n        await req.payload.update({\n          id,\n          collection,\n          data: {\n            alt: result.result.altText,\n            keywords: result.result.keywords,\n          },\n          locale: targetLocale,\n          // Run under the requesting user's access, not Payload's default\n          // `overrideAccess: true`, so collection-level access control applies.\n          overrideAccess: false,\n          user: req.user,\n        })\n      }\n\n      return Response.json({ id, collection, ...result.result })\n    } catch (error) {\n      if (error instanceof ZodError) {\n        return Response.json(formatZodError(error), { status: 400 })\n      }\n      // Surface Payload access errors (Forbidden 403 / NotFound 404) with their\n      // real status so an agent gets an accurate, non-retryable signal instead\n      // of a misleading 500.\n      if (error instanceof APIError) {\n        return Response.json({ error: error.message }, { status: error.status })\n      }\n      console.error('Error generating alt text:', error)\n      return Response.json(\n        {\n          error: `Error generating alt text: ${error instanceof Error ? error.message : 'Unknown error'}`,\n        },\n        { status: 500 },\n      )\n    }\n  }\n"],"names":["APIError","ZodError","matchesMimeType","formatZodError","generateAltTextRequestSchema","generateAltTextEndpoint","access","req","Response","json","error","status","data","id","collection","locale","update","parse","pluginConfig","payload","config","custom","altTextPluginConfig","collectionConfig","collections","find","entry","slug","imageDoc","findByID","depth","overrideAccess","user","getImageThumbnail","resolver","mimeType","undefined","mimeTypes","join","supportedMimeTypes","includes","locales","length","targetLocale","imageThumbnailUrl","result","resolve","filename","success","alt","altText","keywords","message","console","Error"],"mappings":"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"}
+{"version":3,"sources":["../../src/endpoints/generateAltText.ts"],"sourcesContent":["import type { PayloadHandler, PayloadRequest } from 'payload'\n\nimport { APIError } from 'payload'\nimport { ZodError } from 'zod'\n\nimport type { AltTextPluginConfig } from '../types/AltTextPluginConfig.js'\n\nimport { getUnsupportedSourceMimeTypeError, matchesMimeType } from '../utilities/mimeTypes.js'\nimport { formatZodError, generateAltTextRequestSchema } from './schemas.js'\n\n/**\n * Generates alt text for a single image using the configured resolver.\n *\n * By default, returns the result without updating the document (preview mode).\n * Pass `update: true` in the request body to also persist the generated alt text\n * and keywords to the document — useful for programmatic/agent workflows.\n *\n * The response always includes the `id` and `collection` for easy correlation.\n */\nexport const generateAltTextEndpoint =\n  (access: AltTextPluginConfig['access']): PayloadHandler =>\n  async (req: PayloadRequest) => {\n    try {\n      if (!(await access({ req }))) {\n        return Response.json({ error: 'Unauthorized' }, { status: 401 })\n      }\n\n      const data = 'json' in req && typeof req.json === 'function' ? await req.json() : null\n\n      const { id, collection, locale, update } = generateAltTextRequestSchema.parse(data)\n\n      const pluginConfig = req.payload.config.custom?.altTextPluginConfig as\n        AltTextPluginConfig | undefined\n\n      if (!pluginConfig) {\n        return Response.json({ error: 'Plugin config not found' }, { status: 500 })\n      }\n\n      // Treat the configured collections as an allowlist. Reject any other\n      // collection before touching the Local API, so the endpoint can only ever\n      // operate on the upload collections the plugin manages.\n      const collectionConfig = pluginConfig.collections.find((entry) => entry.slug === collection)\n\n      if (!collectionConfig) {\n        return Response.json(\n          { error: `Collection \"${collection}\" is not managed by the alt text plugin.` },\n          { status: 403 },\n        )\n      }\n\n      const imageDoc = await req.payload.findByID({\n        id,\n        collection,\n        depth: 0,\n        // Run under the requesting user's access, not Payload's default\n        // `overrideAccess: true`, so collection-level access control applies.\n        overrideAccess: false,\n        user: req.user,\n      })\n\n      if (!imageDoc) {\n        return Response.json({ error: 'Image not found' }, { status: 404 })\n      }\n\n      if (!pluginConfig.getImageThumbnail) {\n        return Response.json(\n          { error: 'getImageThumbnail function not configured' },\n          { status: 500 },\n        )\n      }\n\n      if (!pluginConfig.resolver) {\n        return Response.json({ error: 'No alt text resolver configured' }, { status: 500 })\n      }\n\n      const mimeType =\n        'mimeType' in imageDoc && typeof imageDoc.mimeType === 'string'\n          ? imageDoc.mimeType\n          : undefined\n\n      if (mimeType && !matchesMimeType(mimeType, collectionConfig.mimeTypes)) {\n        return Response.json(\n          {\n            error: `Alt text is not tracked for files of type \"${mimeType}\" in the \"${collection}\" collection. Tracked types: ${collectionConfig.mimeTypes.join(', ')}.`,\n          },\n          { status: 400 },\n        )\n      }\n\n      const unsupportedSourceError = getUnsupportedSourceMimeTypeError({\n        declaredThumbnailMimeType: collectionConfig.imageThumbnailMimeType,\n        mimeType,\n        supportedMimeTypes: pluginConfig.resolver.supportedMimeTypes,\n      })\n      if (unsupportedSourceError) {\n        return Response.json({ error: unsupportedSourceError }, { status: 400 })\n      }\n\n      // When localization is enabled, the requested locale must be one of the\n      // configured locales. Reject anything else before it can be written to an\n      // unconfigured locale or interpolated into the resolver's prompt.\n      if (\n        locale != null &&\n        pluginConfig.locales.length > 0 &&\n        !pluginConfig.locales.includes(locale)\n      ) {\n        return Response.json(\n          {\n            error: `Locale \"${locale}\" is not configured. Configured locales: ${pluginConfig.locales.join(', ')}.`,\n          },\n          { status: 400 },\n        )\n      }\n\n      // determine target locale\n      const targetLocale = locale ?? pluginConfig.locale\n      if (!targetLocale) {\n        return Response.json(\n          {\n            error:\n              'Could not determine target locale for alt text generation. Please check your plugin configuration.',\n          },\n          { status: 500 },\n        )\n      }\n\n      const imageThumbnailUrl = await pluginConfig.getImageThumbnail(imageDoc, { collection, req })\n\n      const result = await pluginConfig.resolver.resolve({\n        filename:\n          'filename' in imageDoc && typeof imageDoc.filename === 'string'\n            ? imageDoc.filename\n            : undefined,\n        imageThumbnailMimeType: collectionConfig.imageThumbnailMimeType,\n        imageThumbnailUrl,\n        locale: targetLocale,\n        req,\n      })\n\n      if (!result.success) {\n        return Response.json(\n          { error: result.error || 'Failed to generate alt text' },\n          { status: 500 },\n        )\n      }\n\n      if (update) {\n        await req.payload.update({\n          id,\n          collection,\n          data: {\n            alt: result.result.altText,\n            keywords: result.result.keywords,\n          },\n          locale: targetLocale,\n          // Run under the requesting user's access, not Payload's default\n          // `overrideAccess: true`, so collection-level access control applies.\n          overrideAccess: false,\n          user: req.user,\n        })\n      }\n\n      return Response.json({ id, collection, ...result.result })\n    } catch (error) {\n      if (error instanceof ZodError) {\n        return Response.json(formatZodError(error), { status: 400 })\n      }\n      // Surface Payload access errors (Forbidden 403 / NotFound 404) with their\n      // real status so an agent gets an accurate, non-retryable signal instead\n      // of a misleading 500.\n      if (error instanceof APIError) {\n        return Response.json({ error: error.message }, { status: error.status })\n      }\n      req.payload.logger.error({ err: error }, 'Error generating alt text')\n      return Response.json(\n        {\n          error: `Error generating alt text: ${error instanceof Error ? error.message : 'Unknown error'}`,\n        },\n        { status: 500 },\n      )\n    }\n  }\n"],"names":["APIError","ZodError","getUnsupportedSourceMimeTypeError","matchesMimeType","formatZodError","generateAltTextRequestSchema","generateAltTextEndpoint","access","req","Response","json","error","status","data","id","collection","locale","update","parse","pluginConfig","payload","config","custom","altTextPluginConfig","collectionConfig","collections","find","entry","slug","imageDoc","findByID","depth","overrideAccess","user","getImageThumbnail","resolver","mimeType","undefined","mimeTypes","join","unsupportedSourceError","declaredThumbnailMimeType","imageThumbnailMimeType","supportedMimeTypes","locales","length","includes","targetLocale","imageThumbnailUrl","result","resolve","filename","success","alt","altText","keywords","message","logger","err","Error"],"mappings":"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"}