@purposeinplay/payload-ai-translate 0.1.0

package/dist/translation-daily-spend-collection.d.ts

@@ -0,0 +1,24 @@
+import type { Access, CollectionConfig } from 'payload';
+export declare const DEFAULT_TRANSLATION_DAILY_SPEND_COLLECTION_SLUG = "translation-daily-spend";
+/**
+ * One row per (date, consumerKey) tracking aggregate USD spent on
+ * translation that day. Backs the daily-cap enforcement gate
+ * (Decision #14 + F-BIZ-08 + F-SEC-TOTP-BYPASS in
+ * Design-2026-05-27-bulk-translate.md).
+ *
+ * Rows are upserted atomically by the cap utility before each
+ * translation enqueue (bulk + per-doc retry + plugin coalesce paths
+ * per Decision #13 v2). Multi-process safe via SQL `INSERT ... ON
+ * CONFLICT DO UPDATE`, which is required because the totp + bulk
+ * endpoints fan out across Vercel function invocations that each
+ * have isolated in-memory state.
+ *
+ * `consumerKey` is the plugin's `options.usageTracking?.consumerKey
+ * ?? 'default'` and lets a shared-DB deployment with multiple
+ * plugin consumers (rare) keep separate caps per consumer. Default
+ * is `'default'` which works for single-consumer DBs.
+ *
+ * Read access is admin-only. Writes happen only via the cap
+ * utility (Payload `find` + raw SQL upsert via drizzle).
+ */
+export declare function createTranslationDailySpendCollection(readAccess?: Access, slug?: string): CollectionConfig;

package/dist/translation-daily-spend-collection.js

@@ -0,0 +1,133 @@
+export const DEFAULT_TRANSLATION_DAILY_SPEND_COLLECTION_SLUG = 'translation-daily-spend';
+/**
+ * One row per (date, consumerKey) tracking aggregate USD spent on
+ * translation that day. Backs the daily-cap enforcement gate
+ * (Decision #14 + F-BIZ-08 + F-SEC-TOTP-BYPASS in
+ * Design-2026-05-27-bulk-translate.md).
+ *
+ * Rows are upserted atomically by the cap utility before each
+ * translation enqueue (bulk + per-doc retry + plugin coalesce paths
+ * per Decision #13 v2). Multi-process safe via SQL `INSERT ... ON
+ * CONFLICT DO UPDATE`, which is required because the totp + bulk
+ * endpoints fan out across Vercel function invocations that each
+ * have isolated in-memory state.
+ *
+ * `consumerKey` is the plugin's `options.usageTracking?.consumerKey
+ * ?? 'default'` and lets a shared-DB deployment with multiple
+ * plugin consumers (rare) keep separate caps per consumer. Default
+ * is `'default'` which works for single-consumer DBs.
+ *
+ * Read access is admin-only. Writes happen only via the cap
+ * utility (Payload `find` + raw SQL upsert via drizzle).
+ */ export function createTranslationDailySpendCollection(readAccess, slug = DEFAULT_TRANSLATION_DAILY_SPEND_COLLECTION_SLUG) {
+    const isAdminDefault = ({ req })=>{
+        const user = req.user;
+        const roles = user?.roles;
+        if (Array.isArray(roles) && roles.includes('admin')) return true;
+        return false;
+    };
+    return {
+        slug,
+        // System rows are never edited in the admin document view, so
+        // Payload's document-locking buys nothing here — and its lock check
+        // costs a second pool connection inside every update transaction
+        // (core's checkDocumentLockStatus runs a find without `req`). Under
+        // concurrent updates (e.g. dismiss-all on alerts) that exhausted the
+        // pool and deadlocked a consumer in prod on 2026-06-10.
+        lockDocuments: false,
+        labels: {
+            singular: 'Translation Daily Spend',
+            plural: 'Translation Daily Spend Counters'
+        },
+        admin: {
+            group: 'Translation',
+            useAsTitle: 'date',
+            defaultColumns: [
+                'date',
+                'consumerKey',
+                'spendUsd',
+                'capUsd',
+                'requestCount'
+            ],
+            hidden: ({ user })=>{
+                const roles = user?.roles;
+                return !Array.isArray(roles) || !roles.includes('admin');
+            },
+            description: 'Daily aggregate spend counter for the bulk + per-doc translation cost cap. One row per (UTC date, consumer). Updated atomically before each translation enqueue. Read-only in admin; the cap utility owns writes.'
+        },
+        access: {
+            read: readAccess ?? isAdminDefault,
+            create: ()=>false,
+            update: ()=>false,
+            delete: isAdminDefault
+        },
+        fields: [
+            // ISO date string `YYYY-MM-DD` keyed in UTC. Storing as text
+            // (not Date) keeps the equality check trivial for the upsert
+            // and avoids time-zone drift across function invocations.
+            {
+                name: 'date',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'consumerKey',
+                type: 'text',
+                required: true,
+                index: true,
+                defaultValue: 'default',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'spendUsd',
+                type: 'number',
+                required: true,
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'capUsd',
+                type: 'number',
+                admin: {
+                    readOnly: true,
+                    description: 'Cap value snapshotted at row creation. If the env-var cap changes after a day has started, the snapshotted value still applies for that day so admins can predict whether further requests will be allowed.'
+                }
+            },
+            {
+                name: 'requestCount',
+                type: 'number',
+                defaultValue: 0,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                name: 'lastRequestAt',
+                type: 'date',
+                admin: {
+                    readOnly: true
+                }
+            }
+        ],
+        indexes: [
+            // Composite uniqueness for the atomic upsert. Hand-written
+            // migration also adds a Postgres UNIQUE constraint on
+            // (date, consumer_key) to enforce at the DB level.
+            {
+                fields: [
+                    'date',
+                    'consumerKey'
+                ],
+                unique: true
+            }
+        ]
+    };
+}

