@sequoialabs/payload-plugin-reversia 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sequoia Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @sequoialabs/payload-plugin-reversia
+
+A [PayloadCMS](https://payloadcms.com/) plugin that integrates with [Reversia](https://reversia.tech), a translation SaaS platform, enabling seamless content localization and synchronization across multiple languages.
+
+## How it works
+
+1. The plugin scans your PayloadCMS config and detects every top-level field that contains at least one `localized: true` leaf — scalars, groups, arrays, blocks, richText, json all qualify.
+2. When content changes, an `afterChange` hook records the resource in a hidden sync queue.
+3. Reversia polls the plugin's HTTP endpoints to fetch translatable content.
+4. Each resource entry is keyed by top-level field name. Scalars ship as plain values. **Containers ship one JSON-pointer map per field** containing only the localized atoms — non-localized siblings, structural keys, and unrelated data never reach Reversia.
+5. Once translated, Reversia pushes translations back. The plugin **clones the source-locale document** as the base of the update, then overlays each translated leaf at its pointer — required nested siblings (block ids, `blockType`, non-localized subfields) are guaranteed to be present so Payload validation passes.
+6. A confirmation endpoint clears processed items from the sync queue (`updatedAt`-based, so re-edits during translation aren't lost).
+
+## Installation
+
+```bash
+npm install @sequoialabs/payload-plugin-reversia
+# or
+bun add @sequoialabs/payload-plugin-reversia
+```
+
+## Quick start
+
+```ts
+import { buildConfig } from 'payload';
+import { reversiaPlugin } from '@sequoialabs/payload-plugin-reversia';
+
+export default buildConfig({
+  plugins: [
+    reversiaPlugin({
+      apiKey: process.env.REVERSIA_API_KEY!,
+      enabledCollections: ['posts', 'pages'],
+      enabledGlobals: ['site-settings'],
+    }),
+  ],
+});
+```
+
+Then mark whichever fields are translatable. **You don't need to annotate containers** — declaring `localized: true` on any inner subfield is enough; the plugin auto-detects the top-level container and emits a single JSON-pointer entry for it.
+
+```ts
+// Top-level localized scalar — shipped as a primitive.
+{ name: 'title', type: 'text', localized: true }
+
+// Top-level richText — shipped as a JSON-pointer map of `text`/`url`/`alt`
+// leaves by default.
+{ name: 'body', type: 'richText', localized: true }
+
+// Slug field — ship as text, mark behaviour for Reversia.
+{
+  name: 'slug',
+  type: 'text',
+  localized: true,
+  custom: { reversia: { behavior: 'slug' } },
+}
+
+// Blocks container — auto-detected. One entry per page keyed by `body`,
+// value: `{"/0/heading":"…","/2/heading":"…"}`.
+{
+  name: 'body',
+  type: 'blocks',
+  blocks: [
+    { slug: 'hero', fields: [{ name: 'heading', type: 'text', localized: true }] },
+  ],
+}
+```
+
+## Documentation
+
+- **[Configuration](./docs/configuration.md)** — plugin options, auth, what gets exposed.
+- **[Field annotations](./docs/field-annotations.md)** — the `custom.reversia` metadata reference.
+- **[Rich text & JSON fields](./docs/rich-text.md)** — `translatableKeys`, path patterns, and the `extract`/`apply` escape hatch.
+- **[API reference](./docs/api-reference.md)** — HTTP endpoints consumed by the Reversia SaaS.
+- **[Contributing](./CONTRIBUTING.md)** — local dev, linting, testing.
+
+## Requirements
+
+- PayloadCMS v3.0.0+
+- Node.js 20+ or Bun
+- At least one `localized: true` field on a collection or global
+
+## License
+
+MIT

package/dist/collections/sync-pending.d.ts

@@ -0,0 +1,2 @@
+import type { CollectionConfig } from 'payload';
+export declare const reversiaSyncPendingCollection: CollectionConfig;

package/dist/collections/sync-pending.js

@@ -0,0 +1,27 @@
+export const reversiaSyncPendingCollection = {
+    slug: 'reversia-sync-pending',
+    admin: {
+        hidden: true,
+    },
+    access: {
+        // Hidden, internal queue — no public read/write access by default.
+        read: () => false,
+        create: () => false,
+        update: () => false,
+        delete: () => false,
+    },
+    fields: [
+        {
+            name: 'resourceType',
+            type: 'text',
+            required: true,
+            index: true,
+        },
+        {
+            name: 'resourceId',
+            type: 'text',
+            required: true,
+            index: true,
+        },
+    ],
+};

package/dist/endpoints/confirm-resources-sync.d.ts

@@ -0,0 +1,3 @@
+import type { Endpoint } from 'payload';
+import type { ReversiaPluginConfig } from '../types.js';
+export declare function createConfirmResourcesSyncEndpoint(pluginConfig: ReversiaPluginConfig): Endpoint;

package/dist/endpoints/confirm-resources-sync.js

@@ -0,0 +1,31 @@
+import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
+import { decodeCursor } from '../utils/cursor.js';
+export function createConfirmResourcesSyncEndpoint(pluginConfig) {
+    return {
+        path: '/reversia/confirm-resources-sync',
+        method: 'post',
+        handler: async (req) => {
+            if (!validateApiKey(req, pluginConfig.apiKey)) {
+                return unauthorizedResponse();
+            }
+            const body = req.data ??
+                (req.json ? await req.json() : undefined);
+            if (!body?.cursor) {
+                return Response.json({ error: 'cursor is required' }, { status: 400 });
+            }
+            const cursor = decodeCursor(body.cursor);
+            if (!cursor) {
+                return Response.json({ error: 'Invalid cursor' }, { status: 400 });
+            }
+            // Rows edited after the cursor have a later `updatedAt` and must survive.
+            // Using timestamp comparison is portable across Mongo/Postgres/SQLite —
+            // id reuse on SQLite would silently corrupt the queue.
+            const result = await req.payload.delete({
+                collection: 'reversia-sync-pending',
+                where: { updatedAt: { less_than_equal: cursor.id } },
+            });
+            const deleted = Array.isArray(result.docs) ? result.docs.length : 0;
+            return Response.json({ success: true, deleted });
+        },
+    };
+}

package/dist/endpoints/resource.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig, Endpoint, GlobalConfig } from 'payload';
+import type { ReversiaPluginConfig } from '../types.js';
+export declare function createResourceEndpoint(pluginConfig: ReversiaPluginConfig, collectionsMap: Map<string, CollectionConfig>, globalsMap: Map<string, GlobalConfig>): Endpoint;

package/dist/endpoints/resource.js

@@ -0,0 +1,82 @@
+import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
+import { findLocalizedFields, serializeField } from '../utils/fields.js';
+import { resolveDefaultLocale } from '../utils/payload-helpers.js';
+function extract(doc, fields) {
+    const content = {};
+    const contentTypes = {};
+    for (const field of fields) {
+        const entry = serializeField(field, doc);
+        if (!entry) {
+            continue;
+        }
+        content[entry.name] = entry.value;
+        if (entry.contentType) {
+            contentTypes[entry.name] = entry.contentType;
+        }
+    }
+    return { content, contentTypes };
+}
+function getLabelValue(doc, fields) {
+    const labelField = fields.find((f) => !f.isContainer && (f.name === 'title' || f.name === 'name'));
+    if (!labelField) {
+        return undefined;
+    }
+    const value = doc?.[labelField.name];
+    return typeof value === 'string' ? value : undefined;
+}
+export function createResourceEndpoint(pluginConfig, collectionsMap, globalsMap) {
+    return {
+        path: '/reversia/resource',
+        method: 'get',
+        handler: async (req) => {
+            if (!validateApiKey(req, pluginConfig.apiKey)) {
+                return unauthorizedResponse();
+            }
+            const resourceType = req.searchParams.get('resourceType');
+            const resourceId = req.searchParams.get('resourceId');
+            if (!resourceType || resourceType.length === 0) {
+                return Response.json({ error: 'resourceType is required' }, { status: 400 });
+            }
+            const defaultLocale = resolveDefaultLocale(req);
+            if (resourceType.startsWith('payloadcms:global:')) {
+                const globalSlug = resourceType.slice('payloadcms:global:'.length);
+                const globalConfig = globalsMap.get(globalSlug);
+                if (!globalConfig) {
+                    return Response.json({ error: `Global ${globalSlug} not found` }, { status: 404 });
+                }
+                const localizedFields = findLocalizedFields(globalConfig.fields);
+                const doc = await req.payload.findGlobal({ slug: globalSlug, locale: defaultLocale });
+                const { content, contentTypes } = extract(doc, localizedFields);
+                return Response.json({
+                    id: globalSlug,
+                    content,
+                    contentTypes: Object.keys(contentTypes).length > 0 ? contentTypes : undefined,
+                });
+            }
+            if (!resourceType.startsWith('payloadcms:')) {
+                return Response.json({ error: 'Unknown resourceType' }, { status: 400 });
+            }
+            const slug = resourceType.slice('payloadcms:'.length);
+            const collection = collectionsMap.get(slug);
+            if (!collection) {
+                return Response.json({ error: `Collection ${slug} not found` }, { status: 404 });
+            }
+            if (!resourceId || resourceId.length === 0) {
+                return Response.json({ error: 'resourceId is required for collection resources' }, { status: 400 });
+            }
+            const localizedFields = findLocalizedFields(collection.fields);
+            const doc = await req.payload.findByID({
+                collection: slug,
+                id: resourceId,
+                locale: defaultLocale,
+            });
+            const { content, contentTypes } = extract(doc, localizedFields);
+            return Response.json({
+                id: String(doc.id),
+                label: getLabelValue(doc, localizedFields),
+                content,
+                contentTypes: Object.keys(contentTypes).length > 0 ? contentTypes : undefined,
+            });
+        },
+    };
+}

package/dist/endpoints/resources-definition.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig, Endpoint, GlobalConfig } from 'payload';
+import type { ReversiaPluginConfig } from '../types.js';
+export declare function createResourcesDefinitionEndpoint(pluginConfig: ReversiaPluginConfig, collectionsMap: Map<string, CollectionConfig>, globalsMap: Map<string, GlobalConfig>): Endpoint;

