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

package/dist/resolvers/openAI.js

@@ -1,34 +1,18 @@
-import OpenAI from 'openai';
-import { makeParseableResponseFormat } from 'openai/lib/parser.mjs';
-import { z } from 'zod';
+import { createVisionResolver, VisionProviderError } from './createVisionResolver.js';
 /** @see https://platform.openai.com/docs/guides/images-vision */ const OPENAI_SUPPORTED_MIME_TYPES = [
     'image/jpeg',
     'image/png',
     'image/gif',
     'image/webp'
 ];
-/**
- * Creates a chat completion `JSONSchema` response format object from
- * the given Zod schema.
- *
- * This is a temporary drop in replacement for the zodResponseFormat from openai/helpers/zod.ts
- * because of issue https://github.com/openai/openai-node/issues/1576
- */ function zodResponseFormat(zodObject, name, props) {
-    return makeParseableResponseFormat({
-        type: 'json_schema',
-        json_schema: {
-            ...props,
-            name,
-            schema: z.toJSONSchema(zodObject, {
-                target: 'draft-7'
-            }),
-            strict: true
-        }
-    }, (content)=>zodObject.parse(JSON.parse(content)));
-}
 /**
  * Creates an OpenAI-based resolver for alt text generation.
  *
+ * The thumbnail URL is handed to OpenAI, which fetches it itself — so the URL
+ * has to be reachable from the public internet. Behind a private bucket or in
+ * local development, reach for a resolver that inlines the bytes instead
+ * (`mistralResolver`, `anthropicResolver`).
+ *
  * @example
  * ```typescript
  * import { openAIResolver } from '@jhb.software/payload-alt-text-plugin'
@@ -46,39 +30,15 @@ import { z } from 'zod';
  *   model: 'Qwen/Qwen2.5-VL-72B-Instruct',
  * })
  * ```
- */ export const openAIResolver = (config)=>{
-    const { apiKey, baseUrl, model = 'gpt-4.1-nano' } = config;
-    // Build the client lazily (once, on first use): the `resolver` argument is
-    // evaluated even when the plugin is disabled, so eager construction would
-    // throw on a keyless `enabled: !!process.env.OPENAI_API_KEY` setup.
-    let openai;
-    const getClient = ()=>openai ??= new OpenAI({
-            apiKey,
-            baseURL: baseUrl
-        });
-    return {
-        key: 'openai',
-        resolve: async ({ filename, imageThumbnailUrl, locale })=>{
-            try {
-                const modelResponseSchema = z.object({
-                    altText: z.string().describe('A concise, descriptive alt text for the image'),
-                    keywords: z.array(z.string()).describe('Keywords that describe the content of the image')
-                });
-                const response = await getClient().chat.completions.parse({
-                    max_completion_tokens: 150,
+ */ export const openAIResolver = ({ apiKey, baseUrl = 'https://api.openai.com/v1', instructions, model = 'gpt-4.1-nano', supportedMimeTypes = OPENAI_SUPPORTED_MIME_TYPES, timeoutMs = 30_000 })=>createVisionResolver({
+        apiKey,
+        generate: async ({ filename, imageThumbnailUrl, instructions: resolvedInstructions, maxTokens, responseSchema, signal })=>{
+            const response = await fetch(`${baseUrl}/chat/completions`, {
+                body: JSON.stringify({
+                    max_completion_tokens: maxTokens,
                     messages: [
                         {
-                            content: `
-            You are an expert at analyzing images and creating descriptive image alt text.
-
-            Please analyze the given image and provide the following:
-            - A concise, descriptive alt text (1-2 sentences) as "altText". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.
-            - A list of keywords that describe the content (e.g., ["Camel", "Palm trees", "Desert"]) as "keywords"
-
-            If a context is provided, use it to enhance the alt text.
-
-            Format your response as a JSON object. You must respond in the ${locale} language.
-          `,
+                            content: resolvedInstructions,
                             role: 'system'
                         },
                         {
@@ -100,95 +60,54 @@ import { z } from 'zod';
                         }
                     ],
                     model,
-                    response_format: zodResponseFormat(modelResponseSchema, 'data')
+                    response_format: {
+                        type: 'json_schema',
+                        json_schema: {
+                            name: 'data',
+                            schema: responseSchema,
+                            strict: true
+                        }
+                    }
+                }),
+                headers: {
+                    Authorization: `Bearer ${apiKey}`,
+                    'Content-Type': 'application/json'
+                },
+                method: 'POST',
+                signal
+            });
+            if (!response.ok) {
+                // Bounded: unbounded provider text would land in the log as-is.
+                const body = (await response.text().catch(()=>'')).slice(0, 500);
+                throw new VisionProviderError({
+                    body,
+                    label: 'OpenAI',
+                    status: response.status
                 });
-                const result = response.choices[0]?.message?.parsed;
-                if (!result) {
-                    return {
-                        error: 'No result from OpenAI',
-                        success: false
-                    };
-                }
-                return {
-                    result,
-                    success: true
-                };
-            } catch (error) {
-                console.error('Error generating alt text:', error);
-                return {
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                    success: false
-                };
             }
-        },
-        resolveBulk: async ({ filename, imageThumbnailUrl, locales })=>{
+            const completion = await response.json();
+            const choice = completion.choices?.[0];
+            // A budget exhausted mid-JSON otherwise reaches JSON.parse and reads as
+            // "Unexpected end of JSON input" in the admin panel, which tells an editor
+            // nothing about what to change.
+            if (choice?.finish_reason === 'length') {
+                throw new Error(`OpenAI ran out of tokens before finishing the alt text (max_completion_tokens: ${maxTokens})`);
+            }
+            const content = choice?.message?.content;
+            if (typeof content !== 'string') {
+                throw new Error('No result from OpenAI');
+            }
             try {
-                const modelResponseSchema = z.object(Object.fromEntries(locales.map((locale)=>[
-                        locale,
-                        z.object({
-                            altText: z.string().describe('A concise, descriptive alt text for the image'),
-                            keywords: z.array(z.string()).describe('Keywords that describe the content of the image')
-                        })
-                    ])));
-                const response = await getClient().chat.completions.parse({
-                    max_completion_tokens: 300,
-                    messages: [
-                        {
-                            content: `
-      You are an expert at analyzing images and creating descriptive image alt text.
-
-      Please analyze the given image and provide the following in ${locales.join(', ')}:
-      - A concise, localized descriptive alt text (1-2 sentences) as "altText". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.
-      - A localized list of keywords that describe the content (e.g., ["Camel", "Palm trees", "Desert"]) as "keywords"
-
-      If a context is provided, use it to enhance the alt text.
-
-      Format your response as a JSON object with ${locales.join(', ')} keys, each containing "altText" and "keywords".
-    `,
-                            role: 'system'
-                        },
-                        {
-                            content: [
-                                {
-                                    type: 'image_url',
-                                    image_url: {
-                                        url: imageThumbnailUrl
-                                    }
-                                },
-                                ...filename ? [
-                                    {
-                                        type: 'text',
-                                        text: filename
-                                    }
-                                ] : []
-                            ],
-                            role: 'user'
-                        }
-                    ],
-                    model,
-                    response_format: zodResponseFormat(modelResponseSchema, 'data')
-                });
-                const result = response.choices[0]?.message?.parsed;
-                if (!result) {
-                    return {
-                        error: 'No result from OpenAI',
-                        success: false
-                    };
-                }
-                return {
-                    results: result,
-                    success: true
-                };
-            } catch (error) {
-                console.error('Error generating bulk alt text:', error);
-                return {
-                    error: error instanceof Error ? error.message : 'Unknown error',
-                    success: false
-                };
+                return JSON.parse(content);
+            } catch  {
+                throw new Error('OpenAI returned a response that was not valid JSON');
             }
         },
-        supportedMimeTypes: config.supportedMimeTypes ?? OPENAI_SUPPORTED_MIME_TYPES
-    };
-};
+        instructions,
+        key: 'openai',
+        label: 'OpenAI',
+        supportedMimeTypes,
+        timeoutMs
+    });
 
 //# sourceMappingURL=openAI.js.map

package/dist/resolvers/openAI.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/resolvers/openAI.ts"],"sourcesContent":["import type { AutoParseableResponseFormat } from 'openai/lib/parser.mjs'\nimport type { ChatCompletionContentPartText } from 'openai/resources/chat/completions.mjs'\nimport type { ResponseFormatJSONSchema } from 'openai/resources/shared.mjs'\n\nimport OpenAI from 'openai'\nimport { makeParseableResponseFormat } from 'openai/lib/parser.mjs'\nimport { z } from 'zod'\n\nimport type {\n  AltTextBulkResolverArgs,\n  AltTextBulkResolverResponse,\n  AltTextResolver,\n  AltTextResolverArgs,\n  AltTextResolverResponse,\n} from './types.js'\n\nexport type OpenAIResolverConfig = {\n  /** OpenAI API key for authentication */\n  apiKey: string\n  /**\n   * Base URL for the OpenAI-compatible API.\n   * Use this to point at alternative providers (e.g. Azure, Nebius, local inference).\n   * @default undefined — the OpenAI SDK defaults to 'https://api.openai.com/v1'\n   */\n  baseUrl?: string\n  /**\n   * The OpenAI LLM model to use for alt text generation.\n   * @default 'gpt-4.1-nano'\n   */\n  model?: string\n  /**\n   * The MIME types the provider accepts for the image URL.\n   *\n   * Defaults to the formats documented for OpenAI's vision models. Override it\n   * when pointing `baseUrl` at another provider whose accepted formats differ —\n   * the person choosing the provider is the one who knows.\n   *\n   * @default ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n   */\n  supportedMimeTypes?: string[]\n}\n\n/** @see https://platform.openai.com/docs/guides/images-vision */\nconst OPENAI_SUPPORTED_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n\n/**\n * Creates a chat completion `JSONSchema` response format object from\n * the given Zod schema.\n *\n * This is a temporary drop in replacement for the zodResponseFormat from openai/helpers/zod.ts\n * because of issue https://github.com/openai/openai-node/issues/1576\n */\nfunction zodResponseFormat<ZodInput extends z.ZodType>(\n  zodObject: ZodInput,\n  name: string,\n  props?: Omit<ResponseFormatJSONSchema.JSONSchema, 'name' | 'schema' | 'strict'>,\n): AutoParseableResponseFormat<z.infer<ZodInput>> {\n  return makeParseableResponseFormat(\n    {\n      type: 'json_schema',\n      json_schema: {\n        ...props,\n        name,\n        schema: z.toJSONSchema(zodObject, { target: 'draft-7' }),\n        strict: true,\n      },\n    },\n    (content) => zodObject.parse(JSON.parse(content)),\n  )\n}\n\n/**\n * Creates an OpenAI-based resolver for alt text generation.\n *\n * @example\n * ```typescript\n * import { openAIResolver } from '@jhb.software/payload-alt-text-plugin'\n *\n * // OpenAI\n * openAIResolver({\n *   apiKey: process.env.OPENAI_API_KEY,\n *   model: 'gpt-4.1-mini', // optional, defaults to 'gpt-4.1-nano'\n * })\n *\n * // OpenAI-compatible provider (e.g. Nebius)\n * openAIResolver({\n *   apiKey: process.env.NEBIUS_API_KEY,\n *   baseUrl: 'https://api.tokenfactory.us-central1.nebius.com/v1',\n *   model: 'Qwen/Qwen2.5-VL-72B-Instruct',\n * })\n * ```\n */\nexport const openAIResolver = (config: OpenAIResolverConfig): AltTextResolver => {\n  const { apiKey, baseUrl, model = 'gpt-4.1-nano' } = config\n\n  // Build the client lazily (once, on first use): the `resolver` argument is\n  // evaluated even when the plugin is disabled, so eager construction would\n  // throw on a keyless `enabled: !!process.env.OPENAI_API_KEY` setup.\n  let openai: OpenAI | undefined\n  const getClient = (): OpenAI => (openai ??= new OpenAI({ apiKey, baseURL: baseUrl }))\n\n  return {\n    key: 'openai',\n    resolve: async ({\n      filename,\n      imageThumbnailUrl,\n      locale,\n    }: AltTextResolverArgs): Promise<AltTextResolverResponse> => {\n      try {\n        const modelResponseSchema = z.object({\n          altText: z.string().describe('A concise, descriptive alt text for the image'),\n          keywords: z.array(z.string()).describe('Keywords that describe the content of the image'),\n        })\n\n        const response = await getClient().chat.completions.parse({\n          max_completion_tokens: 150,\n          messages: [\n            {\n              content: `\n            You are an expert at analyzing images and creating descriptive image alt text.\n\n            Please analyze the given image and provide the following:\n            - A concise, descriptive alt text (1-2 sentences) as \"altText\". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.\n            - A list of keywords that describe the content (e.g., [\"Camel\", \"Palm trees\", \"Desert\"]) as \"keywords\"\n\n            If a context is provided, use it to enhance the alt text.\n\n            Format your response as a JSON object. You must respond in the ${locale} language.\n          `,\n              role: 'system',\n            },\n            {\n              content: [\n                {\n                  type: 'image_url',\n                  image_url: { url: imageThumbnailUrl },\n                },\n                ...(filename\n                  ? [\n                      {\n                        type: 'text',\n                        text: filename,\n                      } satisfies ChatCompletionContentPartText,\n                    ]\n                  : []),\n              ],\n              role: 'user',\n            },\n          ],\n          model,\n          response_format: zodResponseFormat(modelResponseSchema, 'data'),\n        })\n\n        const result = response.choices[0]?.message?.parsed\n\n        if (!result) {\n          return { error: 'No result from OpenAI', success: false }\n        }\n\n        return {\n          result,\n          success: true,\n        }\n      } catch (error) {\n        console.error('Error generating alt text:', error)\n        return {\n          error: error instanceof Error ? error.message : 'Unknown error',\n          success: false,\n        }\n      }\n    },\n    resolveBulk: async ({\n      filename,\n      imageThumbnailUrl,\n      locales,\n    }: AltTextBulkResolverArgs): Promise<AltTextBulkResolverResponse> => {\n      try {\n        const modelResponseSchema = z.object(\n          Object.fromEntries(\n            locales.map((locale) => [\n              locale,\n              z.object({\n                altText: z.string().describe('A concise, descriptive alt text for the image'),\n                keywords: z\n                  .array(z.string())\n                  .describe('Keywords that describe the content of the image'),\n              }),\n            ]),\n          ),\n        )\n\n        const response = await getClient().chat.completions.parse({\n          max_completion_tokens: 300,\n          messages: [\n            {\n              content: `\n      You are an expert at analyzing images and creating descriptive image alt text.\n\n      Please analyze the given image and provide the following in ${locales.join(', ')}:\n      - A concise, localized descriptive alt text (1-2 sentences) as \"altText\". Focus on the subject, action, and setting. Avoid phrases like 'Image of', 'A picture of', or 'Photo showing'. Be specific and include relevant details like location or context if visible. Make no assumptions.\n      - A localized list of keywords that describe the content (e.g., [\"Camel\", \"Palm trees\", \"Desert\"]) as \"keywords\"\n\n      If a context is provided, use it to enhance the alt text.\n\n      Format your response as a JSON object with ${locales.join(', ')} keys, each containing \"altText\" and \"keywords\".\n    `,\n              role: 'system',\n            },\n            {\n              content: [\n                {\n                  type: 'image_url',\n                  image_url: { url: imageThumbnailUrl },\n                },\n                ...(filename\n                  ? [\n                      {\n                        type: 'text',\n                        text: filename,\n                      } satisfies ChatCompletionContentPartText,\n                    ]\n                  : []),\n              ],\n              role: 'user',\n            },\n          ],\n          model,\n          response_format: zodResponseFormat(modelResponseSchema, 'data'),\n        })\n\n        const result = response.choices[0]?.message?.parsed\n\n        if (!result) {\n          return { error: 'No result from OpenAI', success: false }\n        }\n\n        return {\n          results: result,\n          success: true,\n        }\n      } catch (error) {\n        console.error('Error generating bulk alt text:', error)\n        return {\n          error: error instanceof Error ? error.message : 'Unknown error',\n          success: false,\n        }\n      }\n    },\n    supportedMimeTypes: config.supportedMimeTypes ?? OPENAI_SUPPORTED_MIME_TYPES,\n  }\n}\n"],"names":["OpenAI","makeParseableResponseFormat","z","OPENAI_SUPPORTED_MIME_TYPES","zodResponseFormat","zodObject","name","props","type","json_schema","schema","toJSONSchema","target","strict","content","parse","JSON","openAIResolver","config","apiKey","baseUrl","model","openai","getClient","baseURL","key","resolve","filename","imageThumbnailUrl","locale","modelResponseSchema","object","altText","string","describe","keywords","array","response","chat","completions","max_completion_tokens","messages","role","image_url","url","text","response_format","result","choices","message","parsed","error","success","console","Error","resolveBulk","locales","Object","fromEntries","map","join","results","supportedMimeTypes"],"mappings":"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"}
+{"version":3,"sources":["../../src/resolvers/openAI.ts"],"sourcesContent":["import type { VisionInstructions } from './createVisionResolver.js'\nimport type { AltTextResolver } from './types.js'\n\nimport { createVisionResolver, VisionProviderError } from './createVisionResolver.js'\n\nexport type OpenAIResolverConfig = {\n  /** OpenAI API key for authentication */\n  apiKey: string\n  /**\n   * Base URL for the OpenAI-compatible API, including the version segment.\n   * Use this to point at alternative providers (e.g. Azure, Nebius, local inference).\n   * @default 'https://api.openai.com/v1'\n   */\n  baseUrl?: string\n  /**\n   * Builds the instructions from the default ones, e.g. to append a house style\n   * rule. Sent as the system message, separately from the image.\n   *\n   * @default ({ defaultInstructions }) => defaultInstructions\n   */\n  instructions?: VisionInstructions\n  /**\n   * The OpenAI LLM model to use for alt text generation.\n   * @default 'gpt-4.1-nano'\n   */\n  model?: string\n  /**\n   * The MIME types the provider accepts for the image URL.\n   *\n   * Defaults to the formats documented for OpenAI's vision models. Override it\n   * when pointing `baseUrl` at another provider whose accepted formats differ —\n   * the person choosing the provider is the one who knows.\n   *\n   * @default ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n   */\n  supportedMimeTypes?: string[]\n  /**\n   * Abort after this many milliseconds, covering the completion call and the\n   * retries the factory makes within it.\n   * @default 30000\n   */\n  timeoutMs?: number\n}\n\n/** @see https://platform.openai.com/docs/guides/images-vision */\nconst OPENAI_SUPPORTED_MIME_TYPES = ['image/jpeg', 'image/png', 'image/gif', 'image/webp']\n\n/**\n * Creates an OpenAI-based resolver for alt text generation.\n *\n * The thumbnail URL is handed to OpenAI, which fetches it itself — so the URL\n * has to be reachable from the public internet. Behind a private bucket or in\n * local development, reach for a resolver that inlines the bytes instead\n * (`mistralResolver`, `anthropicResolver`).\n *\n * @example\n * ```typescript\n * import { openAIResolver } from '@jhb.software/payload-alt-text-plugin'\n *\n * // OpenAI\n * openAIResolver({\n *   apiKey: process.env.OPENAI_API_KEY,\n *   model: 'gpt-4.1-mini', // optional, defaults to 'gpt-4.1-nano'\n * })\n *\n * // OpenAI-compatible provider (e.g. Nebius)\n * openAIResolver({\n *   apiKey: process.env.NEBIUS_API_KEY,\n *   baseUrl: 'https://api.tokenfactory.us-central1.nebius.com/v1',\n *   model: 'Qwen/Qwen2.5-VL-72B-Instruct',\n * })\n * ```\n */\nexport const openAIResolver = ({\n  apiKey,\n  baseUrl = 'https://api.openai.com/v1',\n  instructions,\n  model = 'gpt-4.1-nano',\n  supportedMimeTypes = OPENAI_SUPPORTED_MIME_TYPES,\n  timeoutMs = 30_000,\n}: OpenAIResolverConfig): AltTextResolver =>\n  createVisionResolver({\n    apiKey,\n    generate: async ({\n      filename,\n      imageThumbnailUrl,\n      instructions: resolvedInstructions,\n      maxTokens,\n      responseSchema,\n      signal,\n    }) => {\n      const response = await fetch(`${baseUrl}/chat/completions`, {\n        body: JSON.stringify({\n          max_completion_tokens: maxTokens,\n          messages: [\n            { content: resolvedInstructions, role: 'system' },\n            {\n              content: [\n                { type: 'image_url', image_url: { url: imageThumbnailUrl } },\n                ...(filename ? [{ type: 'text', text: filename }] : []),\n              ],\n              role: 'user',\n            },\n          ],\n          model,\n          response_format: {\n            type: 'json_schema',\n            json_schema: { name: 'data', schema: responseSchema, strict: true },\n          },\n        }),\n        headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },\n        method: 'POST',\n        signal,\n      })\n\n      if (!response.ok) {\n        // Bounded: unbounded provider text would land in the log as-is.\n        const body = (await response.text().catch(() => '')).slice(0, 500)\n\n        throw new VisionProviderError({ body, label: 'OpenAI', status: response.status })\n      }\n\n      const completion = (await response.json()) as {\n        choices?: { finish_reason?: string; message?: { content?: unknown } }[]\n      }\n      const choice = completion.choices?.[0]\n\n      // A budget exhausted mid-JSON otherwise reaches JSON.parse and reads as\n      // \"Unexpected end of JSON input\" in the admin panel, which tells an editor\n      // nothing about what to change.\n      if (choice?.finish_reason === 'length') {\n        throw new Error(\n          `OpenAI ran out of tokens before finishing the alt text (max_completion_tokens: ${maxTokens})`,\n        )\n      }\n\n      const content = choice?.message?.content\n\n      if (typeof content !== 'string') {\n        throw new Error('No result from OpenAI')\n      }\n\n      try {\n        return JSON.parse(content)\n      } catch {\n        throw new Error('OpenAI returned a response that was not valid JSON')\n      }\n    },\n    instructions,\n    key: 'openai',\n    label: 'OpenAI',\n    supportedMimeTypes,\n    timeoutMs,\n  })\n"],"names":["createVisionResolver","VisionProviderError","OPENAI_SUPPORTED_MIME_TYPES","openAIResolver","apiKey","baseUrl","instructions","model","supportedMimeTypes","timeoutMs","generate","filename","imageThumbnailUrl","resolvedInstructions","maxTokens","responseSchema","signal","response","fetch","body","JSON","stringify","max_completion_tokens","messages","content","role","type","image_url","url","text","response_format","json_schema","name","schema","strict","headers","Authorization","method","ok","catch","slice","label","status","completion","json","choice","choices","finish_reason","Error","message","parse","key"],"mappings":"AAGA,SAASA,oBAAoB,EAAEC,mBAAmB,QAAQ,4BAA2B;AAyCrF,+DAA+D,GAC/D,MAAMC,8BAA8B;IAAC;IAAc;IAAa;IAAa;CAAa;AAE1F;;;;;;;;;;;;;;;;;;;;;;;;;CAyBC,GACD,OAAO,MAAMC,iBAAiB,CAAC,EAC7BC,MAAM,EACNC,UAAU,2BAA2B,EACrCC,YAAY,EACZC,QAAQ,cAAc,EACtBC,qBAAqBN,2BAA2B,EAChDO,YAAY,MAAM,EACG,GACrBT,qBAAqB;QACnBI;QACAM,UAAU,OAAO,EACfC,QAAQ,EACRC,iBAAiB,EACjBN,cAAcO,oBAAoB,EAClCC,SAAS,EACTC,cAAc,EACdC,MAAM,EACP;YACC,MAAMC,WAAW,MAAMC,MAAM,GAAGb,QAAQ,iBAAiB,CAAC,EAAE;gBAC1Dc,MAAMC,KAAKC,SAAS,CAAC;oBACnBC,uBAAuBR;oBACvBS,UAAU;wBACR;4BAAEC,SAASX;4BAAsBY,MAAM;wBAAS;wBAChD;4BACED,SAAS;gCACP;oCAAEE,MAAM;oCAAaC,WAAW;wCAAEC,KAAKhB;oCAAkB;gCAAE;mCACvDD,WAAW;oCAAC;wCAAEe,MAAM;wCAAQG,MAAMlB;oCAAS;iCAAE,GAAG,EAAE;6BACvD;4BACDc,MAAM;wBACR;qBACD;oBACDlB;oBACAuB,iBAAiB;wBACfJ,MAAM;wBACNK,aAAa;4BAAEC,MAAM;4BAAQC,QAAQlB;4BAAgBmB,QAAQ;wBAAK;oBACpE;gBACF;gBACAC,SAAS;oBAAEC,eAAe,CAAC,OAAO,EAAEhC,QAAQ;oBAAE,gBAAgB;gBAAmB;gBACjFiC,QAAQ;gBACRrB;YACF;YAEA,IAAI,CAACC,SAASqB,EAAE,EAAE;gBAChB,gEAAgE;gBAChE,MAAMnB,OAAO,AAAC,CAAA,MAAMF,SAASY,IAAI,GAAGU,KAAK,CAAC,IAAM,GAAE,EAAGC,KAAK,CAAC,GAAG;gBAE9D,MAAM,IAAIvC,oBAAoB;oBAAEkB;oBAAMsB,OAAO;oBAAUC,QAAQzB,SAASyB,MAAM;gBAAC;YACjF;YAEA,MAAMC,aAAc,MAAM1B,SAAS2B,IAAI;YAGvC,MAAMC,SAASF,WAAWG,OAAO,EAAE,CAAC,EAAE;YAEtC,wEAAwE;YACxE,2EAA2E;YAC3E,gCAAgC;YAChC,IAAID,QAAQE,kBAAkB,UAAU;gBACtC,MAAM,IAAIC,MACR,CAAC,+EAA+E,EAAElC,UAAU,CAAC,CAAC;YAElG;YAEA,MAAMU,UAAUqB,QAAQI,SAASzB;YAEjC,IAAI,OAAOA,YAAY,UAAU;gBAC/B,MAAM,IAAIwB,MAAM;YAClB;YAEA,IAAI;gBACF,OAAO5B,KAAK8B,KAAK,CAAC1B;YACpB,EAAE,OAAM;gBACN,MAAM,IAAIwB,MAAM;YAClB;QACF;QACA1C;QACA6C,KAAK;QACLV,OAAO;QACPjC;QACAC;IACF,GAAE"}

package/dist/types/AltTextPluginConfig.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionSlug, Field, PayloadRequest } from 'payload';
+import type { CollectionSlug, Field, PayloadRequest, Where } from 'payload';
 import type { AltTextResolver } from '../resolvers/types.js';
 import type { AltTextCollectionConfig, IncomingCollectionsConfig, NormalizedAltTextCollectionConfig } from '../utilities/mimeTypes.js';
 export type { AltTextCollectionConfig, NormalizedAltTextCollectionConfig };
@@ -18,6 +18,47 @@ export type GetImageThumbnail = (doc: Record<string, unknown>, args: {
     collection: CollectionSlug;
     req: PayloadRequest;
 }) => Promise<string> | string;
+/**
+ * Narrows the health scan of one collection to a subset of its documents — in a
+ * multi-tenant CMS, to the tenant the request is for. The returned constraint is
+ * ANDed onto the scan's MIME type filter.
+ *
+ * Called once per configured collection, so collections that do not carry the
+ * constraining field (a media library shared across tenants, say) can return `{}`
+ * instead of being queried for a field they do not have.
+ *
+ * Return `{}` to scan the collection whole.
+ *
+ * @param args.collection The slug of the collection being scanned.
+ * @param args.req The request the scan runs for.
+ */
+export type AltTextHealthBaseFilter = (args: {
+    collection: CollectionSlug;
+    req: PayloadRequest;
+}) => Promise<Where> | Where;
+/** Configuration of the alt text health feature. */
+export type AltTextHealthCheckConfig = {
+    /**
+     * Access control for the health report — both the REST endpoint and the dashboard
+     * widget, which hides itself when this denies.
+     *
+     * Use it to restrict the collection-wide report more strictly than the
+     * per-document generate endpoints (e.g. to admins).
+     *
+     * @default the plugin's `access`
+     */
+    access?: (args: {
+        req: PayloadRequest;
+    }) => boolean | Promise<boolean>;
+    /**
+     * Narrows what the report counts. See {@link AltTextHealthBaseFilter}.
+     *
+     * This is not access control: it scopes the aggregate, it does not decide who
+     * may see it. Use `access` for that, and note the report is always filtered to
+     * the collections the requesting user can read.
+     */
+    baseFilter?: AltTextHealthBaseFilter;
+};
 /** Configuration options for the alt text plugin. */
 export type IncomingAltTextPluginConfig = {
     /**
@@ -65,19 +106,12 @@ export type IncomingAltTextPluginConfig = {
      * Controls the alt text health feature (REST endpoint, cache revalidation hooks, and dashboard widget).
      *
      * - `false` disables the entire feature.
-     * - `true` enables it, gated by `access`.
-     * - A function enables it and gates both the endpoint and the dashboard widget
-     *   with that access check — use this to restrict the collection-wide report
-     *   more strictly than the per-document generate endpoints (e.g. to admins).
-     *
-     * Regardless of the gate, the report is always filtered to the collections the
-     * requesting user can read.
+     * - `true` enables it, gated by `access` and covering every document.
+     * - An object enables it and configures it. See {@link AltTextHealthCheckConfig}.
      *
      * @default true
      */
-    healthCheck?: ((args: {
-        req: PayloadRequest;
-    }) => boolean | Promise<boolean>) | boolean;
+    healthCheck?: AltTextHealthCheckConfig | boolean;
     /**
      * The MIME type `getImageThumbnail` delivers, for every configured collection.
      *
@@ -141,6 +175,8 @@ export type AltTextPluginConfig = {
     healthCheckAccess: (args: {
         req: PayloadRequest;
     }) => boolean | Promise<boolean>;
+    /** Narrows what the health report counts. See {@link AltTextHealthBaseFilter}. */
+    healthCheckBaseFilter?: AltTextHealthBaseFilter;
     /** The locale to generate alt texts in when localization is disabled. */
     locale?: string;
     /** The locales to generate alt texts for. */

package/dist/types/AltTextPluginConfig.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/AltTextPluginConfig.ts"],"sourcesContent":["import type { CollectionSlug, Field, PayloadRequest } from 'payload'\n\nimport type { AltTextResolver } from '../resolvers/types.js'\nimport type {\n  AltTextCollectionConfig,\n  IncomingCollectionsConfig,\n  NormalizedAltTextCollectionConfig,\n} from '../utilities/mimeTypes.js'\n\nexport type { AltTextCollectionConfig, NormalizedAltTextCollectionConfig }\n\n/**\n * Builds the thumbnail URL the resolver fetches. Must be publicly reachable.\n *\n * May be async, so the URL can be signed on demand (S3 presigning, short-lived\n * CDN tokens).\n *\n * @param doc The upload document to build the URL for.\n * @param args.collection The slug of the collection `doc` belongs to — use it to\n * build different URLs per collection (e.g. a Cloudinary transformation for one\n * collection and a plain S3 URL for another).\n * @param args.req The request the generation runs under.\n */\nexport type GetImageThumbnail = (\n  doc: Record<string, unknown>,\n  args: { collection: CollectionSlug; req: PayloadRequest },\n) => Promise<string> | string\n\n/** Configuration options for the alt text plugin. */\nexport type IncomingAltTextPluginConfig = {\n  /**\n   * Custom access control for plugin endpoints.\n   * Return `true` to allow access, `false` to deny.\n   *\n   * @default ({ req }) => !!req.user — requires authentication\n   */\n  access?: (args: { req: PayloadRequest }) => boolean | Promise<boolean>\n\n  /**\n   * Collections to enable the plugin for.\n   *\n   * Each entry may be a bare collection slug or an object with a `slug` and an\n   * optional `mimeTypes` array restricting which MIME types are tracked,\n   * validated, and generated. Bare slugs default to `['image/*']`.\n   *\n   * @example\n   * ```typescript\n   * collections: [\n   *   'images', // shorthand — defaults to ['image/*']\n   *   { slug: 'media', mimeTypes: ['image/*', 'application/pdf'] },\n   * ]\n   * ```\n   */\n  collections: IncomingCollectionsConfig\n\n  /** Whether the plugin is enabled. */\n  enabled?: boolean\n\n  /** Override the default fields inserted by the plugin via a function that receives the default fields and returns the new fields */\n  fieldsOverride?: (args: { defaultFields: Field[] }) => Field[]\n\n  /**\n   * Builds the image URL sent to the resolver. See {@link GetImageThumbnail}.\n   *\n   * @remarks\n   * - Prefer a thumbnail/preview size over the original (e.g. from the sizes field)\n   * - When the URL transcodes, declare the delivered format via\n   *   `imageThumbnailMimeType` so source formats the resolver does not accept are\n   *   not rejected\n   */\n  getImageThumbnail: GetImageThumbnail\n\n  /**\n   * Controls the alt text health feature (REST endpoint, cache revalidation hooks, and dashboard widget).\n   *\n   * - `false` disables the entire feature.\n   * - `true` enables it, gated by `access`.\n   * - A function enables it and gates both the endpoint and the dashboard widget\n   *   with that access check — use this to restrict the collection-wide report\n   *   more strictly than the per-document generate endpoints (e.g. to admins).\n   *\n   * Regardless of the gate, the report is always filtered to the collections the\n   * requesting user can read.\n   *\n   * @default true\n   */\n  healthCheck?: ((args: { req: PayloadRequest }) => boolean | Promise<boolean>) | boolean\n\n  /**\n   * The MIME type `getImageThumbnail` delivers, for every configured collection.\n   *\n   * Declaring it takes a document's stored `mimeType` out of the decision of\n   * whether alt text can be generated. Collections may override it or opt out with\n   * `null` — see {@link AltTextCollectionConfig.imageThumbnailMimeType} for the\n   * rationale and the `f_auto` caveat.\n   *\n   * @example 'image/webp'\n   */\n  imageThumbnailMimeType?: string\n\n  /**\n   * The locale to generate alt texts in when localization is disabled.\n   *\n   * Required when localization is disabled, ignored when localization is enabled.\n   * @example 'en'\n   */\n  locale?: string\n\n  /**\n   * Maximum number of concurrent API requests for bulk generate operations.\n   *\n   * @default 16\n   */\n  maxBulkGenerateConcurrency?: number\n\n  /**\n   * Maximum number of image IDs accepted in a single bulk generate request.\n   * Requests exceeding this are rejected with `400`. Duplicate IDs are collapsed\n   * before the limit is applied, so each image counts once.\n   *\n   * Raise it for large libraries that need to process more images per request.\n   *\n   * @default 100\n   */\n  maxBulkGenerateIds?: number\n\n  /** The resolver to use for generating alt text (e.g., openAIResolver) */\n  resolver: AltTextResolver\n}\n\n/** Configuration of the alt text plugin after defaults have been applied. */\nexport type AltTextPluginConfig = {\n  /** Access control for plugin endpoints. */\n  access: (args: { req: PayloadRequest }) => boolean | Promise<boolean>\n\n  /**\n   * Collections with resolved MIME type filters and resolved delivered thumbnail\n   * MIME types. The plugin-level `imageThumbnailMimeType` is folded into these\n   * entries during normalization, so this is the only place to read it from.\n   */\n  collections: NormalizedAltTextCollectionConfig[]\n\n  /** Whether the plugin is enabled. */\n  enabled: boolean\n\n  /** Override the default fields inserted by the plugin via a function that receives the default fields and returns the new fields */\n  fieldsOverride?: (args: { defaultFields: Field[] }) => Field[]\n\n  /** Function to get the thumbnail URL of an image document. */\n  getImageThumbnail: GetImageThumbnail\n\n  /** Whether alt text health tracking is enabled. */\n  healthCheck: boolean\n\n  /** Access control for the health endpoint. Defaults to `access`. */\n  healthCheckAccess: (args: { req: PayloadRequest }) => boolean | Promise<boolean>\n\n  /** The locale to generate alt texts in when localization is disabled. */\n  locale?: string\n\n  /** The locales to generate alt texts for. */\n  locales: string[]\n\n  /** Maximum number of concurrent API requests for bulk generate operations. */\n  maxBulkGenerateConcurrency: number\n\n  /** Maximum number of image IDs accepted per bulk generate request. */\n  maxBulkGenerateIds: number\n\n  /** The resolver to use for generating alt text */\n  resolver: AltTextResolver\n}\n"],"names":[],"mappings":"AAkIA,2EAA2E,GAC3E,WAwCC"}
+{"version":3,"sources":["../../src/types/AltTextPluginConfig.ts"],"sourcesContent":["import type { CollectionSlug, Field, PayloadRequest, Where } from 'payload'\n\nimport type { AltTextResolver } from '../resolvers/types.js'\nimport type {\n  AltTextCollectionConfig,\n  IncomingCollectionsConfig,\n  NormalizedAltTextCollectionConfig,\n} from '../utilities/mimeTypes.js'\n\nexport type { AltTextCollectionConfig, NormalizedAltTextCollectionConfig }\n\n/**\n * Builds the thumbnail URL the resolver fetches. Must be publicly reachable.\n *\n * May be async, so the URL can be signed on demand (S3 presigning, short-lived\n * CDN tokens).\n *\n * @param doc The upload document to build the URL for.\n * @param args.collection The slug of the collection `doc` belongs to — use it to\n * build different URLs per collection (e.g. a Cloudinary transformation for one\n * collection and a plain S3 URL for another).\n * @param args.req The request the generation runs under.\n */\nexport type GetImageThumbnail = (\n  doc: Record<string, unknown>,\n  args: { collection: CollectionSlug; req: PayloadRequest },\n) => Promise<string> | string\n\n/**\n * Narrows the health scan of one collection to a subset of its documents — in a\n * multi-tenant CMS, to the tenant the request is for. The returned constraint is\n * ANDed onto the scan's MIME type filter.\n *\n * Called once per configured collection, so collections that do not carry the\n * constraining field (a media library shared across tenants, say) can return `{}`\n * instead of being queried for a field they do not have.\n *\n * Return `{}` to scan the collection whole.\n *\n * @param args.collection The slug of the collection being scanned.\n * @param args.req The request the scan runs for.\n */\nexport type AltTextHealthBaseFilter = (args: {\n  collection: CollectionSlug\n  req: PayloadRequest\n}) => Promise<Where> | Where\n\n/** Configuration of the alt text health feature. */\nexport type AltTextHealthCheckConfig = {\n  /**\n   * Access control for the health report — both the REST endpoint and the dashboard\n   * widget, which hides itself when this denies.\n   *\n   * Use it to restrict the collection-wide report more strictly than the\n   * per-document generate endpoints (e.g. to admins).\n   *\n   * @default the plugin's `access`\n   */\n  access?: (args: { req: PayloadRequest }) => boolean | Promise<boolean>\n\n  /**\n   * Narrows what the report counts. See {@link AltTextHealthBaseFilter}.\n   *\n   * This is not access control: it scopes the aggregate, it does not decide who\n   * may see it. Use `access` for that, and note the report is always filtered to\n   * the collections the requesting user can read.\n   */\n  baseFilter?: AltTextHealthBaseFilter\n}\n\n/** Configuration options for the alt text plugin. */\nexport type IncomingAltTextPluginConfig = {\n  /**\n   * Custom access control for plugin endpoints.\n   * Return `true` to allow access, `false` to deny.\n   *\n   * @default ({ req }) => !!req.user — requires authentication\n   */\n  access?: (args: { req: PayloadRequest }) => boolean | Promise<boolean>\n\n  /**\n   * Collections to enable the plugin for.\n   *\n   * Each entry may be a bare collection slug or an object with a `slug` and an\n   * optional `mimeTypes` array restricting which MIME types are tracked,\n   * validated, and generated. Bare slugs default to `['image/*']`.\n   *\n   * @example\n   * ```typescript\n   * collections: [\n   *   'images', // shorthand — defaults to ['image/*']\n   *   { slug: 'media', mimeTypes: ['image/*', 'application/pdf'] },\n   * ]\n   * ```\n   */\n  collections: IncomingCollectionsConfig\n\n  /** Whether the plugin is enabled. */\n  enabled?: boolean\n\n  /** Override the default fields inserted by the plugin via a function that receives the default fields and returns the new fields */\n  fieldsOverride?: (args: { defaultFields: Field[] }) => Field[]\n\n  /**\n   * Builds the image URL sent to the resolver. See {@link GetImageThumbnail}.\n   *\n   * @remarks\n   * - Prefer a thumbnail/preview size over the original (e.g. from the sizes field)\n   * - When the URL transcodes, declare the delivered format via\n   *   `imageThumbnailMimeType` so source formats the resolver does not accept are\n   *   not rejected\n   */\n  getImageThumbnail: GetImageThumbnail\n\n  /**\n   * Controls the alt text health feature (REST endpoint, cache revalidation hooks, and dashboard widget).\n   *\n   * - `false` disables the entire feature.\n   * - `true` enables it, gated by `access` and covering every document.\n   * - An object enables it and configures it. See {@link AltTextHealthCheckConfig}.\n   *\n   * @default true\n   */\n  healthCheck?: AltTextHealthCheckConfig | boolean\n\n  /**\n   * The MIME type `getImageThumbnail` delivers, for every configured collection.\n   *\n   * Declaring it takes a document's stored `mimeType` out of the decision of\n   * whether alt text can be generated. Collections may override it or opt out with\n   * `null` — see {@link AltTextCollectionConfig.imageThumbnailMimeType} for the\n   * rationale and the `f_auto` caveat.\n   *\n   * @example 'image/webp'\n   */\n  imageThumbnailMimeType?: string\n\n  /**\n   * The locale to generate alt texts in when localization is disabled.\n   *\n   * Required when localization is disabled, ignored when localization is enabled.\n   * @example 'en'\n   */\n  locale?: string\n\n  /**\n   * Maximum number of concurrent API requests for bulk generate operations.\n   *\n   * @default 16\n   */\n  maxBulkGenerateConcurrency?: number\n\n  /**\n   * Maximum number of image IDs accepted in a single bulk generate request.\n   * Requests exceeding this are rejected with `400`. Duplicate IDs are collapsed\n   * before the limit is applied, so each image counts once.\n   *\n   * Raise it for large libraries that need to process more images per request.\n   *\n   * @default 100\n   */\n  maxBulkGenerateIds?: number\n\n  /** The resolver to use for generating alt text (e.g., openAIResolver) */\n  resolver: AltTextResolver\n}\n\n/** Configuration of the alt text plugin after defaults have been applied. */\nexport type AltTextPluginConfig = {\n  /** Access control for plugin endpoints. */\n  access: (args: { req: PayloadRequest }) => boolean | Promise<boolean>\n\n  /**\n   * Collections with resolved MIME type filters and resolved delivered thumbnail\n   * MIME types. The plugin-level `imageThumbnailMimeType` is folded into these\n   * entries during normalization, so this is the only place to read it from.\n   */\n  collections: NormalizedAltTextCollectionConfig[]\n\n  /** Whether the plugin is enabled. */\n  enabled: boolean\n\n  /** Override the default fields inserted by the plugin via a function that receives the default fields and returns the new fields */\n  fieldsOverride?: (args: { defaultFields: Field[] }) => Field[]\n\n  /** Function to get the thumbnail URL of an image document. */\n  getImageThumbnail: GetImageThumbnail\n\n  /** Whether alt text health tracking is enabled. */\n  healthCheck: boolean\n\n  /** Access control for the health endpoint. Defaults to `access`. */\n  healthCheckAccess: (args: { req: PayloadRequest }) => boolean | Promise<boolean>\n\n  /** Narrows what the health report counts. See {@link AltTextHealthBaseFilter}. */\n  healthCheckBaseFilter?: AltTextHealthBaseFilter\n\n  /** The locale to generate alt texts in when localization is disabled. */\n  locale?: string\n\n  /** The locales to generate alt texts for. */\n  locales: string[]\n\n  /** Maximum number of concurrent API requests for bulk generate operations. */\n  maxBulkGenerateConcurrency: number\n\n  /** Maximum number of image IDs accepted per bulk generate request. */\n  maxBulkGenerateIds: number\n\n  /** The resolver to use for generating alt text */\n  resolver: AltTextResolver\n}\n"],"names":[],"mappings":"AAuKA,2EAA2E,GAC3E,WA2CC"}

package/dist/utilities/altTextHealth.d.ts

@@ -1,8 +1,9 @@
 import type { PayloadRequest } from 'payload';
+import type { AltTextHealthCacheFactory } from './altTextHealthCache.js';
 export declare const ALT_TEXT_HEALTH_PLUGIN_SLUG = "alt-text";
 export declare const ALT_TEXT_HEALTH_CACHE_TTL = 3600;
 export declare const ALT_TEXT_HEALTH_GLOBAL_TAG = "alt-text-health";
-export type AltTextHealthErrorCode = 'ALT_TEXT_COLLECTION_READ_FAILED' | 'ALT_TEXT_PLUGIN_CONFIG_MISSING';
+export type AltTextHealthErrorCode = 'ALT_TEXT_BASE_FILTER_FAILED' | 'ALT_TEXT_COLLECTION_READ_FAILED' | 'ALT_TEXT_PLUGIN_CONFIG_MISSING';
 export type AltTextHealthError = {
     code: AltTextHealthErrorCode;
     collection?: string;
@@ -33,6 +34,7 @@ export type AltTextHealthWidgetData = {
     totalDocs: number;
 };
 export declare const getAltTextHealthCollectionTag: (collectionSlug: string) => string;
+export declare function getAltTextHealthScan(req: PayloadRequest, cacheFactory?: AltTextHealthCacheFactory<AltTextHealthScan>): Promise<AltTextHealthScan>;
 /**
  * Filters a shared, elevated-access health scan down to the collections the
  * requesting user may read. The scan is computed once with `overrideAccess: true`

package/dist/utilities/altTextHealth.js

@@ -2,6 +2,7 @@ import { unstable_cache } from 'next/cache.js';
 import { createCachedAltTextHealthScan } from './altTextHealthCache.js';
 import { localesFromConfig } from './localesFromConfig.js';
 import { buildMimeTypeWhere } from './mimeTypes.js';
+import { stableStringify } from './stableStringify.js';
 import { summarizeCollection } from './summarizeCollection.js';
 export const ALT_TEXT_HEALTH_PLUGIN_SLUG = 'alt-text';
 export const ALT_TEXT_HEALTH_CACHE_TTL = 3600;
@@ -22,11 +23,20 @@ const createCollectionReadError = (collection, message)=>({
         operation: 'find'
     });
 const PAGE_SIZE = 500;
-async function fetchAllDocs(payload, collection, isLocalized, mimeTypes) {
-    const where = buildMimeTypeWhere(mimeTypes);
-    if (!where) {
+const isEmptyWhere = (where)=>!where || Object.keys(where).length === 0;
+async function fetchAllDocs(payload, collection, isLocalized, mimeTypes, baseFilter) {
+    const mimeTypeWhere = buildMimeTypeWhere(mimeTypes);
+    if (!mimeTypeWhere) {
         return [];
     }
+    // The scan runs with `overrideAccess: true`, so a narrowing constraint has to be
+    // part of the query itself — this is what keeps the aggregate within one tenant.
+    const where = isEmptyWhere(baseFilter) ? mimeTypeWhere : {
+        and: [
+            mimeTypeWhere,
+            baseFilter
+        ]
+    };
     const docs = [];
     let page = 1;
     let hasMore = true;
@@ -55,10 +65,10 @@ async function fetchAllDocs(payload, collection, isLocalized, mimeTypes) {
     }
     return docs;
 }
-async function computeAltTextHealthScan({ collections, isLocalized, localeCodes, payload }) {
+async function computeAltTextHealthScan({ baseFilters, collections, isLocalized, localeCodes, payload }) {
     const collectionSummaries = await Promise.all(collections.map(async ({ slug, mimeTypes })=>{
         try {
-            const docs = await fetchAllDocs(payload, slug, isLocalized, mimeTypes);
+            const docs = await fetchAllDocs(payload, slug, isLocalized, mimeTypes, baseFilters[slug]);
             return summarizeCollection({
                 collection: slug,
                 docs,
@@ -96,7 +106,48 @@ async function computeAltTextHealthScan({ collections, isLocalized, localeCodes,
     };
 }
 export const getAltTextHealthCollectionTag = (collectionSlug)=>`${ALT_TEXT_HEALTH_GLOBAL_TAG}:${collectionSlug}`;
-async function getAltTextHealthScan(req) {
+/**
+ * Resolves the configured base filter for every scanned collection.
+ *
+ * A throwing filter (a tenant cookie pointing at a deleted tenant, say) must not
+ * take the dashboard down, and must never fall back to an unfiltered scan — so it
+ * ends the scan with an error the widget and the endpoint report. The error carries
+ * the slug in its message rather than in `collection`, so it survives the read-access
+ * filter that drops errors for collections the caller cannot read.
+ */ async function resolveBaseFilters(req, collections, baseFilter) {
+    const baseFilters = {};
+    if (!baseFilter) {
+        return {
+            baseFilters
+        };
+    }
+    for (const { slug } of collections){
+        try {
+            baseFilters[slug] = await baseFilter({
+                collection: slug,
+                req
+            });
+        } catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            req.payload.logger.error({
+                collection: slug,
+                err: error,
+                msg: 'Alt text health check failed while resolving the base filter.',
+                plugin: ALT_TEXT_HEALTH_PLUGIN_SLUG
+            });
+            return {
+                error: {
+                    code: 'ALT_TEXT_BASE_FILTER_FAILED',
+                    message: `Failed to resolve the alt text health base filter for the "${slug}" collection: ${message}`
+                }
+            };
+        }
+    }
+    return {
+        baseFilters
+    };
+}
+export async function getAltTextHealthScan(req, cacheFactory = unstable_cache) {
     const { payload } = req;
     const pluginConfig = payload.config.custom?.altTextPluginConfig;
     const localeCodes = localesFromConfig(payload.config) ?? (pluginConfig?.locale ? [
@@ -114,6 +165,15 @@ async function getAltTextHealthScan(req) {
         });
     }
     const collections = pluginConfig.collections;
+    const resolved = await resolveBaseFilters(req, collections, pluginConfig.healthCheckBaseFilter);
+    if ('error' in resolved) {
+        return createUnknownScan({
+            error: resolved.error,
+            isLocalized,
+            localeCodes
+        });
+    }
+    const { baseFilters } = resolved;
     const cacheKeyParts = [
         ALT_TEXT_HEALTH_GLOBAL_TAG,
         [
@@ -121,16 +181,22 @@ async function getAltTextHealthScan(req) {
         ].map(({ slug, mimeTypes })=>`${slug}:${[
                 ...mimeTypes
             ].sort().join('|')}`).sort().join(','),
-        localeCodes.join(',')
+        localeCodes.join(','),
+        // The scan is shared across requests, so a scoped scan needs a scoped cache
+        // entry. Deriving the key from the resolved filters — rather than taking one
+        // from the caller — makes it impossible to narrow the scan without also
+        // narrowing its cache, which would serve one tenant's counts to another.
+        `filter:${stableStringify(baseFilters)}`
     ];
     const tags = [
         ALT_TEXT_HEALTH_GLOBAL_TAG,
         ...new Set(collections.map(({ slug })=>getAltTextHealthCollectionTag(slug)))
     ];
     const getCachedHealthScan = createCachedAltTextHealthScan({
-        cacheFactory: unstable_cache,
+        cacheFactory,
         cacheKeyParts,
         compute: async ()=>computeAltTextHealthScan({
+                baseFilters,
                 collections,
                 isLocalized,
                 localeCodes,