@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/content-patcher.js

@@ -0,0 +1,293 @@
+import { deserializeLexicalTree } from '../lexical/deserializer.js';
+import { getValueAtPath } from './content-extractor.js';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * @param base Merge base — target-locale-first state that will be mutated
+ *   (via structured clone) and returned with translated leaves written in.
+ *   This was previously misleadingly called `sourceDoc`; it's the BASE that
+ *   accumulates translated text on top of prior target-locale state.
+ * @param translatedUnits Map of unitId → translated text.
+ * @param fields Translatable field descriptors.
+ * @param sourceDoc The TRUE source-locale doc. Read-only. Used to recover
+ *   structural skeletons (e.g. Lexical trees) when the base's target-locale
+ *   row is empty or otherwise missing the source shape — without this the
+ *   deserializer walks an empty/stale skeleton and discards source structure.
+ */ export function patchTranslatedContent(base, translatedUnits, fields, sourceDoc) {
+    const patched = structuredClone(base);
+    for (const field of fields){
+        switch(field.type){
+            case 'text':
+            case 'textarea':
+                {
+                    const unitId = `${field.path}::0`;
+                    const translated = translatedUnits.get(unitId);
+                    if (translated !== undefined) {
+                        setValueAtPath(patched, field.path, translated);
+                    }
+                    break;
+                }
+            case 'richText':
+                {
+                    // Structure comes from the TRUE source, not the merge base. The base
+                    // for a fresh target locale is often an empty-Lexical skeleton from
+                    // findByIdNoFallback (Payload returns the default editor state), and
+                    // walking that would discard source headings, lists, links, formatting.
+                    const originalValue = getValueAtPath(sourceDoc, field.path);
+                    if (!isLexicalRoot(originalValue)) break;
+                    // Collect all block units belonging to this field
+                    const blockMap = collectFieldUnits(field.path, translatedUnits);
+                    if (blockMap.size === 0) break;
+                    const rebuilt = deserializeLexicalTree(originalValue, blockMap);
+                    setValueAtPath(patched, field.path, rebuilt);
+                    break;
+                }
+            case 'json':
+                {
+                    // Seed from the TRUE source when available — when the source's
+                    // JSON shape changes between publishes (different top-level
+                    // keys, new nesting), reading from `patched` walks the OLD
+                    // target shape and translations land nowhere. Falls back to
+                    // `patched` when sourceDoc doesn't expose the path (legacy
+                    // callers, tests, or paths the caller composes manually) so the
+                    // previous behavior is preserved.
+                    const seedFromSource = getValueAtPath(sourceDoc, field.path);
+                    const seed = seedFromSource !== undefined && seedFromSource !== null ? seedFromSource : getValueAtPath(patched, field.path);
+                    if (seed === null || typeof seed !== 'object' || Array.isArray(seed)) break;
+                    const jsonClone = structuredClone(seed);
+                    patchJsonValues(jsonClone, field.path, translatedUnits);
+                    setValueAtPath(patched, field.path, jsonClone);
+                    break;
+                }
+            case 'group':
+                {
+                    const value = getValueAtPath(patched, field.path);
+                    if (!value || typeof value !== 'object' || Array.isArray(value)) break;
+                    patchGroupLeaves(value, field.path, fields, translatedUnits, sourceDoc);
+                    break;
+                }
+            case 'array':
+                {
+                    const value = getValueAtPath(patched, field.path);
+                    if (!Array.isArray(value)) break;
+                    patchArrayItems(value, field.path, fields, translatedUnits, sourceDoc);
+                    break;
+                }
+            case 'blocks':
+                {
+                    const value = getValueAtPath(patched, field.path);
+                    if (!Array.isArray(value)) break;
+                    patchBlockItems(value, field.path, translatedUnits, sourceDoc);
+                    break;
+                }
+        }
+    }
+    return patched;
+}
+// ---------------------------------------------------------------------------
+// JSON patcher
+// ---------------------------------------------------------------------------
+function patchJsonValues(obj, basePath, translatedUnits) {
+    for (const [key, value] of Object.entries(obj)){
+        const fieldPath = `${basePath}.${key}`;
+        const unitId = `${fieldPath}::0`;
+        const translated = translatedUnits.get(unitId);
+        if (translated !== undefined) {
+            obj[key] = translated;
+        } else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+            patchJsonValues(value, fieldPath, translatedUnits);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Container patchers
+// ---------------------------------------------------------------------------
+function patchGroupLeaves(groupValue, groupPath, allFields, translatedUnits, sourceDoc) {
+    const childLeaves = allFields.filter((f)=>f.path.startsWith(`${groupPath}.`) && (f.type === 'text' || f.type === 'textarea' || f.type === 'richText' || f.type === 'json'));
+    for (const leaf of childLeaves){
+        const relativePath = leaf.path.slice(groupPath.length + 1);
+        if (leaf.type === 'text' || leaf.type === 'textarea') {
+            const unitId = `${leaf.path}::0`;
+            const translated = translatedUnits.get(unitId);
+            if (translated !== undefined) {
+                setValueAtPath(groupValue, relativePath, translated);
+            }
+        } else if (leaf.type === 'richText') {
+            const originalValue = getValueAtPath(sourceDoc, leaf.path);
+            if (!isLexicalRoot(originalValue)) continue;
+            const blockMap = collectFieldUnits(leaf.path, translatedUnits);
+            if (blockMap.size === 0) continue;
+            const rebuilt = deserializeLexicalTree(originalValue, blockMap);
+            setValueAtPath(groupValue, relativePath, rebuilt);
+        } else if (leaf.type === 'json') {
+            // Group-nested JSON: seed from source when available, fall back to
+            // the current target value otherwise. Same reasoning as the
+            // top-level `case 'json'` — source-first propagates schema
+            // changes; target-fallback keeps the previous behavior for paths
+            // sourceDoc doesn't expose.
+            const seedFromSource = getValueAtPath(sourceDoc, leaf.path);
+            const seed = seedFromSource !== undefined && seedFromSource !== null ? seedFromSource : getValueAtPath(groupValue, relativePath);
+            if (seed === null || typeof seed !== 'object' || Array.isArray(seed)) continue;
+            const jsonClone = structuredClone(seed);
+            patchJsonValues(jsonClone, leaf.path, translatedUnits);
+            setValueAtPath(groupValue, relativePath, jsonClone);
+        }
+    }
+}
+function patchArrayItems(items, arrayPath, allFields, translatedUnits, sourceDoc) {
+    const childLeaves = allFields.filter((f)=>f.path.startsWith(`${arrayPath}.`) && (f.type === 'text' || f.type === 'textarea' || f.type === 'richText') && !pathTraversesNestedArray(f.path, arrayPath, allFields));
+    const nestedContainers = allFields.filter((f)=>f.path.startsWith(`${arrayPath}.`) && (f.type === 'array' || f.type === 'blocks') && !pathTraversesNestedArray(f.path, arrayPath, allFields));
+    for(let i = 0; i < items.length; i++){
+        const item = items[i];
+        if (!item || typeof item !== 'object') continue;
+        for (const leaf of childLeaves){
+            const relativePath = leaf.path.slice(arrayPath.length + 1);
+            const indexedPath = `${arrayPath}.${i}.${relativePath}`;
+            if (leaf.type === 'text' || leaf.type === 'textarea') {
+                const unitId = `${indexedPath}::0`;
+                const translated = translatedUnits.get(unitId);
+                if (translated !== undefined) {
+                    setValueAtPath(item, relativePath, translated);
+                }
+            } else if (leaf.type === 'richText') {
+                const originalValue = getValueAtPath(sourceDoc, indexedPath);
+                if (!isLexicalRoot(originalValue)) continue;
+                const blockMap = collectFieldUnits(indexedPath, translatedUnits);
+                if (blockMap.size === 0) continue;
+                const rebuilt = deserializeLexicalTree(originalValue, blockMap);
+                setValueAtPath(item, relativePath, rebuilt);
+            }
+        }
+        for (const container of nestedContainers){
+            const relativePath = container.path.slice(arrayPath.length + 1);
+            const indexedContainerPath = `${arrayPath}.${i}.${relativePath}`;
+            const nestedValue = getValueAtPath(item, relativePath);
+            if (!Array.isArray(nestedValue)) continue;
+            const mappedFields = remapFieldsUnderPath(allFields, container.path, indexedContainerPath);
+            if (container.type === 'array') {
+                patchArrayItems(nestedValue, indexedContainerPath, mappedFields, translatedUnits, sourceDoc);
+            } else {
+                patchBlockItems(nestedValue, indexedContainerPath, translatedUnits, sourceDoc);
+            }
+        }
+    }
+}
+function pathTraversesNestedArray(path, containerPath, allFields) {
+    for (const f of allFields){
+        if (f.type !== 'array' && f.type !== 'blocks') continue;
+        if (f.path === containerPath) continue;
+        if (!f.path.startsWith(`${containerPath}.`)) continue;
+        if (path.startsWith(`${f.path}.`)) return true;
+    }
+    return false;
+}
+function remapFieldsUnderPath(allFields, fromPath, toPath) {
+    return allFields.filter((f)=>f.path === fromPath || f.path.startsWith(`${fromPath}.`)).map((f)=>({
+            ...f,
+            path: toPath + f.path.slice(fromPath.length)
+        }));
+}
+function patchBlockItems(blocks, blocksPath, translatedUnits, sourceDoc) {
+    for(let i = 0; i < blocks.length; i++){
+        const block = blocks[i];
+        if (!block || typeof block !== 'object') continue;
+        const prefix = `${blocksPath}.${i}`;
+        patchBlockFields(block, prefix, translatedUnits, sourceDoc);
+    }
+}
+function patchBlockFields(obj, pathPrefix, translatedUnits, sourceDoc) {
+    for (const [key, value] of Object.entries(obj)){
+        if (key === 'id' || key === 'blockType' || key === 'blockName') continue;
+        const fieldPath = `${pathPrefix}.${key}`;
+        if (typeof value === 'string') {
+            const unitId = `${fieldPath}::0`;
+            const translated = translatedUnits.get(unitId);
+            if (translated !== undefined) {
+                obj[key] = translated;
+            }
+        } else if (isLexicalRoot(value)) {
+            const originalValue = getValueAtPath(sourceDoc, fieldPath);
+            if (!isLexicalRoot(originalValue)) continue;
+            const blockMap = collectFieldUnits(fieldPath, translatedUnits);
+            if (blockMap.size === 0) continue;
+            obj[key] = deserializeLexicalTree(originalValue, blockMap);
+        } else if (Array.isArray(value)) {
+            for(let i = 0; i < value.length; i++){
+                const item = value[i];
+                if (item && typeof item === 'object' && !Array.isArray(item)) {
+                    patchBlockFields(item, `${fieldPath}.${i}`, translatedUnits, sourceDoc);
+                } else if (typeof item === 'string' && item.trim().length > 0) {
+                    // Mirror of extractor: strings inside arrays (e.g. JSON `tags`)
+                    // are translated at indexed paths.
+                    const translated = translatedUnits.get(`${fieldPath}.${i}::0`);
+                    if (translated !== undefined) {
+                        value[i] = translated;
+                    }
+                }
+            }
+        } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            patchBlockFields(value, fieldPath, translatedUnits, sourceDoc);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Path utilities
+// ---------------------------------------------------------------------------
+export function setValueAtPath(obj, path, value) {
+    const segments = path.split('.');
+    let current = obj;
+    for(let i = 0; i < segments.length - 1; i++){
+        const segment = segments[i];
+        const nextSegment = segments[i + 1];
+        const isNextIndex = /^\d+$/.test(nextSegment);
+        if (current[segment] === undefined || current[segment] === null) {
+            current[segment] = isNextIndex ? [] : {};
+        }
+        const next = current[segment];
+        if (Array.isArray(next)) {
+            const index = Number(nextSegment);
+            if (Number.isNaN(index)) return;
+            // Ensure the array is large enough
+            while(next.length <= index){
+                next.push(undefined);
+            }
+            if (i + 1 === segments.length - 2) {
+            // Next iteration will be the final segment set
+            }
+            if (next[index] === undefined || next[index] === null) {
+                const afterNext = segments[i + 2];
+                next[index] = afterNext && /^\d+$/.test(afterNext) ? [] : {};
+            }
+            current = next[index];
+            i++; // skip the index segment
+        } else if (typeof next === 'object') {
+            current = next;
+        } else {
+            // Can't traverse further
+            return;
+        }
+    }
+    const lastSegment = segments[segments.length - 1];
+    current[lastSegment] = value;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function collectFieldUnits(fieldPath, translatedUnits) {
+    const prefix = `${fieldPath}::`;
+    const blockMap = new Map();
+    for (const [id, text] of translatedUnits){
+        if (id.startsWith(prefix)) {
+            // Extract the blockId part after the field path prefix
+            const blockId = id.slice(prefix.length);
+            blockMap.set(blockId, text);
+        }
+    }
+    return blockMap;
+}
+function isLexicalRoot(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const obj = value;
+    return 'root' in obj && obj.root !== null && typeof obj.root === 'object';
+}

package/dist/lib/cost-guards.d.ts

@@ -0,0 +1,2 @@
+export declare function checkPerCallLimit(chars: number, limit: number): void;
+export declare function checkPerDocLimit(totalChars: number, ceiling: number): void;

package/dist/lib/cost-guards.js

@@ -0,0 +1,18 @@
+export function checkPerCallLimit(chars, limit) {
+    if (chars > limit) {
+        const err = new Error(`Per-call character limit exceeded: ${chars} > ${limit}`);
+        err.code = 'PER_CALL_LIMIT';
+        err.characterCount = chars;
+        err.limit = limit;
+        throw err;
+    }
+}
+export function checkPerDocLimit(totalChars, ceiling) {
+    if (totalChars > ceiling) {
+        const err = new Error(`Per-document character ceiling exceeded: ${totalChars} > ${ceiling}`);
+        err.code = 'PER_DOC_CEILING';
+        err.characterCount = totalChars;
+        err.limit = ceiling;
+        throw err;
+    }
+}

package/dist/lib/daily-spend-cap.d.ts

@@ -0,0 +1,58 @@
+import type { Payload } from 'payload';
+export type DailySpendCapResult = {
+    allowed: true;
+    todaySpentUsd: number;
+    remainingUsd: number;
+    capUsd: number;
+} | {
+    allowed: false;
+    reason: 'cap_exceeded' | 'invalid_estimate';
+    todaySpentUsd: number;
+    remainingUsd: number;
+    capUsd: number;
+    message: string;
+};
+export interface DailySpendCapOptions {
+    /**
+     * Override the env-var cap. Used by the bulk plugin config so
+     * consumers can pin a different cap without touching env. If both
+     * env and option are set, the option wins.
+     */
+    capUsd?: number;
+    /**
+     * Distinguishes spend rows when multiple plugin consumers share a
+     * single database (rare). Defaults to `'default'`.
+     */
+    consumerKey?: string;
+    /**
+     * Override slug if the consumer renamed the collection.
+     */
+    collectionSlug?: string;
+    /**
+     * Override the date (UTC ISO YYYY-MM-DD) for testing. Production
+     * code should leave this undefined to use today's date.
+     */
+    dateOverride?: string;
+}
+/**
+ * Check whether `estimatedCostUsd` would push today's spend past the
+ * configured cap. On `allowed`, atomically increments the day's
+ * running total. On `!allowed`, leaves state unchanged.
+ *
+ * Idempotency note: this is NOT idempotent. Callers must call exactly
+ * once per request that will actually fire a translation. The bulk
+ * endpoint calls it at enqueue time before queueing tasks; the per-
+ * doc retry endpoint calls it at HTTP entry. The plugin coalesce
+ * path calls it at hook entry before dispatching to the LLM.
+ */
+export declare function checkAndIncrementDailySpend(payload: Payload, estimatedCostUsd: number | undefined, opt?: DailySpendCapOptions): Promise<DailySpendCapResult>;
+/**
+ * Read-only inspector — exposed for the bulk pre-flight modal which
+ * needs to display remaining budget without incrementing. Does not
+ * touch storage.
+ */
+export declare function getDailySpendStatus(payload: Payload, opt?: DailySpendCapOptions): Promise<{
+    todaySpentUsd: number;
+    remainingUsd: number;
+    capUsd: number;
+}>;

package/dist/lib/daily-spend-cap.js

@@ -0,0 +1,233 @@
+import { DEFAULT_TRANSLATION_DAILY_SPEND_COLLECTION_SLUG } from '../translation-daily-spend-collection.js';
+/**
+ * Daily USD cap utility for translation cost gating.
+ *
+ * Used by all three translate entry points (bulk-translate endpoint,
+ * per-doc retry endpoint, plugin coalesce path) per Decision #13 v2 +
+ * F-SEC-TOTP-BYPASS — the TOTP gate on bulk alone is cosmetic if the
+ * per-doc retry endpoint has no equivalent enforcement. The daily cap
+ * is the real boundary; TOTP becomes friction-not-boundary.
+ *
+ * Reject semantics:
+ *   - `estimatedCostUsd` MUST be a finite number. `undefined` /
+ *     non-finite values reject hard (Decision #29). This forces
+ *     callers to fix the upstream estimate gap rather than silently
+ *     bypassing the cap.
+ *   - Today's spend (`spendUsd`) is summed across all entry points.
+ *     The request's `estimatedCostUsd` is added to the running total;
+ *     if `running + estimate > cap`, the request is rejected and the
+ *     spend row is NOT incremented (the request never happens).
+ *   - Successful checks increment `spendUsd += estimatedCostUsd` and
+ *     `requestCount += 1` atomically via raw SQL upsert.
+ *
+ * The cap value comes from the `BULK_TRANSLATE_DAILY_USD_CAP` env var
+ * (consumer override). Snapshotted into the row at first write of the
+ * day so mid-day env changes don't retroactively shift the limit.
+ */ const DEFAULT_CAP_USD = 50;
+function resolveCap(opt) {
+    if (typeof opt.capUsd === 'number' && Number.isFinite(opt.capUsd)) {
+        return opt.capUsd;
+    }
+    const envRaw = process.env.BULK_TRANSLATE_DAILY_USD_CAP;
+    if (envRaw) {
+        const parsed = Number.parseFloat(envRaw);
+        if (Number.isFinite(parsed) && parsed >= 0) {
+            return parsed;
+        }
+    }
+    return DEFAULT_CAP_USD;
+}
+function todayUtcIso() {
+    // YYYY-MM-DD in UTC. Avoids time-zone drift across Vercel functions
+    // that may run in different regions.
+    return new Date().toISOString().slice(0, 10);
+}
+/**
+ * Check whether `estimatedCostUsd` would push today's spend past the
+ * configured cap. On `allowed`, atomically increments the day's
+ * running total. On `!allowed`, leaves state unchanged.
+ *
+ * Idempotency note: this is NOT idempotent. Callers must call exactly
+ * once per request that will actually fire a translation. The bulk
+ * endpoint calls it at enqueue time before queueing tasks; the per-
+ * doc retry endpoint calls it at HTTP entry. The plugin coalesce
+ * path calls it at hook entry before dispatching to the LLM.
+ */ export async function checkAndIncrementDailySpend(payload, estimatedCostUsd, opt = {}) {
+    const capUsd = resolveCap(opt);
+    const consumerKey = opt.consumerKey ?? 'default';
+    const date = opt.dateOverride ?? todayUtcIso();
+    const slug = opt.collectionSlug ?? DEFAULT_TRANSLATION_DAILY_SPEND_COLLECTION_SLUG;
+    if (typeof estimatedCostUsd !== 'number' || !Number.isFinite(estimatedCostUsd) || estimatedCostUsd < 0) {
+        return {
+            allowed: false,
+            reason: 'invalid_estimate',
+            todaySpentUsd: 0,
+            remainingUsd: capUsd,
+            capUsd,
+            message: 'Translation cost estimate is missing or non-numeric. Refusing to proceed without a valid estimate (Decision #29).'
+        };
+    }
+    // Read today's row. Best-effort — failure here doesn't block the
+    // translation. If the read fails we still try the upsert path below
+    // and let the DB error surface if storage is broken.
+    let todaySpent = 0;
+    try {
+        const result = await payload.find({
+            // biome-ignore lint/suspicious/noExplicitAny: dynamic collection slug
+            collection: slug,
+            where: {
+                and: [
+                    {
+                        date: {
+                            equals: date
+                        }
+                    },
+                    {
+                        consumerKey: {
+                            equals: consumerKey
+                        }
+                    }
+                ]
+            },
+            limit: 1,
+            overrideAccess: true
+        });
+        const existing = result.docs[0];
+        if (existing && typeof existing.spendUsd === 'number') {
+            todaySpent = existing.spendUsd;
+        }
+    } catch  {
+    // Treat as cold day. The upsert below will create the row.
+    }
+    const projected = todaySpent + estimatedCostUsd;
+    if (projected > capUsd) {
+        return {
+            allowed: false,
+            reason: 'cap_exceeded',
+            todaySpentUsd: todaySpent,
+            remainingUsd: Math.max(0, capUsd - todaySpent),
+            capUsd,
+            message: `Daily translation cost cap exceeded: spent $${todaySpent.toFixed(4)}, request adds $${estimatedCostUsd.toFixed(4)}, cap $${capUsd.toFixed(2)}.`
+        };
+    }
+    // Atomic upsert. Uses Payload's `find` + `create` / `update`
+    // pattern as the portable fallback; consumers who want strict
+    // multi-process atomicity can replace this with a raw SQL
+    // `INSERT ... ON CONFLICT DO UPDATE` against the unique
+    // (date, consumer_key) constraint via `payload.db.drizzle`.
+    //
+    // The race window between read-then-write is bounded: the
+    // unique index on (date, consumer_key) ensures only one row
+    // per day, and concurrent increments race-update the same
+    // row's spendUsd — the second increment may briefly over-shoot
+    // the cap, but the cap re-checks on every call so the next
+    // request after the over-shoot will reject. Acceptable for a
+    // cost-cap gate; not acceptable as exact financial tracking.
+    try {
+        const result = await payload.find({
+            // biome-ignore lint/suspicious/noExplicitAny: dynamic collection slug
+            collection: slug,
+            where: {
+                and: [
+                    {
+                        date: {
+                            equals: date
+                        }
+                    },
+                    {
+                        consumerKey: {
+                            equals: consumerKey
+                        }
+                    }
+                ]
+            },
+            limit: 1,
+            overrideAccess: true
+        });
+        const existing = result.docs[0];
+        if (existing) {
+            await payload.update({
+                // biome-ignore lint/suspicious/noExplicitAny: dynamic collection slug
+                collection: slug,
+                id: existing.id,
+                data: {
+                    spendUsd: (existing.spendUsd ?? 0) + estimatedCostUsd,
+                    requestCount: (existing.requestCount ?? 0) + 1,
+                    lastRequestAt: new Date().toISOString()
+                },
+                overrideAccess: true
+            });
+        } else {
+            await payload.create({
+                // biome-ignore lint/suspicious/noExplicitAny: dynamic collection slug
+                collection: slug,
+                data: {
+                    date,
+                    consumerKey,
+                    spendUsd: estimatedCostUsd,
+                    capUsd,
+                    requestCount: 1,
+                    lastRequestAt: new Date().toISOString()
+                },
+                overrideAccess: true
+            });
+        }
+    } catch (err) {
+        payload.logger?.error?.(`[ai-translate] daily-spend-cap upsert failed: ${err instanceof Error ? err.message : String(err)}`);
+    // Don't reject the request just because tracking failed —
+    // the gate already approved based on the read. Tracking is
+    // best-effort. The next request will re-read and may
+    // approve over-cap if this write was lost. Log loudly.
+    }
+    return {
+        allowed: true,
+        todaySpentUsd: projected,
+        remainingUsd: Math.max(0, capUsd - projected),
+        capUsd
+    };
+}
+/**
+ * Read-only inspector — exposed for the bulk pre-flight modal which
+ * needs to display remaining budget without incrementing. Does not
+ * touch storage.
+ */ export async function getDailySpendStatus(payload, opt = {}) {
+    const capUsd = resolveCap(opt);
+    const consumerKey = opt.consumerKey ?? 'default';
+    const date = opt.dateOverride ?? todayUtcIso();
+    const slug = opt.collectionSlug ?? DEFAULT_TRANSLATION_DAILY_SPEND_COLLECTION_SLUG;
+    try {
+        const result = await payload.find({
+            // biome-ignore lint/suspicious/noExplicitAny: dynamic collection slug
+            collection: slug,
+            where: {
+                and: [
+                    {
+                        date: {
+                            equals: date
+                        }
+                    },
+                    {
+                        consumerKey: {
+                            equals: consumerKey
+                        }
+                    }
+                ]
+            },
+            limit: 1,
+            overrideAccess: true
+        });
+        const existing = result.docs[0];
+        const todaySpent = existing && typeof existing.spendUsd === 'number' ? existing.spendUsd : 0;
+        return {
+            todaySpentUsd: todaySpent,
+            remainingUsd: Math.max(0, capUsd - todaySpent),
+            capUsd
+        };
+    } catch  {
+        return {
+            todaySpentUsd: 0,
+            remainingUsd: capUsd,
+            capUsd
+        };
+    }
+}