@sequoialabs/payload-plugin-reversia 0.1.0

package/dist/utils/json-extract.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Key-driven extraction for richText / json field values.
+ *
+ * Walks a JSON value and emits a flat map keyed by JSON Pointer (RFC 6901):
+ *   { "/root/children/0/text": "Hello" }
+ *
+ * Only leaf strings whose *key path* (object keys only, array indices skipped)
+ * matches one of the compiled glob patterns are emitted.
+ *
+ * Pattern syntax:
+ *   text            — bare key; sugar for `**.text` (match at any depth)
+ *   root.foo        — anchored path from the root
+ *   foo.*.bar       — `*` matches a single key segment
+ *   foo.**.bar      — `**` matches zero or more key segments
+ */
+type Segment = {
+    kind: 'key';
+    value: string;
+} | {
+    kind: 'star';
+} | {
+    kind: 'globstar';
+};
+export type CompiledPattern = readonly Segment[];
+export declare function compilePattern(pattern: string): CompiledPattern;
+export interface KeyMatcher {
+    matches(keyPath: readonly string[]): boolean;
+}
+export declare function compileKeyMatcher(patterns: readonly string[]): KeyMatcher;
+export declare function extractByKeys(value: unknown, matcher: KeyMatcher): Record<string, string>;
+/**
+ * Deep-clones `sourceValue` and writes each translated string at its pointer.
+ * Missing targets are skipped silently — the source tree may have drifted.
+ */
+export declare function applyByKeys(sourceValue: unknown, translations: Record<string, string>): unknown;
+export declare const DEFAULT_RICHTEXT_KEYS: readonly ["text", "url", "alt"];
+export {};

package/dist/utils/json-extract.js

