@sequoialabs/payload-plugin-reversia 0.1.0

package/dist/endpoints/resources.js

@@ -0,0 +1,107 @@
+import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
+import { decodeCursor, encodeCursor } from '../utils/cursor.js';
+import { findLocalizedFields, serializeField } from '../utils/fields.js';
+import { parseLimit, resolveDefaultLocale } from '../utils/payload-helpers.js';
+function extractContent(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 createResourcesEndpoint(pluginConfig, collectionsMap, _globalsMap) {
+    return {
+        path: '/reversia/resources',
+        method: 'get',
+        handler: async (req) => {
+            if (!validateApiKey(req, pluginConfig.apiKey)) {
+                return unauthorizedResponse();
+            }
+            const typesParam = req.searchParams.get('types');
+            const cursorParam = req.searchParams.get('cursor');
+            const limit = parseLimit(req.searchParams.get('limit'));
+            const cursor = decodeCursor(cursorParam);
+            const requestedTypes = typesParam ? typesParam.split(',').filter(Boolean) : null;
+            const defaultLocale = resolveDefaultLocale(req);
+            const response = { content: [], cursor: null };
+            let totalFetched = 0;
+            let lastType = null;
+            let lastId = null;
+            let startFromCursor = !cursor;
+            for (const [slug, collection] of collectionsMap) {
+                const resourceType = `payloadcms:${slug}`;
+                if (requestedTypes && !requestedTypes.includes(resourceType)) {
+                    continue;
+                }
+                if (!startFromCursor) {
+                    if (cursor && cursor.type === resourceType) {
+                        startFromCursor = true;
+                    }
+                    else {
+                        continue;
+                    }
+                }
+                if (totalFetched >= limit) {
+                    break;
+                }
+                const localizedFields = findLocalizedFields(collection.fields);
+                if (localizedFields.length === 0) {
+                    continue;
+                }
+                const where = {};
+                if (cursor && cursor.type === resourceType && cursor.id) {
+                    where.id = { greater_than: cursor.id };
+                }
+                const docs = await req.payload.find({
+                    collection: slug,
+                    locale: defaultLocale,
+                    limit: limit - totalFetched,
+                    sort: 'id',
+                    where,
+                });
+                if (docs.docs.length === 0) {
+                    continue;
+                }
+                const items = [];
+                for (const doc of docs.docs) {
+                    const { content, contentTypes } = extractContent(doc, localizedFields);
+                    if (Object.keys(content).length === 0) {
+                        continue;
+                    }
+                    items.push({
+                        id: String(doc.id),
+                        label: getLabelValue(doc, localizedFields),
+                        content,
+                        contentTypes: Object.keys(contentTypes).length > 0 ? contentTypes : undefined,
+                    });
+                    lastType = resourceType;
+                    lastId = String(doc.id);
+                    totalFetched++;
+                }
+                if (items.length > 0) {
+                    response.content.push({ type: resourceType, data: items });
+                }
+            }
+            if (lastType && lastId && totalFetched >= limit) {
+                response.cursor = encodeCursor(lastType, lastId);
+            }
+            return Response.json(response);
+        },
+    };
+}

package/dist/endpoints/settings.d.ts

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

package/dist/endpoints/settings.js

@@ -0,0 +1,34 @@
+import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
+export function createSettingsEndpoint(pluginConfig) {
+    return {
+        path: '/reversia/settings',
+        method: 'get',
+        handler: async (req) => {
+            if (!validateApiKey(req, pluginConfig.apiKey)) {
+                return unauthorizedResponse();
+            }
+            const localization = req.payload.config.localization;
+            let languages = [];
+            if (localization && typeof localization === 'object' && 'locales' in localization) {
+                const locales = localization.locales;
+                languages = locales.map((locale) => {
+                    const label = typeof locale.label === 'string'
+                        ? locale.label
+                        : locale.label && typeof locale.label === 'object' && 'en' in locale.label
+                            ? String(locale.label.en)
+                            : locale.code;
+                    return { code: locale.code, label };
+                });
+            }
+            const defaultLocale = localization && typeof localization === 'object' && 'defaultLocale' in localization
+                ? String(localization.defaultLocale)
+                : 'en';
+            return Response.json({
+                platform: 'payloadcms',
+                pluginVersion: '0.1.0',
+                languages,
+                defaultLocale,
+            });
+        },
+    };
+}

package/dist/hooks/after-change.d.ts

@@ -0,0 +1,11 @@
+import type { CollectionAfterChangeHook } from 'payload';
+/**
+ * Records a pending-sync entry whenever a tracked document changes.
+ *
+ * Each call deletes any existing pending row for the same (resourceType,
+ * resourceId) pair and creates a fresh one. This guarantees the row's id is
+ * greater than every cursor previously handed out, so a `confirm` call that
+ * clears `id ≤ cursor.id` never eats a pending change that arrived after the
+ * cursor was issued.
+ */
+export declare function createAfterChangeHook(resourceType: string): CollectionAfterChangeHook;

package/dist/hooks/after-change.js

@@ -0,0 +1,40 @@
+/**
+ * Records a pending-sync entry whenever a tracked document changes.
+ *
+ * Each call deletes any existing pending row for the same (resourceType,
+ * resourceId) pair and creates a fresh one. This guarantees the row's id is
+ * greater than every cursor previously handed out, so a `confirm` call that
+ * clears `id ≤ cursor.id` never eats a pending change that arrived after the
+ * cursor was issued.
+ */
+export function createAfterChangeHook(resourceType) {
+    return async ({ doc, req, context }) => {
+        if (context?.reversiaInsertion) {
+            return doc;
+        }
+        const resourceId = String(doc.id);
+        try {
+            const existing = await req.payload.find({
+                collection: 'reversia-sync-pending',
+                where: {
+                    and: [{ resourceType: { equals: resourceType } }, { resourceId: { equals: resourceId } }],
+                },
+                limit: 100,
+            });
+            for (const row of existing.docs) {
+                await req.payload.delete({
+                    collection: 'reversia-sync-pending',
+                    id: row.id,
+                });
+            }
+            await req.payload.create({
+                collection: 'reversia-sync-pending',
+                data: { resourceType, resourceId },
+            });
+        }
+        catch (error) {
+            req.payload.logger.error({ err: error, resourceType, resourceId }, '[reversia] Failed to track sync pending');
+        }
+        return doc;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import type { Config } from 'payload';
+import type { ReversiaPluginConfig } from './types.js';
+export type { ConfirmResourcesSyncResponse, InsertionRequest, InsertionResponse, ResourceDefinition, ResourceItem, ResourceResponse, ReversiaErrorResponse, ReversiaFieldCustom, ReversiaPluginConfig, SettingsResponse, StreamResponse, TranslatableFieldConfig, } from './types.js';
+export { ReversiaFieldBehavior, ReversiaFieldType } from './types.js';
+export declare const reversiaPlugin: (pluginConfig: ReversiaPluginConfig) => (config: Config) => Config;
+export default reversiaPlugin;

package/dist/index.js

@@ -0,0 +1,82 @@
+import { reversiaSyncPendingCollection } from './collections/sync-pending.js';
+import { createConfirmResourcesSyncEndpoint } from './endpoints/confirm-resources-sync.js';
+import { createResourceEndpoint } from './endpoints/resource.js';
+import { createResourcesEndpoint } from './endpoints/resources.js';
+import { createResourcesDefinitionEndpoint } from './endpoints/resources-definition.js';
+import { createResourcesInsertEndpoint } from './endpoints/resources-insert.js';
+import { createResourcesSyncEndpoint } from './endpoints/resources-sync.js';
+import { createSettingsEndpoint } from './endpoints/settings.js';
+import { createAfterChangeHook } from './hooks/after-change.js';
+import { findLocalizedFields } from './utils/fields.js';
+export { ReversiaFieldBehavior, ReversiaFieldType } from './types.js';
+const APPLIED_MARKER = Symbol.for('payload-plugin-reversia.applied');
+export const reversiaPlugin = (pluginConfig) => (config) => {
+    if (pluginConfig.disabled) {
+        return config;
+    }
+    if (typeof pluginConfig.apiKey !== 'string' || pluginConfig.apiKey.length === 0) {
+        throw new Error('[reversia] apiKey is required. Set `ReversiaPluginConfig.apiKey` to a non-empty string.');
+    }
+    const marked = config;
+    if (marked[APPLIED_MARKER]) {
+        return config;
+    }
+    marked[APPLIED_MARKER] = true;
+    const enabledCollectionSlugs = pluginConfig.enabledCollections
+        ? new Set(pluginConfig.enabledCollections.map((s) => String(s)))
+        : null;
+    const enabledGlobalSlugs = pluginConfig.enabledGlobals
+        ? new Set(pluginConfig.enabledGlobals)
+        : null;
+    const collectionsMap = new Map();
+    const globalsMap = new Map();
+    const collections = [...(config.collections ?? [])];
+    for (const collection of collections) {
+        if (enabledCollectionSlugs && !enabledCollectionSlugs.has(collection.slug)) {
+            continue;
+        }
+        if (findLocalizedFields(collection.fields).length === 0) {
+            continue;
+        }
+        collectionsMap.set(collection.slug, collection);
+    }
+    const globals = [...(config.globals ?? [])];
+    for (const global of globals) {
+        if (enabledGlobalSlugs && !enabledGlobalSlugs.has(global.slug)) {
+            continue;
+        }
+        if (findLocalizedFields(global.fields).length === 0) {
+            continue;
+        }
+        globalsMap.set(global.slug, global);
+    }
+    config.collections = collections.map((collection) => {
+        if (!collectionsMap.has(collection.slug)) {
+            return collection;
+        }
+        const resourceType = `payloadcms:${collection.slug}`;
+        return {
+            ...collection,
+            hooks: {
+                ...(collection.hooks ?? {}),
+                afterChange: [
+                    ...(collection.hooks?.afterChange ?? []),
+                    createAfterChangeHook(resourceType),
+                ],
+            },
+        };
+    });
+    config.collections = [...(config.collections ?? []), reversiaSyncPendingCollection];
+    config.endpoints = [
+        ...(config.endpoints ?? []),
+        createResourcesDefinitionEndpoint(pluginConfig, collectionsMap, globalsMap),
+        createResourcesEndpoint(pluginConfig, collectionsMap, globalsMap),
+        createResourcesSyncEndpoint(pluginConfig, collectionsMap),
+        createResourceEndpoint(pluginConfig, collectionsMap, globalsMap),
+        createResourcesInsertEndpoint(pluginConfig, collectionsMap, globalsMap),
+        createConfirmResourcesSyncEndpoint(pluginConfig),
+        createSettingsEndpoint(pluginConfig),
+    ];
+    return config;
+};
+export default reversiaPlugin;

package/dist/types.d.ts

@@ -0,0 +1,238 @@
+import type { CollectionSlug } from 'payload';
+import type { LeafSegment } from './utils/path-resolver.js';
+export interface ReversiaPluginConfig {
+    /**
+     * API key used by Reversia SaaS to authenticate requests.
+     * Validated against `X-API-Key` header.
+     */
+    apiKey: string;
+    /**
+     * Optional: restrict which collections are exposed to Reversia.
+     * If omitted, all collections with localized fields are exposed.
+     */
+    enabledCollections?: CollectionSlug[];
+    /**
+     * Optional: restrict which globals are exposed to Reversia.
+     * If omitted, all globals with localized fields are exposed.
+     */
+    enabledGlobals?: string[];
+    /**
+     * Whether the plugin is disabled. Defaults to false.
+     */
+    disabled?: boolean;
+}
+export declare enum ReversiaFieldType {
+    TEXT = "TEXT",
+    HTML = "HTML",
+    JSON = "JSON",
+    LINK = "LINK",
+    MEDIUM = "MEDIUM"
+}
+export declare enum ReversiaFieldBehavior {
+    SLUG = "slug"
+}
+/**
+ * Custom field metadata for Reversia.
+ *
+ * Usage on any PayloadCMS field:
+ * ```ts
+ * import { ReversiaFieldType, ReversiaFieldBehavior } from 'payload-plugin-reversia'
+ *
+ * {
+ *   name: 'slug',
+ *   type: 'text',
+ *   localized: true,
+ *   custom: {
+ *     reversia: {
+ *       behavior: ReversiaFieldBehavior.SLUG,
+ *     },
+ *   },
+ * }
+ *
+ * {
+ *   name: 'ogImage',
+ *   type: 'text',
+ *   localized: true,
+ *   custom: {
+ *     reversia: {
+ *       type: ReversiaFieldType.MEDIUM,
+ *     },
+ *   },
+ * }
+ * ```
+ */
+export interface ReversiaFieldCustom {
+    /**
+     * How the field value should be treated during translation.
+     */
+    behavior?: ReversiaFieldBehavior;
+    /**
+     * The content type of the field value.
+     * Inferred from PayloadCMS field type when omitted (richText → JSON, json → JSON).
+     * The Lexical/Slate tree is shipped as a JSON-encoded map of translatable leaves.
+     */
+    type?: ReversiaFieldType;
+    /**
+     * Whether this field is used as the resource label in Reversia.
+     */
+    asLabel?: boolean;
+    /**
+     * Whether this field is selected for translation by default.
+     * Defaults to true.
+     */
+    selected?: boolean;
+    /**
+     * For object/array-shaped values (richText, json), restrict which leaf strings
+     * are shipped to Reversia.
+     *
+     * Path syntax:
+     * - `text`                  — any key `text` at any depth (shorthand for `**.text`)
+     * - `root.foo`              — exact path from the root
+     * - `foo.*.bar`             — single wildcard segment (one object key or array index)
+     * - `foo.**.bar`            — deep wildcard (zero or more segments)
+     *
+     * Default for `richText` when omitted: `['text', 'url', 'alt']`.
+     * For `json`, extraction only happens when this is explicitly set (or `extract` is provided).
+     */
+    translatableKeys?: string[];
+    /**
+     * Escape hatch. When provided, bypasses `translatableKeys` matching entirely.
+     * `extract` receives the raw field value and returns the string shipped to Reversia.
+     * `apply` receives the source-locale value plus the translated string and returns
+     * the value stored on the target locale. Both must be set together.
+     */
+    extract?: (value: unknown) => string;
+    apply?: (sourceValue: unknown, translated: string) => unknown;
+}
+export interface TranslatableFieldConfig {
+    label: string;
+    asLabel?: boolean;
+    behavior?: ReversiaFieldBehavior;
+    type?: ReversiaFieldType;
+    selected?: boolean;
+}
+export interface ResourceDefinition {
+    type: string;
+    label: {
+        singular: string;
+        plural: string;
+    };
+    group: string;
+    version: string;
+    configuration: Record<string, TranslatableFieldConfig>;
+    configurationType: 'ENTITY' | 'MULTIPLE';
+    count?: number;
+    synchronizable: boolean;
+}
+/**
+ * Describes one localized leaf inside a top-level container field.
+ *
+ * `segments` walks from the container's *value* to the leaf (so a top-level
+ * scalar localized field has `segments: []` because the container value IS
+ * the scalar).
+ *
+ * `kind`:
+ *  - `scalar` — atomic string-shaped leaf (text, textarea, email, url, …)
+ *    serialized as-is at its pointer.
+ *  - `json` — structurally complex leaf (richText, json) that needs internal
+ *    extraction by `translatableKeys`. Each matching sub-leaf gets its own
+ *    pointer entry, prefixed by the leaf's own pointer in the container.
+ */
+export interface LocalizedLeaf {
+    segments: LeafSegment[];
+    kind: 'scalar' | 'json';
+    payloadFieldType: string;
+    reversia?: ReversiaFieldCustom;
+}
+/**
+ * One translatable top-level field on a collection or global.
+ *
+ * The plugin emits exactly one resource-content entry per `LocalizedFieldInfo`,
+ * keyed by `name`. Scalars ship their value directly. Containers ship a
+ * JSON-stringified `{ <jsonPointer>: <translatableString> }` map whose keys
+ * address each atomic translatable leaf inside the container's value.
+ */
+export interface LocalizedFieldInfo {
+    /** Top-level field name — the key in the document and in the content map. */
+    name: string;
+    /** Resolved label for the resource configuration. */
+    label: string;
+    /** PayloadCMS field type at the top level (`text`, `richText`, `array`, …). */
+    payloadFieldType: string;
+    /**
+     * `true` when the value is shipped as a JSON pointer-map (containers).
+     * `false` when shipped as a plain primitive (top-level localized scalars).
+     */
+    isContainer: boolean;
+    /** `custom.reversia` declared on the top-level field, if any. */
+    reversia?: ReversiaFieldCustom;
+    /** One descriptor per localized leaf inside the container. */
+    leaves: LocalizedLeaf[];
+}
+export interface ResourceItem {
+    id: string;
+    label?: string;
+    content: Record<string, unknown>;
+    contentTypes?: Record<string, string>;
+}
+export interface StreamResponse {
+    content: Array<{
+        type: string;
+        data: ResourceItem[];
+    }>;
+    cursor: string | null;
+}
+export interface InsertionRequest {
+    type: string;
+    id: string;
+    sourceLocale: string;
+    targetLocale: string;
+    data: Record<string, unknown>;
+}
+export interface InsertionResponse {
+    errors: string[];
+    [key: number]: {
+        index: number;
+        type: string;
+        id: string;
+        diff: Record<string, string>;
+    };
+}
+export interface Cursor {
+    type: string;
+    id: string;
+}
+/**
+ * Response shape for `GET /reversia/resource` (single collection doc or global).
+ */
+export interface ResourceResponse {
+    id: string;
+    label?: string;
+    content: Record<string, unknown>;
+    contentTypes?: Record<string, string>;
+}
+/**
+ * Response shape for `GET /reversia/settings`.
+ */
+export interface SettingsResponse {
+    platform: 'payloadcms';
+    pluginVersion: string;
+    languages: Array<{
+        code: string;
+        label: string;
+    }>;
+    defaultLocale: string;
+}
+/**
+ * Response shape for `POST /reversia/confirm-resources-sync`.
+ */
+export interface ConfirmResourcesSyncResponse {
+    success: true;
+    deleted: number;
+}
+/**
+ * 4xx/5xx error response used uniformly across endpoints.
+ */
+export interface ReversiaErrorResponse {
+    error: string;
+}

package/dist/types.js

@@ -0,0 +1,12 @@
+export var ReversiaFieldType;
+(function (ReversiaFieldType) {
+    ReversiaFieldType["TEXT"] = "TEXT";
+    ReversiaFieldType["HTML"] = "HTML";
+    ReversiaFieldType["JSON"] = "JSON";
+    ReversiaFieldType["LINK"] = "LINK";
+    ReversiaFieldType["MEDIUM"] = "MEDIUM";
+})(ReversiaFieldType || (ReversiaFieldType = {}));
+export var ReversiaFieldBehavior;
+(function (ReversiaFieldBehavior) {
+    ReversiaFieldBehavior["SLUG"] = "slug";
+})(ReversiaFieldBehavior || (ReversiaFieldBehavior = {}));

package/dist/utils/auth.d.ts

@@ -0,0 +1,3 @@
+import type { PayloadRequest } from 'payload';
+export declare function validateApiKey(req: PayloadRequest, expectedKey: string): boolean;
+export declare function unauthorizedResponse(): Response;

package/dist/utils/auth.js

@@ -0,0 +1,27 @@
+import { timingSafeEqual } from 'node:crypto';
+export function validateApiKey(req, expectedKey) {
+    if (typeof expectedKey !== 'string' || expectedKey.length === 0) {
+        return false;
+    }
+    const headerKey = req.headers.get('x-api-key');
+    const queryKey = req.searchParams.get('apiKey');
+    const providedKey = headerKey ?? queryKey;
+    if (typeof providedKey !== 'string' || providedKey.length === 0) {
+        return false;
+    }
+    return constantTimeEquals(providedKey, expectedKey);
+}
+function constantTimeEquals(a, b) {
+    const aBuf = Buffer.from(a, 'utf8');
+    const bBuf = Buffer.from(b, 'utf8');
+    if (aBuf.length !== bBuf.length) {
+        // Still consume a comparison on a pair of equal-length buffers so callers
+        // cannot distinguish "wrong length" from "wrong contents" via timing.
+        timingSafeEqual(aBuf, aBuf);
+        return false;
+    }
+    return timingSafeEqual(aBuf, bBuf);
+}
+export function unauthorizedResponse() {
+    return Response.json({ error: 'Invalid API key' }, { status: 401 });
+}

package/dist/utils/cursor.d.ts

@@ -0,0 +1,7 @@
+import type { Cursor } from '../types.js';
+/**
+ * Opaque cursor encoding. Uses JSON in base64url so the delimiter concern
+ * (types or ids containing `|`) is eliminated.
+ */
+export declare function encodeCursor(type: string, id: string): string;
+export declare function decodeCursor(cursorString: string | null | undefined): Cursor | null;

package/dist/utils/cursor.js

@@ -0,0 +1,30 @@
+/**
+ * Opaque cursor encoding. Uses JSON in base64url so the delimiter concern
+ * (types or ids containing `|`) is eliminated.
+ */
+export function encodeCursor(type, id) {
+    return Buffer.from(JSON.stringify({ type, id }), 'utf-8').toString('base64url');
+}
+export function decodeCursor(cursorString) {
+    if (!cursorString) {
+        return null;
+    }
+    try {
+        const decoded = Buffer.from(cursorString, 'base64url').toString('utf-8');
+        const parsed = JSON.parse(decoded);
+        if (!parsed ||
+            typeof parsed !== 'object' ||
+            typeof parsed.type !== 'string' ||
+            typeof parsed.id !== 'string') {
+            return null;
+        }
+        const { type, id } = parsed;
+        if (type.length === 0 || id.length === 0) {
+            return null;
+        }
+        return { type, id };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/utils/fields.d.ts

@@ -0,0 +1,58 @@
+import type { Field } from 'payload';
+import type { LocalizedFieldInfo, TranslatableFieldConfig } from '../types.js';
+import { ReversiaFieldType } from '../types.js';
+/**
+ * Collects one `LocalizedFieldInfo` per top-level field that is itself
+ * localized OR that contains at least one localized descendant.
+ *
+ * Top-level localized scalars become non-container entries. Everything else
+ * (richText, json, group, array, blocks, or any unnamed wrapper containing
+ * localized descendants) becomes a container with one or more `leaves`.
+ */
+export declare function findLocalizedFields(fields: Field[]): LocalizedFieldInfo[];
+export declare function resolveContentType(field: LocalizedFieldInfo): ReversiaFieldType | undefined;
+export declare function buildTranslatableConfiguration(localizedFields: LocalizedFieldInfo[]): Record<string, TranslatableFieldConfig>;
+export declare const getContentType: typeof resolveContentType;
+export interface SerialisedFieldEntry {
+    /** Top-level field name; doubles as the key in `content` and `contentTypes`. */
+    name: string;
+    /** Serialised value to ship to Reversia. */
+    value: string | number | boolean;
+    /** Resolved Reversia content type, if any. */
+    contentType?: ReversiaFieldType;
+}
+/**
+ * Produces zero or one serialised entry for a top-level localized field.
+ *
+ * - Scalars: pass-through primitive value (or `extract` result).
+ * - Containers: walk every localized leaf, build a JSON-pointer map of only
+ *   the translatable atoms (so we never ship non-localized siblings or fields
+ *   the user opted out of), JSON.stringify and emit one entry.
+ *
+ * Returns `undefined` when there is nothing translatable to send (empty
+ * source value, no matching leaves, or filtered out).
+ */
+export declare function serializeField(field: LocalizedFieldInfo, doc: unknown): SerialisedFieldEntry | undefined;
+/**
+ * Reverses `serializeField` for one top-level field.
+ *
+ * - Scalars: return `translatedRaw` as-is (after `apply` if defined).
+ * - Containers: parse the JSON pointer map; deep-clone the source-locale
+ *   container value as the base; overlay each translated leaf at its pointer.
+ *   For `json` sub-leaves the pointer is split between the leaf location and
+ *   the sub-extraction pointer — `applyByKeys` replays the standard richText
+ *   path on the leaf's value before we re-attach it.
+ *
+ * The source-clone strategy guarantees required non-localized siblings (block
+ * structure, array item ids, sub-object scaffolding) are preserved when we
+ * write to Payload — same pattern as the PrestaShop module.
+ */
+export declare function deserializeFieldValue(field: LocalizedFieldInfo, sourceValue: unknown, translatedRaw: unknown): unknown;
+/**
+ * Builds the base `updateData` for a translation insertion by deep-cloning
+ * each top-level localized field's value out of the source-locale doc. This
+ * guarantees required nested siblings (block structure, ids, non-localized
+ * subfields) are present in the update payload, even when Reversia only sent
+ * a subset of leaves.
+ */
+export declare function cloneLocalizedContainersFromSource(sourceDoc: unknown, fields: readonly LocalizedFieldInfo[]): Record<string, unknown>;