@sequoialabs/payload-plugin-reversia 0.1.7 → 0.2.0

package/README.md

@@ -71,6 +71,7 @@ Then mark whichever fields are translatable. **You don't need to annotate contai
 - **[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.
+- **[Triggering crawls](./docs/trigger-crawl.md)** — `triggerCrawl()` for server code and `useTriggerCrawl()` for admin UI.
 - **[Contributing](./CONTRIBUTING.md)** — local dev, linting, testing.
 
 ## Requirements

package/dist/client/index.d.ts

@@ -0,0 +1 @@
+export { type TriggerCrawlArgs, type TriggerCrawlOutcome, type TriggerCrawlStatus, type UseTriggerCrawlOptions, type UseTriggerCrawlResult, useTriggerCrawl, } from './use-trigger-crawl';

package/dist/client/index.js

@@ -0,0 +1 @@
+export { useTriggerCrawl, } from './use-trigger-crawl';

package/dist/client/use-trigger-crawl.d.ts

@@ -0,0 +1,30 @@
+import type { CollectionSlug, GlobalSlug } from 'payload';
+export type TriggerCrawlStatus = 'idle' | 'pending' | 'success' | 'error';
+export interface UseTriggerCrawlOptions {
+    /**
+     * Override the server endpoint path. Defaults to
+     * `/api/reversia/dashboard/trigger-crawl`.
+     */
+    endpoint?: string;
+}
+export interface TriggerCrawlArgs {
+    /**
+     * Collection and/or global slugs to crawl. Slugs are prefixed with
+     * `payloadcms:` server-side before reaching Reversia. Omit/empty to crawl
+     * every enabled resource for the project.
+     */
+    types?: Array<CollectionSlug | GlobalSlug>;
+    /** Bypass cached crawl content. Defaults to `false`. */
+    noCache?: boolean;
+}
+export interface TriggerCrawlOutcome {
+    success: boolean;
+    error?: string;
+}
+export interface UseTriggerCrawlResult {
+    trigger: (args?: TriggerCrawlArgs) => Promise<TriggerCrawlOutcome>;
+    status: TriggerCrawlStatus;
+    error: string | null;
+    reset: () => void;
+}
+export declare function useTriggerCrawl(options?: UseTriggerCrawlOptions): UseTriggerCrawlResult;

package/dist/client/use-trigger-crawl.js

@@ -0,0 +1,43 @@
+'use client';
+import { useCallback, useState } from 'react';
+const DEFAULT_ENDPOINT = '/api/reversia/dashboard/trigger-crawl';
+export function useTriggerCrawl(options = {}) {
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    const [status, setStatus] = useState('idle');
+    const [error, setError] = useState(null);
+    const trigger = useCallback(async (args = {}) => {
+        setStatus('pending');
+        setError(null);
+        try {
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                credentials: 'same-origin',
+                body: JSON.stringify({
+                    ...(args.types && args.types.length > 0 ? { types: args.types } : {}),
+                    ...(args.noCache ? { noCache: true } : {}),
+                }),
+            });
+            const body = (await response.json().catch(() => ({})));
+            if (!response.ok || body.success === false) {
+                const message = body.error ?? `Request failed (${response.status})`;
+                setStatus('error');
+                setError(message);
+                return { success: false, error: message };
+            }
+            setStatus('success');
+            return { success: true };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            setStatus('error');
+            setError(message);
+            return { success: false, error: message };
+        }
+    }, [endpoint]);
+    const reset = useCallback(() => {
+        setStatus('idle');
+        setError(null);
+    }, []);
+    return { trigger, status, error, reset };
+}

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

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

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