package/dist/translation-rate-limits-collection.d.ts

@@ -0,0 +1,30 @@
+import type { Access, CollectionConfig } from 'payload';
+export declare const DEFAULT_TRANSLATION_RATE_LIMITS_COLLECTION_SLUG = "translation-rate-limits";
+/**
+ * One row per (provider, model) tracking a Postgres-backed leaky
+ * token bucket against upstream LLM RPM caps. Backs the bulk +
+ * per-doc + coalesce translate paths per Risk R8 + architect §4 in
+ * Design-2026-05-27-bulk-translate.md.
+ *
+ * The legacy in-memory limiter (`lib/rate-limiter.ts`) is per-process
+ * and invisible across Vercel function invocations and server-driven
+ * job workers — multiple instances each get their own bucket, so the
+ * aggregate burst against the upstream provider can be N× the
+ * per-process cap. This collection moves the bucket into Postgres so
+ * every entry point shares the same state.
+ *
+ * Rows are lazily created on first `acquireToken` call for a given
+ * (provider, model). Defaults: capacity=60, refillRatePerSec=1.0
+ * (60 RPM), tunable per-row by admins post-creation. Env-var
+ * overrides (`TRANSLATION_RATE_LIMIT_CAPACITY`,
+ * `TRANSLATION_RATE_LIMIT_REFILL_PER_SEC`) seed the defaults at
+ * lazy-create time only — mid-life rate changes are admin-edits on
+ * the row itself.
+ *
+ * Read access is admin-only. Writes happen only via the token-bucket
+ * utility (Payload `find` + `update` / `create`). Mutability on the
+ * `tokens` / `lastRefillAt` fields is intentional — admins can edit
+ * `capacity` and `refillRatePerSec` to tune limits, but the bucket
+ * state itself is owned by the utility.
+ */
+export declare function createTranslationRateLimitsCollection(readAccess?: Access, slug?: string): CollectionConfig;

package/dist/translation-rate-limits-collection.js