package/dist/endpoints/resources-definition.js

@@ -0,0 +1,54 @@
+import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
+import { buildTranslatableConfiguration, findLocalizedFields } from '../utils/fields.js';
+import { resolveStaticLabel } from '../utils/labels.js';
+export function createResourcesDefinitionEndpoint(pluginConfig, collectionsMap, globalsMap) {
+    return {
+        path: '/reversia/resources-definition',
+        method: 'get',
+        handler: async (req) => {
+            if (!validateApiKey(req, pluginConfig.apiKey)) {
+                return unauthorizedResponse();
+            }
+            const definitions = [];
+            for (const [slug, collection] of collectionsMap) {
+                const localizedFields = findLocalizedFields(collection.fields);
+                if (localizedFields.length === 0) {
+                    continue;
+                }
+                const count = await req.payload.count({ collection: slug });
+                definitions.push({
+                    type: `payloadcms:${slug}`,
+                    label: {
+                        singular: resolveStaticLabel(collection.labels?.singular, slug),
+                        plural: resolveStaticLabel(collection.labels?.plural, slug),
+                    },
+                    group: 'payloadcms',
+                    version: '1.0.0',
+                    configuration: buildTranslatableConfiguration(localizedFields),
+                    configurationType: 'MULTIPLE',
+                    count: count.totalDocs,
+                    synchronizable: true,
+                });
+            }
+            for (const [slug, global] of globalsMap) {
+                const localizedFields = findLocalizedFields(global.fields);
+                if (localizedFields.length === 0) {
+                    continue;
+                }
+                definitions.push({
+                    type: `payloadcms:global:${slug}`,
+                    label: {
+                        singular: resolveStaticLabel(global.label, slug),
+                        plural: resolveStaticLabel(global.label, slug),
+                    },
+                    group: 'payloadcms',
+                    version: '1.0.0',
+                    configuration: buildTranslatableConfiguration(localizedFields),
+                    configurationType: 'ENTITY',
+                    synchronizable: true,
+                });
+            }
+            return Response.json(definitions);
+        },
+    };
+}