@@ -1,5 +1,5 @@
-import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
-import { decodeCursor } from '../utils/cursor.js';
+import { unauthorizedResponse, validateApiKey } from '../utils/auth';
+import { decodeCursor } from '../utils/cursor';
 export function createConfirmResourcesSyncEndpoint(pluginConfig) {
     return {
         path: '/reversia/confirm-resources-sync',

package/dist/endpoints/resource.d.ts

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

package/dist/endpoints/resource.js

@@ -1,6 +1,6 @@
-import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
-import { findLocalizedFields, serializeField } from '../utils/fields.js';
-import { resolveDefaultLocale } from '../utils/payload-helpers.js';
+import { unauthorizedResponse, validateApiKey } from '../utils/auth';
+import { findLocalizedFields, serializeField } from '../utils/fields';
+import { resolveDefaultLocale } from '../utils/payload-helpers';
 function extract(doc, fields) {
     const content = {};
     const contentTypes = {};

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

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

package/dist/endpoints/resources-definition.js

@@ -1,6 +1,6 @@
-import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
-import { buildTranslatableConfiguration, findLocalizedFields } from '../utils/fields.js';
-import { resolveStaticLabel } from '../utils/labels.js';
+import { unauthorizedResponse, validateApiKey } from '../utils/auth';
+import { buildTranslatableConfiguration, findLocalizedFields } from '../utils/fields';
+import { resolveStaticLabel } from '../utils/labels';
 export function createResourcesDefinitionEndpoint(pluginConfig, collectionsMap, globalsMap) {
     return {
         path: '/reversia/resources-definition',

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

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

package/dist/endpoints/resources-insert.js

@@ -1,5 +1,5 @@
-import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
-import { deflatePopulatedRelationships, deserializeFieldValue, findLocalizedFields, } from '../utils/fields.js';
+import { unauthorizedResponse, validateApiKey } from '../utils/auth';
+import { deflatePopulatedRelationships, deserializeFieldValue, findLocalizedFields, } from '../utils/fields';
 const WRITE_CONFLICT_MAX_RETRIES = 3;
 const WRITE_CONFLICT_BASE_DELAY_MS = 50;
 function isWriteConflict(error) {
@@ -109,7 +109,24 @@ function applyTranslations({ allowedFields, data, sourceDoc, previousDoc, }) {
             continue;
         }
         const sourceValue = source ? source[fieldName] : undefined;
-        const finalValue = deserializeFieldValue(field, sourceValue, translatedValue);
+        let finalValue;
+        try {
+            finalValue = deserializeFieldValue(field, sourceValue, translatedValue);
+        }
+        catch (error) {
+            // Re-throw with the offending field name attached so the caller's
+            // logger can pinpoint which container's source-locale shape blew up
+            // (e.g. a richText with a missing `children` array, an array item
+            // without an `id`). Without this, the surface error is something like
+            // "Cannot set properties of undefined (setting '0')" with no clue
+            // which field caused it across a multi-field document.
+            const message = error instanceof Error ? error.message : String(error);
+            const wrapped = new Error(`field "${fieldName}" failed to deserialize: ${message}`);
+            if (error instanceof Error && error.stack) {
+                wrapped.stack = error.stack;
+            }
+            throw wrapped;
+        }
         updateData[fieldName] = finalValue;
         acceptedFields.push(fieldName);
         const prevValue = previous ? previous[fieldName] : undefined;
@@ -124,6 +141,65 @@ function applyTranslations({ allowedFields, data, sourceDoc, previousDoc, }) {
     }
     return { updateData, diff, acceptedFields };
 }
+/**
+ * Payload's unique validator rejects an update when the new value already
+ * exists on another doc in the same locale. Reversia legitimately produces
+ * colliding translations (proper nouns, short phrases, numeric-suffix titles
+ * that don't change across locales), so without a pre-check the whole item
+ * fails with `ValidationError: <field>.<locale>: Value must be unique`.
+ *
+ * For every scalar field in `updateData` that the schema marks `unique: true`,
+ * query the target collection/locale for any OTHER doc with that value. When
+ * one exists, drop the field from the write so the rest of the update can go
+ * through. The source of truth stays on the first doc that claimed the value;
+ * the second doc's target-locale slot remains empty and can be edited
+ * manually later.
+ */
+async function dropUniqueCollisions(params) {
+    const { payload, collection, id, locale, fields, updateData, acceptedFields, diff } = params;
+    const dropped = [];
+    for (const field of fields) {
+        if (field.isContainer || !field.unique) {
+            continue;
+        }
+        if (!(field.name in updateData)) {
+            continue;
+        }
+        const value = updateData[field.name];
+        if (value === null || value === undefined || value === '') {
+            continue;
+        }
+        const existing = await payload.find({
+            collection: collection,
+            locale: locale,
+            depth: 0,
+            limit: 1,
+            pagination: false,
+            where: {
+                and: [{ [field.name]: { equals: value } }, { id: { not_equals: id } }],
+            },
+        });
+        if (existing.docs.length === 0) {
+            continue;
+        }
+        payload.logger.warn({
+            collection,
+            id,
+            targetLocale: locale,
+            field: field.name,
+            value,
+            collidingDocId: existing.docs[0]?.id,
+        }, '[reversia] skipping field to avoid unique collision');
+        delete updateData[field.name];
+        const acceptedIdx = acceptedFields.indexOf(field.name);
+        if (acceptedIdx !== -1) {
+            acceptedFields.splice(acceptedIdx, 1);
+        }
+        delete diff[field.name];
+        dropped.push(field.name);
+    }
+    return dropped;
+}
 export function createResourcesInsertEndpoint(pluginConfig, collectionsMap, globalsMap) {
     return {
         path: '/reversia/resources-insert',
@@ -238,6 +314,20 @@ export function createResourcesInsertEndpoint(pluginConfig, collectionsMap, glob
                         response.errors.push(`Item ${index}: no recognised fields in data (keys: ${Object.keys(item.data).join(', ')})`);
                         continue;
                     }
+                    const droppedForUnique = await dropUniqueCollisions({
+                        payload: req.payload,
+                        collection: slug,
+                        id: itemId,
+                        locale: item.targetLocale,
+                        fields: allowedFields,
+                        updateData,
+                        acceptedFields,
+                        diff,
+                    });
+                    if (acceptedFields.length === 0 || Object.keys(updateData).length === 0) {
+                        response.errors.push(`Item ${index} (${item.type} ${itemId} → ${item.targetLocale}): all translatable fields skipped due to unique-constraint collisions [${droppedForUnique.join(', ')}]`);
+                        continue;
+                    }
                     await withRetry(() => req.payload.update({
                         collection: slug,
                         id: itemId,

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

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

package/dist/endpoints/resources-sync.js

@@ -1,6 +1,6 @@
-import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
-import { decodeCursor, encodeCursor } from '../utils/cursor.js';
-import { parseLimit } from '../utils/payload-helpers.js';
+import { unauthorizedResponse, validateApiKey } from '../utils/auth';
+import { decodeCursor, encodeCursor } from '../utils/cursor';
+import { parseLimit } from '../utils/payload-helpers';
 export function createResourcesSyncEndpoint(pluginConfig, _collectionsMap) {
     return {
         path: '/reversia/resources-sync',

package/dist/endpoints/resources.d.ts

@@ -1,3 +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;
+import type { ReversiaPluginConfig } from '../types';
+export declare function createResourcesEndpoint(pluginConfig: ReversiaPluginConfig, collectionsMap: Map<string, CollectionConfig>, globalsMap: Map<string, GlobalConfig>): Endpoint;

package/dist/endpoints/resources.js

@@ -1,7 +1,7 @@
-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';
+import { unauthorizedResponse, validateApiKey } from '../utils/auth';
+import { decodeCursor, encodeCursor } from '../utils/cursor';
+import { findLocalizedFields, serializeField } from '../utils/fields';
+import { parseLimit, resolveDefaultLocale } from '../utils/payload-helpers';
 function extractContent(doc, fields) {
     const content = {};
     const contentTypes = {};
@@ -25,7 +25,7 @@ function getLabelValue(doc, fields) {
     const value = doc?.[labelField.name];
     return typeof value === 'string' ? value : undefined;
 }
-export function createResourcesEndpoint(pluginConfig, collectionsMap, _globalsMap) {
+export function createResourcesEndpoint(pluginConfig, collectionsMap, globalsMap) {
     return {
         path: '/reversia/resources',
         method: 'get',
@@ -98,6 +98,47 @@ export function createResourcesEndpoint(pluginConfig, collectionsMap, _globalsMa
                     response.content.push({ type: resourceType, data: items });
                 }
             }
+            // Globals are singletons (one doc per slug, id = slug), emitted after
+            // collections so pagination via `cursor` resumes at the right slot.
+            // Each global counts as 1 toward `limit`. Cursor semantics mirror the
+            // collection loop: when we find the type the cursor points to, that
+            // slot has already been returned — advance past it and resume from
+            // the next iteration.
+            for (const [slug, global] of globalsMap) {
+                const resourceType = `payloadcms:global:${slug}`;
+                if (requestedTypes && !requestedTypes.includes(resourceType)) {
+                    continue;
+                }
+                if (!startFromCursor) {
+                    if (cursor && cursor.type === resourceType) {
+                        startFromCursor = true;
+                        continue;
+                    }
+                    continue;
+                }
+                if (totalFetched >= limit) {
+                    break;
+                }
+                const localizedFields = findLocalizedFields(global.fields);
+                if (localizedFields.length === 0) {
+                    continue;
+                }
+                const doc = await req.payload.findGlobal({ slug, locale: defaultLocale });
+                const { content, contentTypes } = extractContent(doc, localizedFields);
+                if (Object.keys(content).length === 0) {
+                    continue;
+                }
+                const item = {
+                    id: slug,
+                    label: getLabelValue(doc, localizedFields),
+                    content,
+                    contentTypes: Object.keys(contentTypes).length > 0 ? contentTypes : undefined,
+                };
+                response.content.push({ type: resourceType, data: [item] });
+                lastType = resourceType;
+                lastId = slug;
+                totalFetched++;
+            }
             if (lastType && lastId && totalFetched >= limit) {
                 response.cursor = encodeCursor(lastType, lastId);
             }

package/dist/endpoints/settings.d.ts

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

package/dist/endpoints/settings.js

@@ -1,4 +1,4 @@
-import { unauthorizedResponse, validateApiKey } from '../utils/auth.js';
+import { unauthorizedResponse, validateApiKey } from '../utils/auth';
 export function createSettingsEndpoint(pluginConfig) {
     return {
         path: '/reversia/settings',

package/dist/endpoints/trigger-crawl-dashboard.d.ts

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

package/dist/endpoints/trigger-crawl-dashboard.js

@@ -0,0 +1,34 @@
+import { triggerCrawl } from '../trigger-crawl';
+export function createTriggerCrawlDashboardEndpoint(pluginConfig) {
+    return {
+        path: '/reversia/dashboard/trigger-crawl',
+        method: 'post',
+        handler: async (req) => {
+            if (!req.user) {
+                return Response.json({ error: 'Unauthorized' }, { status: 401 });
+            }
+            const body = req.json ? await req.json() : undefined;
+            const types = Array.isArray(body?.types)
+                ? body.types.filter((t) => typeof t === 'string')
+                : undefined;
+            const noCache = Boolean(body?.noCache);
+            try {
+                const result = await triggerCrawl({
+                    apiKey: pluginConfig.apiKey,
+                    baseUrl: pluginConfig.baseUrl,
+                    ...(types && types.length > 0 ? { types } : {}),
+                    ...(noCache ? { noCache: true } : {}),
+                });
+                return Response.json(result);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                req.payload.logger.error({
+                    msg: '[reversia] dashboard trigger-crawl failed',
+                    err: message,
+                });
+                return Response.json({ error: message }, { status: 502 });
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 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';
+import type { ReversiaPluginConfig } from './types';
+export type { TriggerCrawlOptions, TriggerCrawlResult } from './trigger-crawl';
+export { triggerCrawl } from './trigger-crawl';
+export type { ConfirmResourcesSyncResponse, InsertionRequest, InsertionResponse, ResourceDefinition, ResourceItem, ResourceResponse, ReversiaErrorResponse, ReversiaFieldCustom, ReversiaPluginConfig, SettingsResponse, StreamResponse, TranslatableFieldConfig, } from './types';
+export { ReversiaFieldBehavior, ReversiaFieldType } from './types';
 export declare const reversiaPlugin: (pluginConfig: ReversiaPluginConfig) => (config: Config) => Config;
 export default reversiaPlugin;

package/dist/index.js

@@ -1,14 +1,16 @@
-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';
+import { reversiaSyncPendingCollection } from './collections/sync-pending';
+import { createConfirmResourcesSyncEndpoint } from './endpoints/confirm-resources-sync';
+import { createResourceEndpoint } from './endpoints/resource';
+import { createResourcesEndpoint } from './endpoints/resources';
+import { createResourcesDefinitionEndpoint } from './endpoints/resources-definition';
+import { createResourcesInsertEndpoint } from './endpoints/resources-insert';
+import { createResourcesSyncEndpoint } from './endpoints/resources-sync';
+import { createSettingsEndpoint } from './endpoints/settings';
+import { createTriggerCrawlDashboardEndpoint } from './endpoints/trigger-crawl-dashboard';
+import { createAfterChangeHook } from './hooks/after-change';
+import { findLocalizedFields } from './utils/fields';
+export { triggerCrawl } from './trigger-crawl';
+export { ReversiaFieldBehavior, ReversiaFieldType } from './types';
 const APPLIED_MARKER = Symbol.for('payload-plugin-reversia.applied');
 export const reversiaPlugin = (pluginConfig) => (config) => {
     if (pluginConfig.disabled) {
@@ -76,6 +78,7 @@ export const reversiaPlugin = (pluginConfig) => (config) => {
         createResourcesInsertEndpoint(pluginConfig, collectionsMap, globalsMap),
         createConfirmResourcesSyncEndpoint(pluginConfig),
         createSettingsEndpoint(pluginConfig),
+        createTriggerCrawlDashboardEndpoint(pluginConfig),
     ];
     return config;
 };

package/dist/trigger-crawl.d.ts

@@ -0,0 +1,24 @@
+import type { CollectionSlug, GlobalSlug } from 'payload';
+export interface TriggerCrawlOptions {
+    /** Reversia project API key (the same value passed to `reversiaPlugin({ apiKey })`). */
+    apiKey: string;
+    /**
+     * Collection and/or global slugs to crawl. Each slug is prefixed with
+     * `payloadcms:` before being sent to Reversia. Omit/empty → crawl all
+     * enabled resources for the project.
+     */
+    types?: Array<CollectionSlug | GlobalSlug>;
+    /** Bypass cached crawl content. Defaults to `false`. */
+    noCache?: boolean;
+    /**
+     * Override the Reversia API base URL. Defaults to `process.env.REVERSIA_API_URL`
+     * then a built-in production/staging URL.
+     */
+    baseUrl?: string;
+    /** Optional custom fetch (for tests / proxies). Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+export interface TriggerCrawlResult {
+    success: boolean;
+}
+export declare function triggerCrawl(options: TriggerCrawlOptions): Promise<TriggerCrawlResult>;

package/dist/trigger-crawl.js

@@ -0,0 +1,47 @@
+const DEFAULT_BASE_URL = 'https://staging.api.reversia.tech';
+const TYPE_NAMESPACE = 'payloadcms:';
+const TRIGGER_CRAWL_PATH = '/projects/trigger-crawl';
+export async function triggerCrawl(options) {
+    if (typeof options.apiKey !== 'string' || options.apiKey.length === 0) {
+        throw new Error('[reversia] apiKey is required. Pass `TriggerCrawlOptions.apiKey` as a non-empty string.');
+    }
+    const baseUrl = (options.baseUrl ?? process.env.REVERSIA_API_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const normalizedTypes = (options.types ?? [])
+        .filter((t) => typeof t === 'string' && t.length > 0)
+        .map((t) => `${TYPE_NAMESPACE}${t}`);
+    const body = {};
+    if (normalizedTypes.length > 0) {
+        body.types = normalizedTypes;
+    }
+    if (options.noCache) {
+        body.noCache = true;
+    }
+    const fetchImpl = options.fetch ?? fetch;
+    const response = await fetchImpl(`${baseUrl}${TRIGGER_CRAWL_PATH}`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${options.apiKey}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        body: JSON.stringify(body),
+    });
+    if (!response.ok) {
+        let excerpt = '';
+        try {
+            excerpt = (await response.text()).slice(0, 200);
+        }
+        catch {
+            // ignore body read errors — keep the status info
+        }
+        throw new Error(`[reversia] trigger-crawl failed: ${response.status} ${response.statusText}${excerpt ? ` — ${excerpt}` : ''}`);
+    }
+    let parsed = null;
+    try {
+        parsed = (await response.json());
+    }
+    catch {
+        parsed = null;
+    }
+    return { success: parsed?.success !== false };
+}

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { CollectionSlug } from 'payload';
-import type { LeafSegment } from './utils/path-resolver.js';
+import type { LeafSegment } from './utils/path-resolver';
 export interface ReversiaPluginConfig {
     /**
      * API key used by Reversia SaaS to authenticate requests.
@@ -20,6 +20,12 @@ export interface ReversiaPluginConfig {
      * Whether the plugin is disabled. Defaults to false.
      */
     disabled?: boolean;
+    /**
+     * Override the Reversia API base URL used by `triggerCrawl` and the
+     * dashboard button. Defaults to `process.env.REVERSIA_API_URL` then the
+     * built-in production URL.
+     */
+    baseUrl?: string;
 }
 export declare enum ReversiaFieldType {
     TEXT = "TEXT",
@@ -183,6 +189,15 @@ export interface LocalizedFieldInfo {
      * the update.
      */
     hasRequiredLeaf?: boolean;
+    /**
+     * True when a top-level localized scalar is `unique: true`. Used during
+     * insertion to pre-check for cross-document collisions in the target locale
+     * before writing — Reversia may translate two docs' source values to the
+     * same target string, and Payload's unique validator would reject the
+     * second write. Only meaningful for scalars; Payload doesn't support
+     * `unique` on containers.
+     */
+    unique?: boolean;
 }
 export interface ResourceItem {
     id: string;

package/dist/utils/cursor.d.ts

@@ -1,4 +1,4 @@
-import type { Cursor } from '../types.js';
+import type { Cursor } from '../types';
 /**
  * Opaque cursor encoding. Uses JSON in base64url so the delimiter concern
  * (types or ids containing `|`) is eliminated.

package/dist/utils/fields.d.ts

@@ -1,6 +1,6 @@
 import type { Field } from 'payload';
-import type { LocalizedFieldInfo, TranslatableFieldConfig } from '../types.js';
-import { ReversiaFieldType } from '../types.js';
+import type { LocalizedFieldInfo, TranslatableFieldConfig } from '../types';
+import { ReversiaFieldType } from '../types';
 /**
  * Collects one `LocalizedFieldInfo` per top-level field that is itself
  * localized OR that contains at least one localized descendant.

package/dist/utils/fields.js

@@ -1,7 +1,7 @@
-import { ReversiaFieldType } from '../types.js';
-import { applyByKeys, compileKeyMatcher, DEFAULT_RICHTEXT_KEYS, extractByKeys, } from './json-extract.js';
-import { resolveStaticLabel } from './labels.js';
-import { applyTranslationsToContainer, joinPointers, resolveLeafLocations, } from './path-resolver.js';
+import { ReversiaFieldType } from '../types';
+import { applyByKeys, compileKeyMatcher, DEFAULT_RICHTEXT_KEYS, extractByKeys, } from './json-extract';
+import { resolveStaticLabel } from './labels';
+import { applyTranslationsToContainer, joinPointers, resolveLeafLocations, } from './path-resolver';
 function getFieldLabel(field) {
     if (!('name' in field)) {
         return '';
@@ -134,6 +134,7 @@ function describeTopLevelField(field) {
         const maxLength = getNumericProp(field, 'maxLength');
         const minLength = getNumericProp(field, 'minLength');
         const required = getBoolProp(field, 'required');
+        const unique = getBoolProp(field, 'unique');
         return {
             name,
             label,
@@ -151,6 +152,7 @@ function describeTopLevelField(field) {
             ...(maxLength !== undefined && { maxLength }),
             ...(minLength !== undefined && { minLength }),
             ...(required && { hasRequiredLeaf: true }),
+            ...(unique && { unique: true }),
         };
     }
     // Top-level richText / json (localized or not localized but containing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sequoialabs/payload-plugin-reversia",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "author": {
     "name": "Jean Walrave",
     "email": "contact@reversia.tech",
@@ -27,6 +27,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
     }
   },
   "main": "dist/index.js",
@@ -44,14 +48,17 @@
     "prepublishOnly": "bun run test && bun run build"
   },
   "peerDependencies": {
-    "payload": "^3.0.0"
+    "payload": "^3.0.0",
+    "react": "^18.0.0 || ^19.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",
+    "@types/react": "^19.0.0",
     "payload": "^3.0.0",
+    "react": "^19.0.0",
     "typescript": "^5.0.0"
   }
-}
+}