@@ -0,0 +1,144 @@
+export const DEFAULT_TRANSLATION_RATE_LIMITS_COLLECTION_SLUG = 'translation-rate-limits';
+/**
+ * One row per (provider, model) tracking a Postgres-backed leaky
+ * token bucket against upstream LLM RPM caps. Backs the bulk +
+ * per-doc + coalesce translate paths per Risk R8 + architect §4 in
+ * Design-2026-05-27-bulk-translate.md.
+ *
+ * The legacy in-memory limiter (`lib/rate-limiter.ts`) is per-process
+ * and invisible across Vercel function invocations and server-driven
+ * job workers — multiple instances each get their own bucket, so the
+ * aggregate burst against the upstream provider can be N× the
+ * per-process cap. This collection moves the bucket into Postgres so
+ * every entry point shares the same state.
+ *
+ * Rows are lazily created on first `acquireToken` call for a given
+ * (provider, model). Defaults: capacity=60, refillRatePerSec=1.0
+ * (60 RPM), tunable per-row by admins post-creation. Env-var
+ * overrides (`TRANSLATION_RATE_LIMIT_CAPACITY`,
+ * `TRANSLATION_RATE_LIMIT_REFILL_PER_SEC`) seed the defaults at
+ * lazy-create time only — mid-life rate changes are admin-edits on
+ * the row itself.
+ *
+ * Read access is admin-only. Writes happen only via the token-bucket
+ * utility (Payload `find` + `update` / `create`). Mutability on the
+ * `tokens` / `lastRefillAt` fields is intentional — admins can edit
+ * `capacity` and `refillRatePerSec` to tune limits, but the bucket
+ * state itself is owned by the utility.
+ */ export function createTranslationRateLimitsCollection(readAccess, slug = DEFAULT_TRANSLATION_RATE_LIMITS_COLLECTION_SLUG) {
+    const isAdminDefault = ({ req })=>{
+        const user = req.user;
+        const roles = user?.roles;
+        if (Array.isArray(roles) && roles.includes('admin')) return true;
+        return false;
+    };
+    return {
+        slug,
+        // System rows are never edited in the admin document view, so
+        // Payload's document-locking buys nothing here — and its lock check
+        // costs a second pool connection inside every update transaction
+        // (core's checkDocumentLockStatus runs a find without `req`). Under
+        // concurrent updates (e.g. dismiss-all on alerts) that exhausted the
+        // pool and deadlocked a consumer in prod on 2026-06-10.
+        lockDocuments: false,
+        labels: {
+            singular: 'Translation Rate Limit',
+            plural: 'Translation Rate Limits'
+        },
+        admin: {
+            group: 'Translation',
+            useAsTitle: 'model',
+            defaultColumns: [
+                'provider',
+                'model',
+                'tokens',
+                'capacity',
+                'refillRatePerSec',
+                'lastRefillAt'
+            ],
+            hidden: ({ user })=>{
+                const roles = user?.roles;
+                return !Array.isArray(roles) || !roles.includes('admin');
+            },
+            description: 'Postgres-backed leaky token bucket per (provider, model). Throttles bulk + per-doc + coalesce translation paths against upstream LLM RPM caps. Rows are created lazily on first request; admins may tune capacity / refillRatePerSec to match provider plan limits.'
+        },
+        access: {
+            read: readAccess ?? isAdminDefault,
+            create: ()=>false,
+            update: ()=>false,
+            delete: isAdminDefault
+        },
+        fields: [
+            {
+                name: 'provider',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true,
+                    description: 'Provider key — e.g. "openrouter", "anthropic", "openai". Matches the plugin provider id.'
+                }
+            },
+            {
+                name: 'model',
+                type: 'text',
+                required: true,
+                index: true,
+                admin: {
+                    readOnly: true,
+                    description: 'Model id within the provider — e.g. "google/gemini-2.5-flash". The (provider, model) pair is the bucket key.'
+                }
+            },
+            {
+                name: 'tokens',
+                type: 'number',
+                required: true,
+                defaultValue: 0,
+                admin: {
+                    readOnly: true,
+                    description: 'Current remaining tokens in the bucket. Refilled on each acquire based on (now - lastRefillAt) * refillRatePerSec, capped at capacity. Owned by the token-bucket utility — do not hand-edit.'
+                }
+            },
+            {
+                name: 'capacity',
+                type: 'number',
+                required: true,
+                defaultValue: 60,
+                admin: {
+                    description: 'Maximum bucket size. Tune to match the provider plan RPM cap (e.g. 60 for a 60 RPM plan, 600 for a 600 RPM plan). Admins may edit; the utility respects the current value.'
+                }
+            },
+            {
+                name: 'refillRatePerSec',
+                type: 'number',
+                required: true,
+                defaultValue: 1,
+                admin: {
+                    description: 'Tokens added per second. For a 60 RPM cap use 1.0; for 600 RPM use 10.0. Admins may edit; the utility respects the current value.'
+                }
+            },
+            {
+                name: 'lastRefillAt',
+                type: 'date',
+                required: true,
+                admin: {
+                    readOnly: true,
+                    description: 'Timestamp of the last refill calculation. Used by the utility to compute elapsed time since the last acquire. Owned by the utility.'
+                }
+            }
+        ],
+        indexes: [
+            // Composite uniqueness for the (provider, model) bucket key.
+            // Hand-written migration should also add a Postgres UNIQUE
+            // constraint at the DB level to enforce concurrent-insert
+            // safety.
+            {
+                fields: [
+                    'provider',
+                    'model'
+                ],
+                unique: true
+            }
+        ]
+    };
+}