@purposeinplay/payload-ai-translate 0.1.0

package/dist/alerts-collection.d.ts

@@ -0,0 +1,21 @@
+import type { Access, CollectionConfig } from 'payload';
+/**
+ * Factory for the auto-registered `translation-alerts` collection.
+ *
+ * The plugin pushes this collection onto `config.collections` when
+ * `alertsTracking.enabled` is true (default). Every `emitAlert` call from
+ * `lib/events.ts` writes one row in addition to firing the consumer's
+ * `onAlert` callback (which is unchanged — kept for back-compat).
+ *
+ * Alerts surface failure modes that aren't visible in the usage table:
+ *   - persistent-failure: doc keeps failing across retries
+ *   - cost-guard-abort:  doc exceeded perDocCharCeiling, no row was written
+ *   - provider-outage:   upstream provider returned 5xx for an extended window
+ *
+ * Without this collection the Hub had no way to surface these — the
+ * consumer's `onAlert` callback (typically Slack/email) was the only
+ * signal, and in-app admins had no visibility.
+ *
+ * Mirrors the `translation-usage` and `audit-log` collection patterns.
+ */
+export declare function createAlertsCollection(readAccess?: Access, collectionSlug?: string): CollectionConfig;

package/dist/alerts-collection.js

@@ -0,0 +1,159 @@
+import { DEFAULT_ALERTS_COLLECTION_SLUG } from './defaults.js';
+/**
+ * Factory for the auto-registered `translation-alerts` collection.
+ *
+ * The plugin pushes this collection onto `config.collections` when
+ * `alertsTracking.enabled` is true (default). Every `emitAlert` call from
+ * `lib/events.ts` writes one row in addition to firing the consumer's
+ * `onAlert` callback (which is unchanged — kept for back-compat).
+ *
+ * Alerts surface failure modes that aren't visible in the usage table:
+ *   - persistent-failure: doc keeps failing across retries
+ *   - cost-guard-abort:  doc exceeded perDocCharCeiling, no row was written
+ *   - provider-outage:   upstream provider returned 5xx for an extended window
+ *
+ * Without this collection the Hub had no way to surface these — the
+ * consumer's `onAlert` callback (typically Slack/email) was the only
+ * signal, and in-app admins had no visibility.
+ *
+ * Mirrors the `translation-usage` and `audit-log` collection patterns.
+ */ export function createAlertsCollection(readAccess, collectionSlug) {
+    const slug = collectionSlug ?? DEFAULT_ALERTS_COLLECTION_SLUG;
+    const defaultAdminRead = ({ req })=>req?.user?.roles?.includes('admin') ?? false;
+    // Admins can mark an alert dismissed (an editor doesn't need to see a
+    // 5-day-old cost-guard-abort that's been triaged). Everything else is
+    // plugin-owned — no creates / deletes from the UI.
+    const defaultAdminUpdate = ({ req })=>req?.user?.roles?.includes('admin') ?? 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 Alert',
+            plural: 'Translation Alerts'
+        },
+        admin: {
+            useAsTitle: 'message',
+            group: 'System',
+            // Hide from non-admins; the Hub surfaces these via its own banner.
+            hidden: ({ user })=>!user?.roles?.includes('admin'),
+            description: 'One row per alert event raised by the translation plugin (cost-guard-abort, persistent-failure, provider-outage). The Hub surfaces these in a banner; this collection is the persistent audit trail. Rows are written automatically — admins can only dismiss them.',
+            defaultColumns: [
+                'createdAt',
+                'alertType',
+                'collection',
+                'documentId',
+                'dismissed'
+            ]
+        },
+        access: {
+            read: readAccess ?? defaultAdminRead,
+            create: ()=>false,
+            update: defaultAdminUpdate,
+            delete: ()=>false
+        },
+        graphQL: false,
+        timestamps: true,
+        fields: [
+            {
+                name: 'alertType',
+                type: 'select',
+                required: true,
+                admin: {
+                    readOnly: true
+                },
+                options: [
+                    {
+                        label: 'Persistent failure',
+                        value: 'persistent-failure'
+                    },
+                    {
+                        label: 'Cost guard abort',
+                        value: 'cost-guard-abort'
+                    },
+                    {
+                        label: 'Provider outage',
+                        value: 'provider-outage'
+                    }
+                ]
+            },
+            {
+                name: 'message',
+                type: 'text',
+                required: true,
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                // For collection alerts, the slug of the collection that triggered.
+                // For globals, the slug of the global. Nullable for plugin-wide
+                // alerts (e.g. a provider-outage that isn't tied to a specific doc).
+                name: 'collection',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                // Stringified doc id. Nullable for the same reason as `collection`.
+                name: 'documentId',
+                type: 'text',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                // Type-specific blob: e.g. cost-guard-abort includes
+                // `{ characterCount, limit }`. JSON to keep the schema simple
+                // without proliferating per-type sidecar tables.
+                name: 'metadata',
+                type: 'json',
+                admin: {
+                    readOnly: true
+                }
+            },
+            {
+                // Allow admins to acknowledge an alert. Editable; everything else
+                // is read-only.
+                name: 'dismissed',
+                type: 'checkbox',
+                defaultValue: false
+            },
+            {
+                name: 'dismissedAt',
+                type: 'date',
+                admin: {
+                    readOnly: true
+                }
+            }
+        ],
+        hooks: {
+            beforeChange: [
+                ({ data, originalDoc })=>{
+                    // Auto-stamp dismissedAt when dismissed flips false→true. Read-only
+                    // in the UI but populated server-side so we don't have to trust
+                    // a client-supplied timestamp.
+                    if (data.dismissed && !originalDoc?.dismissed) {
+                        return {
+                            ...data,
+                            dismissedAt: new Date().toISOString()
+                        };
+                    }
+                    if (!data.dismissed && originalDoc?.dismissed) {
+                        return {
+                            ...data,
+                            dismissedAt: null
+                        };
+                    }
+                    return data;
+                }
+            ]
+        }
+    };
+}

package/dist/api.d.ts

@@ -0,0 +1,4 @@
+import type { Payload } from 'payload';
+import type { TranslateDocumentOptions, TranslateDocumentResult, TranslateGlobalOptions } from './types.js';
+export declare function translateDocument(payload: Payload, options: TranslateDocumentOptions): Promise<TranslateDocumentResult>;
+export declare function translateGlobal(payload: Payload, options: TranslateGlobalOptions): Promise<TranslateDocumentResult>;