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

package/README.md

@@ -1,16 +1,17 @@
 # Image Alt Text Generation Plugin for Payload CMS
 
-A [Payload CMS](https://payloadcms.com/) plugin that adds AI-powered alt text generation for images. I automatically adds an alt text field with a button to generate the alt text to specified upload collections, and includes a bulk generation feature in the list view for processing multiple images at once.
+A [Payload CMS](https://payloadcms.com/) plugin that adds AI-powered alt text generation for images. It automatically adds an alt text field with a button to generate the alt text to specified upload collections, and includes a bulk generation feature in the list view for processing multiple images at once.
 
 ## Features
 
 - 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 ready-to-use OpenAI and Mistral resolvers 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
+- Bulk generation from the collection list view
 - 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:
 
@@ -21,7 +22,6 @@ When the plugin is enabled for an upload collection, it will:
    - This field will be automatically filled when generating the alt text
    - It will be used for improving the search of images in the admin panel
 3. Add a bulk generate button to the collection list view
-   - This button will allow you to generate alt text for multiple images at once
 4. Register an `Alt text health` dashboard widget
    - Results are cached and revalidated when documents in the configured upload collections change
 
@@ -77,19 +77,20 @@ 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                                                                                                                                                                                                                                                                                              |
-| `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 \| 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`) |
-| `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))                                                                                            |
+| 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       | Disables the plugin entirely when `false` (default: `true`)                                                                                                                                                                                                                                           |
+| `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)                                                                                                                                                                                                                               |
+| `filterLocales`              | `({ locales, req }) => string[] \| Promise<string[]>` | No       | Narrows the locales a request generates for and is measured against — in a multi-tenant CMS, to the locales the selected tenant serves (see [Per-request locales](#per-request-locales))                                                                                                              |
+| `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:
 
@@ -104,9 +105,48 @@ It may also be async, so the URL can be signed on demand:
 getImageThumbnail: async (doc, { req }) => await presignThumbnailUrl(String(doc.url), req)
 ```
 
+### Per-request locales
+
+Payload's locale list is config-wide. A multi-tenant project therefore configures the union of every tenant's locales — and without narrowing, every tenant is served all of them: a bulk generation writes (and pays for) locales the tenant does not serve, and the health report counts its images as incomplete until locales it will never publish are filled.
+
+`filterLocales` narrows that list per request:
+
+```ts
+import { getTenantFromCookie } from '@payloadcms/plugin-multi-tenant/utilities'
+
+filterLocales: async ({ locales, req }) => {
+  const tenantId = getTenantFromCookie(req.headers, req.payload.db.defaultIDType)
+
+  // No tenant selected: every configured locale, matching the tenant selector.
+  if (!tenantId) {
+    return locales
+  }
+
+  const tenant = await req.payload.findByID({
+    id: tenantId,
+    collection: 'tenants',
+    depth: 0,
+    req,
+    select: { locales: true },
+  })
+
+  return tenant?.locales?.length ? tenant.locales : locales
+}
+```
+
+It governs all three locale-dependent behaviors:
+
+| Behavior                       | Effect                                                                                      |
+| ------------------------------ | ------------------------------------------------------------------------------------------- |
+| `POST /alt-text/generate/bulk` | Generates and writes only the admitted locales                                              |
+| `POST /alt-text/generate`      | Rejects a request `locale` outside them with `400`, before the resolver runs                |
+| Health report and widget       | Counts a document complete once the admitted locales are filled, and scopes its cache entry |
+
+The returned codes must be a non-empty subset of the configured locales; anything else fails the request rather than writing into a locale the project does not define. Omit the option and every request targets the full configured list — no call is made, so a project that does not scope locales pays nothing for it.
+
 ### 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:
+Each entry in `collections` may be either a bare collection slug or an object with the following fields:
 
 | Option                   | Type                      | Required | Description                                                                                                                                                                                       |
 | ------------------------ | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -118,7 +158,7 @@ Each entry in `collections` may be either a bare collection slug (shorthand, def
 ```ts
 payloadAltTextPlugin({
   collections: [
-    'images', // shorthand — defaults to mimeTypes: ['image/*']
+    'images', // shorthand
     { slug: 'media', mimeTypes: ['image/*', 'application/pdf'] },
   ],
   // ...
@@ -141,7 +181,7 @@ payloadAltTextPlugin({
 })
 ```
 
-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.
+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.
 
@@ -205,6 +245,34 @@ 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. Omitting `baseFilter` entirely does the same for every collection.
+
+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.
+
+Which locales a document is measured against is scoped separately, by [`filterLocales`](#per-request-locales).
+
 #### 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:
@@ -219,9 +287,13 @@ await payload.create({
 
 ### Resolvers
 
-This plugin is designed to work seamlessly with various AI providers by accepting a customizable resolver as a configuration option.
+Three resolvers ship with the plugin — [OpenAI](#openai-resolver),
+[Mistral](#mistral-resolver) and [Anthropic](#anthropic-resolver) — and any other
+provider can be used by writing your own.
 
-An OpenAI resolver is provided out of the box, but you can use any AI provider by creating your own resolver and specifying it in the plugin configuration.
+They differ in how the image reaches the provider: the OpenAI resolver passes the
+thumbnail URL, the Mistral and Anthropic resolvers download the image and send
+the bytes.
 
 #### OpenAI Resolver
 
@@ -234,12 +306,18 @@ openAIResolver({
 })
 ```
 
+OpenAI fetches the thumbnail URL itself, so it must be reachable from the public
+internet. If it is not, use [`mistralResolver`](#mistral-resolver) or
+[`anthropicResolver`](#anthropic-resolver), which send the bytes instead.
+
 | 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 (e.g. Nebius, Azure)                                                                                                                             |
+| `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
 
@@ -252,22 +330,125 @@ mistralResolver({
 })
 ```
 
-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
+})
+```
+
+`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.
 
-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.
+```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 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'
@@ -314,7 +495,7 @@ That default fits a setup where every Payload user is trusted staff. Generating
 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 the `healthCheck` function).
+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`
 
@@ -342,7 +523,7 @@ Generates alt text for a single image. By default, returns the result without sa
 
 ### `POST /api/alt-text/generate/bulk`
 
-Generates and persists alt text for multiple images across all configured locales.
+Generates and persists alt text for multiple images across every target locale (see [Per-request locales](#per-request-locales)).
 
 **Request body:**
 
@@ -355,12 +536,20 @@ Generates and persists alt text for multiple images across all configured locale
 
 ```json
 {
-  "updatedDocs": 5,
+  "updatedDocs": 4,
   "totalDocs": 6,
-  "erroredDocs": ["abc789"]
+  "erroredDocs": ["abc789"],
+  "skippedDocs": [{ "id": "def456", "reason": "notTracked" }]
 }
 ```
 
+`skippedDocs` holds the documents no provider call was made for. They are reported separately from `erroredDocs` because they are not failures of the run — a selection covering a whole list view routinely contains a few — and each carries the reason, which decides what the editor has to do:
+
+| Reason              | Meaning                                                                                         |
+| ------------------- | ----------------------------------------------------------------------------------------------- |
+| `notTracked`        | The collection does not track this file type, so it needs no alt text at all                    |
+| `unsupportedFormat` | A tracked file whose format the resolver cannot read — it still needs alt text, written by hand |
+
 ### `GET /api/alt-text/health`
 
 Returns alt text coverage statistics across all configured collections. Only available when `healthCheck` is enabled.

package/dist/components/BulkGenerateAltTextsButton.js

@@ -6,6 +6,7 @@ import { useTransition } from 'react';
 import { PLUGIN_SLUG } from '../constants.js';
 import { Lightning } from './icons/Lightning.js';
 import { Spinner } from './icons/Spinner.js';
+import { summarizeBulkGenerate } from './summarizeBulkGenerate.js';
 export function BulkGenerateAltTextsButton({ collectionSlug }) {
     const { t } = useTranslation();
     const [isPending, startTransition] = useTransition();
@@ -33,22 +34,8 @@ export function BulkGenerateAltTextsButton({ collectionSlug }) {
                     return;
                 }
                 const data = await response.json();
-                if (data.erroredDocs.length > 0) {
-                    toast.error(t('@jhb.software/payload-alt-text-plugin:failedToGenerateForXImages', {
-                        count: data.erroredDocs.length
-                    }));
-                }
-                // in case not all images were updated, show a warning instead of a success message:
-                if (data.updatedDocs === data.totalDocs) {
-                    toast.success(t('@jhb.software/payload-alt-text-plugin:xOfYImagesUpdated', {
-                        total: data.totalDocs,
-                        updated: data.updatedDocs
-                    }));
-                } else {
-                    toast.warning(t('@jhb.software/payload-alt-text-plugin:xOfYImagesUpdated', {
-                        total: data.totalDocs,
-                        updated: data.updatedDocs
-                    }));
+                for (const { severity, translationKey, variables } of summarizeBulkGenerate(data)){
+                    toast[severity](t(`@jhb.software/payload-alt-text-plugin:${translationKey}`, variables));
                 }
                 // deselect all previously selected images
                 for (const id of selectedIds){

package/dist/components/BulkGenerateAltTextsButton.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/BulkGenerateAltTextsButton.tsx"],"sourcesContent":["'use client'\n\nimport { Button, toast, useAuth, useConfig, useSelection, useTranslation } from '@payloadcms/ui'\nimport { useRouter } from 'next/navigation.js'\nimport { useTransition } from 'react'\n\nimport type {\n  PluginAltTextTranslationKeys,\n  PluginAltTextTranslations,\n} from '../translations/index.js'\n\nimport { PLUGIN_SLUG } from '../constants.js'\nimport { Lightning } from './icons/Lightning.js'\nimport { Spinner } from './icons/Spinner.js'\n\nexport function BulkGenerateAltTextsButton({ collectionSlug }: { collectionSlug: string }) {\n  const { t } = useTranslation<PluginAltTextTranslations, PluginAltTextTranslationKeys>()\n  const [isPending, startTransition] = useTransition()\n  const { permissions } = useAuth()\n  const { selected, setSelection } = useSelection()\n\n  const canUpdateCollection = Boolean(permissions?.collections?.[collectionSlug]?.update)\n  const {\n    config: {\n      routes: { api: apiRoute },\n      serverURL,\n    },\n  } = useConfig()\n\n  const selectedIds = Array.from(selected.entries())\n    .filter(([, isSelected]) => isSelected)\n    .map(([id]) => id) as string[]\n\n  const router = useRouter()\n\n  const handleGenerateAltTexts = () => {\n    startTransition(async () => {\n      if (!collectionSlug) {\n        throw new Error('Collection slug is required')\n      }\n\n      try {\n        const response = await fetch(`${serverURL ?? ''}${apiRoute}/${PLUGIN_SLUG}/generate/bulk`, {\n          body: JSON.stringify({\n            collection: collectionSlug,\n            ids: selectedIds,\n          }),\n          method: 'POST',\n        })\n\n        if (!response.ok) {\n          toast.error(t('@jhb.software/payload-alt-text-plugin:failedToGenerate'))\n          return\n        }\n\n        const data = (await response.json()) as {\n          erroredDocs: string[]\n          totalDocs: number\n          updatedDocs: number\n        }\n\n        if (data.erroredDocs.length > 0) {\n          toast.error(\n            t('@jhb.software/payload-alt-text-plugin:failedToGenerateForXImages', {\n              count: data.erroredDocs.length,\n            }),\n          )\n        }\n\n        // in case not all images were updated, show a warning instead of a success message:\n        if (data.updatedDocs === data.totalDocs) {\n          toast.success(\n            t('@jhb.software/payload-alt-text-plugin:xOfYImagesUpdated', {\n              total: data.totalDocs,\n              updated: data.updatedDocs,\n            }),\n          )\n        } else {\n          toast.warning(\n            t('@jhb.software/payload-alt-text-plugin:xOfYImagesUpdated', {\n              total: data.totalDocs,\n              updated: data.updatedDocs,\n            }),\n          )\n        }\n\n        // deselect all previously selected images\n        for (const id of selectedIds) {\n          setSelection(id)\n        }\n\n        router.refresh()\n      } catch (error) {\n        console.error('Error generating alt text:', error)\n        toast.error(t('@jhb.software/payload-alt-text-plugin:errorGeneratingAltText'))\n      }\n    })\n  }\n\n  return (\n    canUpdateCollection &&\n    selectedIds.length > 0 && (\n      <div className=\"m-0\" style={{ display: 'flex', justifyContent: 'right' }}>\n        <Button\n          className=\"m-0\"\n          disabled={isPending || selectedIds.length === 0}\n          icon={isPending ? <Spinner /> : <Lightning />}\n          onClick={handleGenerateAltTexts}\n        >\n          {t('@jhb.software/payload-alt-text-plugin:generateAltTextFor', {\n            count: selectedIds.length,\n          })}\n        </Button>\n      </div>\n    )\n  )\n}\n"],"names":["Button","toast","useAuth","useConfig","useSelection","useTranslation","useRouter","useTransition","PLUGIN_SLUG","Lightning","Spinner","BulkGenerateAltTextsButton","collectionSlug","t","isPending","startTransition","permissions","selected","setSelection","canUpdateCollection","Boolean","collections","update","config","routes","api","apiRoute","serverURL","selectedIds","Array","from","entries","filter","isSelected","map","id","router","handleGenerateAltTexts","Error","response","fetch","body","JSON","stringify","collection","ids","method","ok","error","data","json","erroredDocs","length","count","updatedDocs","totalDocs","success","total","updated","warning","refresh","console","div","className","style","display","justifyContent","disabled","icon","onClick"],"mappings":"AAAA;;AAEA,SAASA,MAAM,EAAEC,KAAK,EAAEC,OAAO,EAAEC,SAAS,EAAEC,YAAY,EAAEC,cAAc,QAAQ,iBAAgB;AAChG,SAASC,SAAS,QAAQ,qBAAoB;AAC9C,SAASC,aAAa,QAAQ,QAAO;AAOrC,SAASC,WAAW,QAAQ,kBAAiB;AAC7C,SAASC,SAAS,QAAQ,uBAAsB;AAChD,SAASC,OAAO,QAAQ,qBAAoB;AAE5C,OAAO,SAASC,2BAA2B,EAAEC,cAAc,EAA8B;IACvF,MAAM,EAAEC,CAAC,EAAE,GAAGR;IACd,MAAM,CAACS,WAAWC,gBAAgB,GAAGR;IACrC,MAAM,EAAES,WAAW,EAAE,GAAGd;IACxB,MAAM,EAAEe,QAAQ,EAAEC,YAAY,EAAE,GAAGd;IAEnC,MAAMe,sBAAsBC,QAAQJ,aAAaK,aAAa,CAACT,eAAe,EAAEU;IAChF,MAAM,EACJC,QAAQ,EACNC,QAAQ,EAAEC,KAAKC,QAAQ,EAAE,EACzBC,SAAS,EACV,EACF,GAAGxB;IAEJ,MAAMyB,cAAcC,MAAMC,IAAI,CAACb,SAASc,OAAO,IAC5CC,MAAM,CAAC,CAAC,GAAGC,WAAW,GAAKA,YAC3BC,GAAG,CAAC,CAAC,CAACC,GAAG,GAAKA;IAEjB,MAAMC,SAAS9B;IAEf,MAAM+B,yBAAyB;QAC7BtB,gBAAgB;YACd,IAAI,CAACH,gBAAgB;gBACnB,MAAM,IAAI0B,MAAM;YAClB;YAEA,IAAI;gBACF,MAAMC,WAAW,MAAMC,MAAM,GAAGb,aAAa,KAAKD,SAAS,CAAC,EAAElB,YAAY,cAAc,CAAC,EAAE;oBACzFiC,MAAMC,KAAKC,SAAS,CAAC;wBACnBC,YAAYhC;wBACZiC,KAAKjB;oBACP;oBACAkB,QAAQ;gBACV;gBAEA,IAAI,CAACP,SAASQ,EAAE,EAAE;oBAChB9C,MAAM+C,KAAK,CAACnC,EAAE;oBACd;gBACF;gBAEA,MAAMoC,OAAQ,MAAMV,SAASW,IAAI;gBAMjC,IAAID,KAAKE,WAAW,CAACC,MAAM,GAAG,GAAG;oBAC/BnD,MAAM+C,KAAK,CACTnC,EAAE,oEAAoE;wBACpEwC,OAAOJ,KAAKE,WAAW,CAACC,MAAM;oBAChC;gBAEJ;gBAEA,oFAAoF;gBACpF,IAAIH,KAAKK,WAAW,KAAKL,KAAKM,SAAS,EAAE;oBACvCtD,MAAMuD,OAAO,CACX3C,EAAE,2DAA2D;wBAC3D4C,OAAOR,KAAKM,SAAS;wBACrBG,SAAST,KAAKK,WAAW;oBAC3B;gBAEJ,OAAO;oBACLrD,MAAM0D,OAAO,CACX9C,EAAE,2DAA2D;wBAC3D4C,OAAOR,KAAKM,SAAS;wBACrBG,SAAST,KAAKK,WAAW;oBAC3B;gBAEJ;gBAEA,0CAA0C;gBAC1C,KAAK,MAAMnB,MAAMP,YAAa;oBAC5BV,aAAaiB;gBACf;gBAEAC,OAAOwB,OAAO;YAChB,EAAE,OAAOZ,OAAO;gBACda,QAAQb,KAAK,CAAC,8BAA8BA;gBAC5C/C,MAAM+C,KAAK,CAACnC,EAAE;YAChB;QACF;IACF;IAEA,OACEM,uBACAS,YAAYwB,MAAM,GAAG,mBACnB,KAACU;QAAIC,WAAU;QAAMC,OAAO;YAAEC,SAAS;YAAQC,gBAAgB;QAAQ;kBACrE,cAAA,KAAClE;YACC+D,WAAU;YACVI,UAAUrD,aAAac,YAAYwB,MAAM,KAAK;YAC9CgB,MAAMtD,0BAAY,KAACJ,6BAAa,KAACD;YACjC4D,SAAShC;sBAERxB,EAAE,4DAA4D;gBAC7DwC,OAAOzB,YAAYwB,MAAM;YAC3B;;;AAKV"}
+{"version":3,"sources":["../../src/components/BulkGenerateAltTextsButton.tsx"],"sourcesContent":["'use client'\n\nimport { Button, toast, useAuth, useConfig, useSelection, useTranslation } from '@payloadcms/ui'\nimport { useRouter } from 'next/navigation.js'\nimport { useTransition } from 'react'\n\nimport type {\n  PluginAltTextTranslationKeys,\n  PluginAltTextTranslations,\n} from '../translations/index.js'\nimport type { BulkGenerateResult } from './summarizeBulkGenerate.js'\n\nimport { PLUGIN_SLUG } from '../constants.js'\nimport { Lightning } from './icons/Lightning.js'\nimport { Spinner } from './icons/Spinner.js'\nimport { summarizeBulkGenerate } from './summarizeBulkGenerate.js'\n\nexport function BulkGenerateAltTextsButton({ collectionSlug }: { collectionSlug: string }) {\n  const { t } = useTranslation<PluginAltTextTranslations, PluginAltTextTranslationKeys>()\n  const [isPending, startTransition] = useTransition()\n  const { permissions } = useAuth()\n  const { selected, setSelection } = useSelection()\n\n  const canUpdateCollection = Boolean(permissions?.collections?.[collectionSlug]?.update)\n  const {\n    config: {\n      routes: { api: apiRoute },\n      serverURL,\n    },\n  } = useConfig()\n\n  const selectedIds = Array.from(selected.entries())\n    .filter(([, isSelected]) => isSelected)\n    .map(([id]) => id) as string[]\n\n  const router = useRouter()\n\n  const handleGenerateAltTexts = () => {\n    startTransition(async () => {\n      if (!collectionSlug) {\n        throw new Error('Collection slug is required')\n      }\n\n      try {\n        const response = await fetch(`${serverURL ?? ''}${apiRoute}/${PLUGIN_SLUG}/generate/bulk`, {\n          body: JSON.stringify({\n            collection: collectionSlug,\n            ids: selectedIds,\n          }),\n          method: 'POST',\n        })\n\n        if (!response.ok) {\n          toast.error(t('@jhb.software/payload-alt-text-plugin:failedToGenerate'))\n          return\n        }\n\n        const data = (await response.json()) as BulkGenerateResult\n\n        for (const { severity, translationKey, variables } of summarizeBulkGenerate(data)) {\n          toast[severity](t(`@jhb.software/payload-alt-text-plugin:${translationKey}`, variables))\n        }\n\n        // deselect all previously selected images\n        for (const id of selectedIds) {\n          setSelection(id)\n        }\n\n        router.refresh()\n      } catch (error) {\n        console.error('Error generating alt text:', error)\n        toast.error(t('@jhb.software/payload-alt-text-plugin:errorGeneratingAltText'))\n      }\n    })\n  }\n\n  return (\n    canUpdateCollection &&\n    selectedIds.length > 0 && (\n      <div className=\"m-0\" style={{ display: 'flex', justifyContent: 'right' }}>\n        <Button\n          className=\"m-0\"\n          disabled={isPending || selectedIds.length === 0}\n          icon={isPending ? <Spinner /> : <Lightning />}\n          onClick={handleGenerateAltTexts}\n        >\n          {t('@jhb.software/payload-alt-text-plugin:generateAltTextFor', {\n            count: selectedIds.length,\n          })}\n        </Button>\n      </div>\n    )\n  )\n}\n"],"names":["Button","toast","useAuth","useConfig","useSelection","useTranslation","useRouter","useTransition","PLUGIN_SLUG","Lightning","Spinner","summarizeBulkGenerate","BulkGenerateAltTextsButton","collectionSlug","t","isPending","startTransition","permissions","selected","setSelection","canUpdateCollection","Boolean","collections","update","config","routes","api","apiRoute","serverURL","selectedIds","Array","from","entries","filter","isSelected","map","id","router","handleGenerateAltTexts","Error","response","fetch","body","JSON","stringify","collection","ids","method","ok","error","data","json","severity","translationKey","variables","refresh","console","length","div","className","style","display","justifyContent","disabled","icon","onClick","count"],"mappings":"AAAA;;AAEA,SAASA,MAAM,EAAEC,KAAK,EAAEC,OAAO,EAAEC,SAAS,EAAEC,YAAY,EAAEC,cAAc,QAAQ,iBAAgB;AAChG,SAASC,SAAS,QAAQ,qBAAoB;AAC9C,SAASC,aAAa,QAAQ,QAAO;AAQrC,SAASC,WAAW,QAAQ,kBAAiB;AAC7C,SAASC,SAAS,QAAQ,uBAAsB;AAChD,SAASC,OAAO,QAAQ,qBAAoB;AAC5C,SAASC,qBAAqB,QAAQ,6BAA4B;AAElE,OAAO,SAASC,2BAA2B,EAAEC,cAAc,EAA8B;IACvF,MAAM,EAAEC,CAAC,EAAE,GAAGT;IACd,MAAM,CAACU,WAAWC,gBAAgB,GAAGT;IACrC,MAAM,EAAEU,WAAW,EAAE,GAAGf;IACxB,MAAM,EAAEgB,QAAQ,EAAEC,YAAY,EAAE,GAAGf;IAEnC,MAAMgB,sBAAsBC,QAAQJ,aAAaK,aAAa,CAACT,eAAe,EAAEU;IAChF,MAAM,EACJC,QAAQ,EACNC,QAAQ,EAAEC,KAAKC,QAAQ,EAAE,EACzBC,SAAS,EACV,EACF,GAAGzB;IAEJ,MAAM0B,cAAcC,MAAMC,IAAI,CAACb,SAASc,OAAO,IAC5CC,MAAM,CAAC,CAAC,GAAGC,WAAW,GAAKA,YAC3BC,GAAG,CAAC,CAAC,CAACC,GAAG,GAAKA;IAEjB,MAAMC,SAAS/B;IAEf,MAAMgC,yBAAyB;QAC7BtB,gBAAgB;YACd,IAAI,CAACH,gBAAgB;gBACnB,MAAM,IAAI0B,MAAM;YAClB;YAEA,IAAI;gBACF,MAAMC,WAAW,MAAMC,MAAM,GAAGb,aAAa,KAAKD,SAAS,CAAC,EAAEnB,YAAY,cAAc,CAAC,EAAE;oBACzFkC,MAAMC,KAAKC,SAAS,CAAC;wBACnBC,YAAYhC;wBACZiC,KAAKjB;oBACP;oBACAkB,QAAQ;gBACV;gBAEA,IAAI,CAACP,SAASQ,EAAE,EAAE;oBAChB/C,MAAMgD,KAAK,CAACnC,EAAE;oBACd;gBACF;gBAEA,MAAMoC,OAAQ,MAAMV,SAASW,IAAI;gBAEjC,KAAK,MAAM,EAAEC,QAAQ,EAAEC,cAAc,EAAEC,SAAS,EAAE,IAAI3C,sBAAsBuC,MAAO;oBACjFjD,KAAK,CAACmD,SAAS,CAACtC,EAAE,CAAC,sCAAsC,EAAEuC,gBAAgB,EAAEC;gBAC/E;gBAEA,0CAA0C;gBAC1C,KAAK,MAAMlB,MAAMP,YAAa;oBAC5BV,aAAaiB;gBACf;gBAEAC,OAAOkB,OAAO;YAChB,EAAE,OAAON,OAAO;gBACdO,QAAQP,KAAK,CAAC,8BAA8BA;gBAC5ChD,MAAMgD,KAAK,CAACnC,EAAE;YAChB;QACF;IACF;IAEA,OACEM,uBACAS,YAAY4B,MAAM,GAAG,mBACnB,KAACC;QAAIC,WAAU;QAAMC,OAAO;YAAEC,SAAS;YAAQC,gBAAgB;QAAQ;kBACrE,cAAA,KAAC9D;YACC2D,WAAU;YACVI,UAAUhD,aAAac,YAAY4B,MAAM,KAAK;YAC9CO,MAAMjD,0BAAY,KAACL,6BAAa,KAACD;YACjCwD,SAAS3B;sBAERxB,EAAE,4DAA4D;gBAC7DoD,OAAOrC,YAAY4B,MAAM;YAC3B;;;AAKV"}

package/dist/components/summarizeBulkGenerate.d.ts

@@ -0,0 +1,26 @@
+import type { SkippedDoc } from '../endpoints/bulkGenerateAltTexts.js';
+export type BulkGenerateResult = {
+    erroredDocs: (number | string)[];
+    skippedDocs: SkippedDoc[];
+    totalDocs: number;
+    updatedDocs: number;
+};
+export type BulkGenerateToast = {
+    severity: 'error' | 'info' | 'success' | 'warning';
+    translationKey: 'failedToGenerateForXImages' | 'skippedNoAltTextNeeded' | 'skippedUnsupportedFormat' | 'xOfYImagesUpdated';
+    variables: {
+        count: number;
+        total?: number;
+        updated?: number;
+    };
+};
+/**
+ * What a finished bulk run tells the editor, in the order it is told.
+ *
+ * Skipped files were never candidates, so they are reported on their own terms
+ * — by what the editor has to do about each — and left out of the count the run
+ * is measured against. A run whose selection skipped away entirely has no
+ * result to report: "0 of 0 images updated" reads as a failure of work that
+ * never existed.
+ */
+export declare function summarizeBulkGenerate({ erroredDocs, skippedDocs, totalDocs, updatedDocs, }: BulkGenerateResult): BulkGenerateToast[];

package/dist/components/summarizeBulkGenerate.js

@@ -0,0 +1,56 @@
+/**
+ * What a finished bulk run tells the editor, in the order it is told.
+ *
+ * Skipped files were never candidates, so they are reported on their own terms
+ * — by what the editor has to do about each — and left out of the count the run
+ * is measured against. A run whose selection skipped away entirely has no
+ * result to report: "0 of 0 images updated" reads as a failure of work that
+ * never existed.
+ */ export function summarizeBulkGenerate({ erroredDocs, skippedDocs, totalDocs, updatedDocs }) {
+    const toasts = [];
+    if (erroredDocs.length > 0) {
+        toasts.push({
+            severity: 'error',
+            translationKey: 'failedToGenerateForXImages',
+            variables: {
+                count: erroredDocs.length
+            }
+        });
+    }
+    const notTracked = skippedDocs.filter((doc)=>doc.reason === 'notTracked').length;
+    const unsupported = skippedDocs.length - notTracked;
+    if (notTracked > 0) {
+        toasts.push({
+            severity: 'info',
+            translationKey: 'skippedNoAltTextNeeded',
+            variables: {
+                count: notTracked
+            }
+        });
+    }
+    // Needs alt text, just not from a model — so it is the editor's to write.
+    if (unsupported > 0) {
+        toasts.push({
+            severity: 'warning',
+            translationKey: 'skippedUnsupportedFormat',
+            variables: {
+                count: unsupported
+            }
+        });
+    }
+    const attempted = totalDocs - skippedDocs.length;
+    if (attempted > 0) {
+        toasts.push({
+            severity: updatedDocs === attempted ? 'success' : 'warning',
+            translationKey: 'xOfYImagesUpdated',
+            variables: {
+                count: attempted,
+                total: attempted,
+                updated: updatedDocs
+            }
+        });
+    }
+    return toasts;
+}
+
+//# sourceMappingURL=summarizeBulkGenerate.js.map

package/dist/components/summarizeBulkGenerate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/summarizeBulkGenerate.ts"],"sourcesContent":["import type { SkippedDoc } from '../endpoints/bulkGenerateAltTexts.js'\n\nexport type BulkGenerateResult = {\n  erroredDocs: (number | string)[]\n  skippedDocs: SkippedDoc[]\n  totalDocs: number\n  updatedDocs: number\n}\n\nexport type BulkGenerateToast = {\n  severity: 'error' | 'info' | 'success' | 'warning'\n  translationKey:\n    | 'failedToGenerateForXImages'\n    | 'skippedNoAltTextNeeded'\n    | 'skippedUnsupportedFormat'\n    | 'xOfYImagesUpdated'\n  variables: { count: number; total?: number; updated?: number }\n}\n\n/**\n * What a finished bulk run tells the editor, in the order it is told.\n *\n * Skipped files were never candidates, so they are reported on their own terms\n * — by what the editor has to do about each — and left out of the count the run\n * is measured against. A run whose selection skipped away entirely has no\n * result to report: \"0 of 0 images updated\" reads as a failure of work that\n * never existed.\n */\nexport function summarizeBulkGenerate({\n  erroredDocs,\n  skippedDocs,\n  totalDocs,\n  updatedDocs,\n}: BulkGenerateResult): BulkGenerateToast[] {\n  const toasts: BulkGenerateToast[] = []\n\n  if (erroredDocs.length > 0) {\n    toasts.push({\n      severity: 'error',\n      translationKey: 'failedToGenerateForXImages',\n      variables: { count: erroredDocs.length },\n    })\n  }\n\n  const notTracked = skippedDocs.filter((doc) => doc.reason === 'notTracked').length\n  const unsupported = skippedDocs.length - notTracked\n\n  if (notTracked > 0) {\n    toasts.push({\n      severity: 'info',\n      translationKey: 'skippedNoAltTextNeeded',\n      variables: { count: notTracked },\n    })\n  }\n\n  // Needs alt text, just not from a model — so it is the editor's to write.\n  if (unsupported > 0) {\n    toasts.push({\n      severity: 'warning',\n      translationKey: 'skippedUnsupportedFormat',\n      variables: { count: unsupported },\n    })\n  }\n\n  const attempted = totalDocs - skippedDocs.length\n\n  if (attempted > 0) {\n    toasts.push({\n      severity: updatedDocs === attempted ? 'success' : 'warning',\n      translationKey: 'xOfYImagesUpdated',\n      variables: { count: attempted, total: attempted, updated: updatedDocs },\n    })\n  }\n\n  return toasts\n}\n"],"names":["summarizeBulkGenerate","erroredDocs","skippedDocs","totalDocs","updatedDocs","toasts","length","push","severity","translationKey","variables","count","notTracked","filter","doc","reason","unsupported","attempted","total","updated"],"mappings":"AAmBA;;;;;;;;CAQC,GACD,OAAO,SAASA,sBAAsB,EACpCC,WAAW,EACXC,WAAW,EACXC,SAAS,EACTC,WAAW,EACQ;IACnB,MAAMC,SAA8B,EAAE;IAEtC,IAAIJ,YAAYK,MAAM,GAAG,GAAG;QAC1BD,OAAOE,IAAI,CAAC;YACVC,UAAU;YACVC,gBAAgB;YAChBC,WAAW;gBAAEC,OAAOV,YAAYK,MAAM;YAAC;QACzC;IACF;IAEA,MAAMM,aAAaV,YAAYW,MAAM,CAAC,CAACC,MAAQA,IAAIC,MAAM,KAAK,cAAcT,MAAM;IAClF,MAAMU,cAAcd,YAAYI,MAAM,GAAGM;IAEzC,IAAIA,aAAa,GAAG;QAClBP,OAAOE,IAAI,CAAC;YACVC,UAAU;YACVC,gBAAgB;YAChBC,WAAW;gBAAEC,OAAOC;YAAW;QACjC;IACF;IAEA,0EAA0E;IAC1E,IAAII,cAAc,GAAG;QACnBX,OAAOE,IAAI,CAAC;YACVC,UAAU;YACVC,gBAAgB;YAChBC,WAAW;gBAAEC,OAAOK;YAAY;QAClC;IACF;IAEA,MAAMC,YAAYd,YAAYD,YAAYI,MAAM;IAEhD,IAAIW,YAAY,GAAG;QACjBZ,OAAOE,IAAI,CAAC;YACVC,UAAUJ,gBAAgBa,YAAY,YAAY;YAClDR,gBAAgB;YAChBC,WAAW;gBAAEC,OAAOM;gBAAWC,OAAOD;gBAAWE,SAASf;YAAY;QACxE;IACF;IAEA,OAAOC;AACT"}

package/dist/endpoints/bulkGenerateAltTexts.d.ts

@@ -1,6 +1,23 @@
 import type { PayloadHandler } from 'payload';
 import type { AltTextPluginConfig } from '../types/AltTextPluginConfig.js';
 /**
- * Generates and updates alt text for multiple images in all locales.
+ * Generates and updates alt text for multiple images in all target locales.
+ *
+ * Files nothing can be generated for are reported as `skippedDocs` rather than
+ * `erroredDocs` — burying them among real failures hides those — each with the
+ * reason that decides what the editor has to do next. See {@link SkipReason}.
  */
 export declare const bulkGenerateAltTextsEndpoint: (access: AltTextPluginConfig["access"]) => PayloadHandler;
+/**
+ * Why a document was left alone.
+ *
+ * - `notTracked` — the collection does not track this file type, so it needs no
+ *   alt text at all.
+ * - `unsupportedFormat` — a tracked file whose format the resolver cannot read.
+ *   It still needs alt text; an editor has to write it.
+ */
+export type SkipReason = 'notTracked' | 'unsupportedFormat';
+export type SkippedDoc = {
+    id: number | string;
+    reason: SkipReason;
+};