package/dist/endpoints/resources-insert.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig, Endpoint, GlobalConfig } from 'payload';
+import type { ReversiaPluginConfig } from '../types.js';
+export declare function createResourcesInsertEndpoint(pluginConfig: ReversiaPluginConfig, collectionsMap: Map<string, CollectionConfig>, globalsMap: Map<string, GlobalConfig>): Endpoint;

package/dist/endpoints/resources-insert.js

@@ -0,0 +1,174 @@
+import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
+import { cloneLocalizedContainersFromSource, deserializeFieldValue, findLocalizedFields, } from '../utils/fields.js';
+function stringifyDiffValue(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (typeof value === 'object') {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+function indexFieldsByName(fields) {
+    const map = new Map();
+    for (const f of fields) {
+        map.set(f.name, f);
+    }
+    return map;
+}
+function applyTranslations({ allowedFields, data, sourceDoc, previousDoc, }) {
+    const fieldByName = indexFieldsByName(allowedFields);
+    // Source clone is the base — required nested siblings are preserved even
+    // when Reversia only sends a subset of leaves (mirrors the PrestaShop
+    // module's "clone source, replace with what we got" approach).
+    const updateData = cloneLocalizedContainersFromSource(sourceDoc, allowedFields);
+    const diff = {};
+    const acceptedFields = [];
+    const previous = previousDoc ?? null;
+    const source = sourceDoc ?? null;
+    for (const [fieldName, translatedValue] of Object.entries(data)) {
+        const field = fieldByName.get(fieldName);
+        if (!field) {
+            continue;
+        }
+        const sourceValue = source ? source[fieldName] : undefined;
+        const finalValue = deserializeFieldValue(field, sourceValue, translatedValue);
+        updateData[fieldName] = finalValue;
+        acceptedFields.push(fieldName);
+        const prevValue = previous ? previous[fieldName] : undefined;
+        if (prevValue === undefined || prevValue === null) {
+            continue;
+        }
+        const prevString = stringifyDiffValue(prevValue);
+        const newString = stringifyDiffValue(finalValue);
+        if (prevString !== newString) {
+            diff[fieldName] = prevString;
+        }
+    }
+    return { updateData, diff, acceptedFields };
+}
+export function createResourcesInsertEndpoint(pluginConfig, collectionsMap, globalsMap) {
+    return {
+        path: '/reversia/resources-insert',
+        method: 'put',
+        handler: async (req) => {
+            if (!validateApiKey(req, pluginConfig.apiKey)) {
+                return unauthorizedResponse();
+            }
+            const body = req.data ??
+                (req.json ? await req.json() : undefined);
+            if (!Array.isArray(body)) {
+                return Response.json({ error: 'Request body must be an array' }, { status: 400 });
+            }
+            const response = { errors: [] };
+            for (let index = 0; index < body.length; index++) {
+                const item = body[index];
+                if (!item || typeof item !== 'object') {
+                    response.errors.push(`Item ${index}: must be an object`);
+                    continue;
+                }
+                if (!item.type) {
+                    response.errors.push(`Item ${index}: type is required`);
+                    continue;
+                }
+                if (!item.targetLocale) {
+                    response.errors.push(`Item ${index}: targetLocale is required`);
+                    continue;
+                }
+                if (!item.data || typeof item.data !== 'object') {
+                    response.errors.push(`Item ${index}: data is required and must be an object`);
+                    continue;
+                }
+                try {
+                    if (item.type.startsWith('payloadcms:global:')) {
+                        const globalSlug = item.type.slice('payloadcms:global:'.length);
+                        const globalConfig = globalsMap.get(globalSlug);
+                        if (!globalConfig) {
+                            response.errors.push(`Item ${index}: global ${globalSlug} not found`);
+                            continue;
+                        }
+                        const allowedFields = findLocalizedFields(globalConfig.fields);
+                        // Always fetch source — required to populate non-localized siblings
+                        // and to deserialize JSON-pointer maps. Target fetch is for diff.
+                        const [sourceDoc, previousDoc] = await Promise.all([
+                            req.payload.findGlobal({ slug: globalSlug, locale: item.sourceLocale }),
+                            req.payload.findGlobal({ slug: globalSlug, locale: item.targetLocale }),
+                        ]);
+                        const { updateData, diff, acceptedFields } = applyTranslations({
+                            allowedFields,
+                            data: item.data,
+                            sourceDoc,
+                            previousDoc,
+                        });
+                        if (acceptedFields.length === 0) {
+                            response.errors.push(`Item ${index}: no recognised fields in data (keys: ${Object.keys(item.data).join(', ')})`);
+                            continue;
+                        }
+                        await req.payload.updateGlobal({
+                            slug: globalSlug,
+                            locale: item.targetLocale,
+                            data: updateData,
+                            context: { reversiaInsertion: true },
+                        });
+                        response[index] = { index, type: item.type, id: globalSlug, diff };
+                        continue;
+                    }
+                    if (!item.type.startsWith('payloadcms:')) {
+                        response.errors.push(`Item ${index}: unknown resourceType "${item.type}"`);
+                        continue;
+                    }
+                    const slug = item.type.slice('payloadcms:'.length);
+                    const collection = collectionsMap.get(slug);
+                    if (!collection) {
+                        response.errors.push(`Item ${index}: collection ${slug} not found`);
+                        continue;
+                    }
+                    if (!item.id) {
+                        response.errors.push(`Item ${index}: id is required for collection resources`);
+                        continue;
+                    }
+                    const allowedFields = findLocalizedFields(collection.fields);
+                    const [sourceDoc, previousDoc] = await Promise.all([
+                        req.payload.findByID({
+                            collection: slug,
+                            id: item.id,
+                            locale: item.sourceLocale,
+                        }),
+                        req.payload.findByID({
+                            collection: slug,
+                            id: item.id,
+                            locale: item.targetLocale,
+                        }),
+                    ]);
+                    const { updateData, diff, acceptedFields } = applyTranslations({
+                        allowedFields,
+                        data: item.data,
+                        sourceDoc,
+                        previousDoc,
+                    });
+                    if (acceptedFields.length === 0) {
+                        response.errors.push(`Item ${index}: no recognised fields in data (keys: ${Object.keys(item.data).join(', ')})`);
+                        continue;
+                    }
+                    await req.payload.update({
+                        collection: slug,
+                        id: item.id,
+                        locale: item.targetLocale,
+                        data: updateData,
+                        context: { reversiaInsertion: true },
+                    });
+                    response[index] = { index, type: item.type, id: item.id, diff };
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    req.payload.logger.error({ err: error, item: { type: item.type, id: item.id, targetLocale: item.targetLocale } }, '[reversia] insertion failed');
+                    response.errors.push(`Item ${index} (${item.type}${item.id ? ` ${item.id}` : ''} → ${item.targetLocale}): ${message}`);
+                }
+            }
+            return Response.json(response);
+        },
+    };
+}

package/dist/endpoints/resources-sync.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig, Endpoint } from 'payload';
+import type { ReversiaPluginConfig } from '../types.js';
+export declare function createResourcesSyncEndpoint(pluginConfig: ReversiaPluginConfig, _collectionsMap: Map<string, CollectionConfig>): Endpoint;

package/dist/endpoints/resources-sync.js

@@ -0,0 +1,59 @@
+import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
+import { decodeCursor, encodeCursor } from '../utils/cursor.js';
+import { parseLimit } from '../utils/payload-helpers.js';
+export function createResourcesSyncEndpoint(pluginConfig, _collectionsMap) {
+    return {
+        path: '/reversia/resources-sync',
+        method: 'get',
+        handler: async (req) => {
+            if (!validateApiKey(req, pluginConfig.apiKey)) {
+                return unauthorizedResponse();
+            }
+            const cursorParam = req.searchParams.get('cursor');
+            const limit = parseLimit(req.searchParams.get('limit'));
+            const cursor = decodeCursor(cursorParam);
+            const where = {};
+            if (cursor) {
+                // Cursor.id carries the `updatedAt` checkpoint as an ISO string.
+                where.updatedAt = { greater_than: cursor.id };
+            }
+            const pendingDocs = await req.payload.find({
+                collection: 'reversia-sync-pending',
+                where,
+                sort: 'updatedAt',
+                limit,
+            });
+            if (pendingDocs.docs.length === 0) {
+                return Response.json({ content: [], cursor: null });
+            }
+            const grouped = new Map();
+            for (const doc of pendingDocs.docs) {
+                const pending = doc;
+                const existing = grouped.get(pending.resourceType) ?? [];
+                existing.push(pending.resourceId);
+                grouped.set(pending.resourceType, existing);
+            }
+            const content = [];
+            for (const [resourceType, identifiers] of grouped) {
+                content.push({
+                    type: resourceType,
+                    data: [
+                        {
+                            id: resourceType,
+                            content: { identifiers },
+                        },
+                    ],
+                });
+            }
+            const lastDoc = pendingDocs.docs[pendingDocs.docs.length - 1];
+            const lastUpdatedAt = typeof lastDoc.updatedAt === 'string'
+                ? lastDoc.updatedAt
+                : new Date(lastDoc.updatedAt).toISOString();
+            const lastCursor = encodeCursor('reversia-sync-pending', lastUpdatedAt);
+            return Response.json({
+                content,
+                cursor: lastCursor,
+            });
+        },
+    };
+}

package/dist/endpoints/resources.d.ts

@@ -0,0 +1,3 @@
+import type { CollectionConfig, Endpoint, GlobalConfig } from 'payload';
+import type { ReversiaPluginConfig } from '../types.js';
+export declare function createResourcesEndpoint(pluginConfig: ReversiaPluginConfig, collectionsMap: Map<string, CollectionConfig>, _globalsMap: Map<string, GlobalConfig>): Endpoint;