@@ -0,0 +1,186 @@
+/**
+ * Key-driven extraction for richText / json field values.
+ *
+ * Walks a JSON value and emits a flat map keyed by JSON Pointer (RFC 6901):
+ *   { "/root/children/0/text": "Hello" }
+ *
+ * Only leaf strings whose *key path* (object keys only, array indices skipped)
+ * matches one of the compiled glob patterns are emitted.
+ *
+ * Pattern syntax:
+ *   text            — bare key; sugar for `**.text` (match at any depth)
+ *   root.foo        — anchored path from the root
+ *   foo.*.bar       — `*` matches a single key segment
+ *   foo.**.bar      — `**` matches zero or more key segments
+ */
+export function compilePattern(pattern) {
+    const parts = pattern.split('.').filter((p) => p.length > 0);
+    if (parts.length === 1 && parts[0] !== '*' && parts[0] !== '**') {
+        return [{ kind: 'globstar' }, { kind: 'key', value: parts[0] }];
+    }
+    return parts.map((p) => {
+        if (p === '*') {
+            return { kind: 'star' };
+        }
+        if (p === '**') {
+            return { kind: 'globstar' };
+        }
+        return { kind: 'key', value: p };
+    });
+}
+/** Classic two-pointer glob match with `**` backtracking. */
+function matchPattern(segs, path) {
+    let i = 0;
+    let j = 0;
+    let starI = -1;
+    let starJ = 0;
+    while (j < path.length) {
+        const seg = segs[i];
+        if (seg?.kind === 'globstar') {
+            starI = i;
+            starJ = j;
+            i++;
+            continue;
+        }
+        if (seg && (seg.kind === 'star' || (seg.kind === 'key' && seg.value === path[j]))) {
+            i++;
+            j++;
+            continue;
+        }
+        if (starI !== -1) {
+            i = starI + 1;
+            starJ++;
+            j = starJ;
+            continue;
+        }
+        return false;
+    }
+    while (i < segs.length && segs[i].kind === 'globstar') {
+        i++;
+    }
+    return i === segs.length;
+}
+export function compileKeyMatcher(patterns) {
+    const compiled = patterns.map(compilePattern);
+    return {
+        matches(keyPath) {
+            if (keyPath.length === 0) {
+                return false;
+            }
+            for (const p of compiled) {
+                if (matchPattern(p, keyPath)) {
+                    return true;
+                }
+            }
+            return false;
+        },
+    };
+}
+function encodePointerSegment(seg) {
+    if (typeof seg === 'number') {
+        return String(seg);
+    }
+    return seg.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+function decodePointerSegment(seg) {
+    return seg.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+function encodePointer(path) {
+    let out = '';
+    for (const seg of path) {
+        out = `${out}/${encodePointerSegment(seg)}`;
+    }
+    return out;
+}
+function decodePointer(pointer) {
+    if (pointer === '') {
+        return [];
+    }
+    if (pointer[0] !== '/') {
+        throw new Error(`Invalid JSON Pointer: ${pointer}`);
+    }
+    return pointer.slice(1).split('/').map(decodePointerSegment);
+}
+export function extractByKeys(value, matcher) {
+    const out = {};
+    const locPath = [];
+    const keyPath = [];
+    const visit = (node) => {
+        if (typeof node === 'string') {
+            if (matcher.matches(keyPath)) {
+                out[encodePointer(locPath)] = node;
+            }
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (let i = 0; i < node.length; i++) {
+                locPath.push(i);
+                visit(node[i]);
+                locPath.pop();
+            }
+            return;
+        }
+        if (node !== null && typeof node === 'object') {
+            for (const k of Object.keys(node)) {
+                locPath.push(k);
+                keyPath.push(k);
+                visit(node[k]);
+                keyPath.pop();
+                locPath.pop();
+            }
+        }
+    };
+    visit(value);
+    return out;
+}
+/**
+ * Deep-clones `sourceValue` and writes each translated string at its pointer.
+ * Missing targets are skipped silently — the source tree may have drifted.
+ */
+export function applyByKeys(sourceValue, translations) {
+    if (sourceValue === null || typeof sourceValue !== 'object') {
+        return sourceValue;
+    }
+    const cloned = structuredClone(sourceValue);
+    for (const pointer of Object.keys(translations)) {
+        writeAtPointer(cloned, decodePointer(pointer), translations[pointer]);
+    }
+    return cloned;
+}
+function writeAtPointer(root, segments, value) {
+    if (segments.length === 0) {
+        return;
+    }
+    let current = root;
+    for (let i = 0; i < segments.length - 1; i++) {
+        current = stepInto(current, segments[i]);
+        if (current === undefined) {
+            return;
+        }
+    }
+    const last = segments[segments.length - 1];
+    if (Array.isArray(current)) {
+        const idx = Number(last);
+        if (Number.isInteger(idx) && idx >= 0 && idx < current.length) {
+            current[idx] = value;
+        }
+        return;
+    }
+    if (current !== null && typeof current === 'object' && last in current) {
+        current[last] = value;
+    }
+}
+function stepInto(node, segment) {
+    if (Array.isArray(node)) {
+        const idx = Number(segment);
+        if (!Number.isInteger(idx)) {
+            return undefined;
+        }
+        return node[idx];
+    }
+    if (node !== null && typeof node === 'object') {
+        return node[segment];
+    }
+    return undefined;
+}
+export const DEFAULT_RICHTEXT_KEYS = ['text', 'url', 'alt'];

package/dist/utils/labels.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Resolves a PayloadCMS static label to a plain string.
+ *
+ * Labels in Payload can be:
+ * - `string`: "Post"
+ * - `Record<string, string>`: { en: "Post", fr: "Article" }
+ * - `function`: (args) => string (used for dynamic labels in admin UI)
+ * - `false` | `undefined`
+ *
+ * We pick the first available value: `en` key, then first key, then fallback.
+ */
+export declare function resolveStaticLabel(label: unknown, fallback: string): string;

package/dist/utils/labels.js

@@ -0,0 +1,27 @@
+/**
+ * Resolves a PayloadCMS static label to a plain string.
+ *
+ * Labels in Payload can be:
+ * - `string`: "Post"
+ * - `Record<string, string>`: { en: "Post", fr: "Article" }
+ * - `function`: (args) => string (used for dynamic labels in admin UI)
+ * - `false` | `undefined`
+ *
+ * We pick the first available value: `en` key, then first key, then fallback.
+ */
+export function resolveStaticLabel(label, fallback) {
+    if (typeof label === 'string') {
+        return label;
+    }
+    if (label && typeof label === 'object' && !Array.isArray(label)) {
+        const record = label;
+        if (typeof record.en === 'string') {
+            return record.en;
+        }
+        const firstKey = Object.keys(record)[0];
+        if (firstKey && typeof record[firstKey] === 'string') {
+            return record[firstKey];
+        }
+    }
+    return fallback;
+}

package/dist/utils/path-resolver.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Structural traversal for "container" fields.
+ *
+ * In the per-top-level-field model, every translatable resource entry is a
+ * single top-level field. Scalars ship as plain strings. Containers (groups,
+ * arrays, blocks, richText, json) ship as a JSON-stringified map of
+ *   { <jsonPointer>: <translatableString> }
+ * where each pointer addresses one atomic translatable leaf inside the
+ * container's value.
+ *
+ * `LeafSegment` describes how to navigate from a container's *value* down to
+ * one of its localized leaves. Unlike absolute paths from the document root,
+ * an `iterate` segment means "the current node is an array, iterate it" —
+ * because the container's value IS the array we're already inside.
+ */
+export type LeafSegment = {
+    kind: 'key';
+    name: string;
+} | {
+    kind: 'iterate';
+} | {
+    kind: 'iterateBlock';
+    blockSlug: string;
+};
+export interface LeafLocation {
+    /** RFC 6901 JSON Pointer string from the container's value root. */
+    pointer: string;
+    /** Decoded pointer parts (object keys / numeric indices). */
+    pointerParts: string[];
+    /** Resolved value at that location. */
+    value: unknown;
+}
+export declare function resolveLeafLocations(containerValue: unknown, segments: readonly LeafSegment[]): LeafLocation[];
+export declare function encodePointer(parts: readonly string[]): string;
+export declare function decodePointer(pointer: string): string[];
+/**
+ * Concatenate a parent pointer with a child pointer (already encoded).
+ * `''` is the empty pointer (root). Either side may be empty.
+ */
+export declare function joinPointers(parent: string, child: string): string;
+/**
+ * Writes a string at the location addressed by `pointer` inside `target`.
+ * Creates intermediate objects/arrays when traversal hits null/undefined,
+ * preserving any pre-existing structure encountered along the way.
+ */
+export declare function writeAtPointer(target: unknown, pointer: string, value: string): unknown;
+/**
+ * Deep-clones the source-locale container value and overlays each translation
+ * at its addressed pointer. When `containerSource` is missing, builds a sparse
+ * tree from the pointers — best-effort fallback so the platform still receives
+ * translated values for any leaves Reversia did send.
+ */
+export declare function applyTranslationsToContainer(containerSource: unknown, translations: Record<string, string>): unknown;

package/dist/utils/path-resolver.js

@@ -0,0 +1,157 @@
+/**
+ * Structural traversal for "container" fields.
+ *
+ * In the per-top-level-field model, every translatable resource entry is a
+ * single top-level field. Scalars ship as plain strings. Containers (groups,
+ * arrays, blocks, richText, json) ship as a JSON-stringified map of
+ *   { <jsonPointer>: <translatableString> }
+ * where each pointer addresses one atomic translatable leaf inside the
+ * container's value.
+ *
+ * `LeafSegment` describes how to navigate from a container's *value* down to
+ * one of its localized leaves. Unlike absolute paths from the document root,
+ * an `iterate` segment means "the current node is an array, iterate it" —
+ * because the container's value IS the array we're already inside.
+ */
+export function resolveLeafLocations(containerValue, segments) {
+    const out = [];
+    walk(containerValue, segments, 0, [], out);
+    return out;
+}
+function walk(node, segs, i, parts, out) {
+    if (i === segs.length) {
+        out.push({ pointer: encodePointer(parts), pointerParts: parts.slice(), value: node });
+        return;
+    }
+    if (node === null || node === undefined) {
+        return;
+    }
+    const seg = segs[i];
+    if (seg.kind === 'key') {
+        if (typeof node !== 'object' || Array.isArray(node)) {
+            return;
+        }
+        const next = node[seg.name];
+        walk(next, segs, i + 1, [...parts, seg.name], out);
+        return;
+    }
+    if (seg.kind === 'iterate') {
+        if (!Array.isArray(node)) {
+            return;
+        }
+        for (let idx = 0; idx < node.length; idx++) {
+            walk(node[idx], segs, i + 1, [...parts, String(idx)], out);
+        }
+        return;
+    }
+    if (seg.kind === 'iterateBlock') {
+        if (!Array.isArray(node)) {
+            return;
+        }
+        for (let idx = 0; idx < node.length; idx++) {
+            const item = node[idx];
+            if (item &&
+                typeof item === 'object' &&
+                item.blockType === seg.blockSlug) {
+                walk(item, segs, i + 1, [...parts, String(idx)], out);
+            }
+        }
+    }
+}
+export function encodePointer(parts) {
+    if (parts.length === 0) {
+        return '';
+    }
+    let out = '';
+    for (const p of parts) {
+        out += `/${encodePointerSegment(p)}`;
+    }
+    return out;
+}
+export function decodePointer(pointer) {
+    if (pointer === '' || pointer === '/') {
+        return pointer === '/' ? [''] : [];
+    }
+    if (pointer[0] !== '/') {
+        throw new Error(`Invalid JSON Pointer: ${pointer}`);
+    }
+    return pointer.slice(1).split('/').map(decodePointerSegment);
+}
+function encodePointerSegment(seg) {
+    return seg.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+function decodePointerSegment(seg) {
+    return seg.replace(/~1/g, '/').replace(/~0/g, '~');
+}
+/**
+ * Concatenate a parent pointer with a child pointer (already encoded).
+ * `''` is the empty pointer (root). Either side may be empty.
+ */
+export function joinPointers(parent, child) {
+    if (parent === '') {
+        return child;
+    }
+    if (child === '') {
+        return parent;
+    }
+    return `${parent}${child}`;
+}
+/**
+ * Writes a string at the location addressed by `pointer` inside `target`.
+ * Creates intermediate objects/arrays when traversal hits null/undefined,
+ * preserving any pre-existing structure encountered along the way.
+ */
+export function writeAtPointer(target, pointer, value) {
+    const parts = decodePointer(pointer);
+    if (parts.length === 0) {
+        return value;
+    }
+    let root = target;
+    if (root === null || root === undefined) {
+        root = /^\d+$/.test(parts[0]) ? [] : {};
+    }
+    let current = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const key = parts[i];
+        const nextKey = parts[i + 1];
+        const nextIsIndex = /^\d+$/.test(nextKey);
+        if (Array.isArray(current)) {
+            const idx = Number(key);
+            if (current[idx] === null || current[idx] === undefined) {
+                current[idx] = nextIsIndex ? [] : {};
+            }
+            current = current[idx];
+            continue;
+        }
+        if (current && typeof current === 'object') {
+            const obj = current;
+            if (obj[key] === null || obj[key] === undefined) {
+                obj[key] = nextIsIndex ? [] : {};
+            }
+            current = obj[key];
+        }
+    }
+    const last = parts[parts.length - 1];
+    if (Array.isArray(current)) {
+        current[Number(last)] = value;
+    }
+    else if (current && typeof current === 'object') {
+        current[last] = value;
+    }
+    return root;
+}
+/**
+ * Deep-clones the source-locale container value and overlays each translation
+ * at its addressed pointer. When `containerSource` is missing, builds a sparse
+ * tree from the pointers — best-effort fallback so the platform still receives
+ * translated values for any leaves Reversia did send.
+ */
+export function applyTranslationsToContainer(containerSource, translations) {
+    let root = containerSource === undefined || containerSource === null
+        ? null
+        : structuredClone(containerSource);
+    for (const [pointer, value] of Object.entries(translations)) {
+        root = writeAtPointer(root, pointer, value);
+    }
+    return root;
+}

package/dist/utils/payload-helpers.d.ts

@@ -0,0 +1,16 @@
+import type { PayloadRequest } from 'payload';
+/**
+ * Parses a caller-supplied `limit` query parameter and clamps it to a safe
+ * range. NaN, zero, and negatives fall back to the default.
+ */
+export declare function parseLimit(raw: string | null, fallback?: number): number;
+/**
+ * Resolves the default locale code from a Payload config, defaulting to `en`
+ * when localization is not configured.
+ */
+export declare function resolveDefaultLocale(req: PayloadRequest): string;
+/**
+ * Plain dot-path lookup on an object, returning `undefined` for any missing
+ * segment or non-object traversal. Does not walk into arrays.
+ */
+export declare function getNestedValue(obj: Record<string, unknown>, path: string): unknown;

package/dist/utils/payload-helpers.js

@@ -0,0 +1,45 @@
+const DEFAULT_LIMIT = 100;
+const MAX_LIMIT = 1000;
+/**
+ * Parses a caller-supplied `limit` query parameter and clamps it to a safe
+ * range. NaN, zero, and negatives fall back to the default.
+ */
+export function parseLimit(raw, fallback = DEFAULT_LIMIT) {
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return fallback;
+    }
+    return Math.min(parsed, MAX_LIMIT);
+}
+/**
+ * Resolves the default locale code from a Payload config, defaulting to `en`
+ * when localization is not configured.
+ */
+export function resolveDefaultLocale(req) {
+    const localization = req.payload.config.localization;
+    if (localization && typeof localization === 'object' && 'defaultLocale' in localization) {
+        const value = localization.defaultLocale;
+        if (typeof value === 'string' && value.length > 0) {
+            return value;
+        }
+    }
+    return 'en';
+}
+/**
+ * Plain dot-path lookup on an object, returning `undefined` for any missing
+ * segment or non-object traversal. Does not walk into arrays.
+ */
+export function getNestedValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@sequoialabs/payload-plugin-reversia",
+  "version": "0.1.0",
+  "author": {
+    "name": "Jean Walrave",
+    "email": "contact@reversia.tech",
+    "url": "https://reversia.tech"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/SequoiaLabs/reversia-payloadcms-plugin#readme",
+  "keywords": [
+    "payload",
+    "payloadcms",
+    "plugin",
+    "reversia",
+    "i18n",
+    "translation",
+    "localization"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SequoiaLabs/reversia-payloadcms-plugin.git"
+  },
+  "description": "PayloadCMS plugin for Reversia translation SaaS integration",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "test": "rm -f dev/test.db && bun test",
+    "lint": "biome check",
+    "lint:fix": "biome check --write",
+    "format": "biome format --write",
+    "prepublishOnly": "bun run test && bun run build"
+  },
+  "peerDependencies": {
+    "payload": "^3.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.12",
+    "@payloadcms/db-sqlite": "^3.0.0",
+    "@payloadcms/richtext-lexical": "^3.79.1",
+    "@types/bun": "^1.3.10",
+    "payload": "^3.0.0",
+    "typescript": "^5.0.0"
+  }
+}