@easyling/sanity-connector 1.3.0-rc.9 → 1.4.0

package/dist-types/components/dialogs/LocaleSelectionDialog.d.ts

@@ -6,6 +6,20 @@
  */
 import React from 'react';
 import type { LocaleDefinition } from '../../types/locale';
+import type { CollisionResolutionMode, ExistingDocumentHandling } from '../../types/pluginConfig';
+/**
+ * Result returned when user confirms locale selection
+ */
+export interface LocaleSelectionResult {
+    /** Selected locale codes */
+    locales: string[];
+    /** Document creation mode */
+    creationMode?: 'draft' | 'published';
+    /** Collision resolution mode (if override is enabled) */
+    collisionResolutionMode?: CollisionResolutionMode;
+    /** Existing document handling (if override is enabled) */
+    existingDocumentHandling?: ExistingDocumentHandling;
+}
 export interface LocaleSelectionDialogProps {
     /** Whether the dialog is open */
     open: boolean;
@@ -29,8 +43,16 @@ export interface LocaleSelectionDialogProps {
     showCreationModeOption?: boolean;
     /** Default creation mode to pre-select */
     defaultCreationMode?: 'draft' | 'published';
+    /** Whether to show collision resolution override options */
+    showCollisionResolutionOverride?: boolean;
+    /** Default collision resolution mode from config */
+    defaultCollisionResolutionMode?: CollisionResolutionMode;
+    /** Default existing document handling from config */
+    defaultExistingDocumentHandling?: ExistingDocumentHandling;
     /** Callback when user confirms selection */
     onConfirm: (selectedLocales: string[], creationMode?: 'draft' | 'published') => void;
+    /** Enhanced callback with full result object */
+    onConfirmWithOptions?: (result: LocaleSelectionResult) => void;
     /** Callback when user cancels */
     onCancel: () => void;
 }

package/dist-types/services/collisionDetectionService.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Collision Detection Service
+ * Requirements: Translation Collision Handling - EARS 2.1, 2.2
+ *
+ * Detects existing translated documents for the same source document and target locale
+ * to enable collision resolution handling.
+ */
+import { SanityClient, SanityDocument } from 'sanity';
+/**
+ * Result of a collision detection check
+ */
+export interface CollisionResult {
+    /** Whether a collision was detected */
+    detected: boolean;
+    /** The existing translated document if collision was detected */
+    existingDocument?: SanityDocument;
+    /** How the collision was identified */
+    matchedBy?: 'parent' | 'slug-locale';
+}
+/**
+ * Options for collision detection
+ */
+export interface CollisionDetectionOptions {
+    /** The source document ID (the original document being translated) */
+    sourceDocumentId: string;
+    /** The target locale code for the translation */
+    targetLocale: string;
+    /** The slug of the translated document (optional, used for slug-locale matching) */
+    slug?: string;
+    /** The document type to search within */
+    documentType?: string;
+}
+/**
+ * Error type for collision detection operations
+ */
+export declare class CollisionDetectionError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+/**
+ * Service for detecting translation collisions
+ *
+ * A collision occurs when a translated document already exists for the same
+ * source document and target locale. The service identifies collisions using:
+ * 1. Parent reference matching: parentDocument._ref == sourceDocumentId AND locale == targetLocale
+ * 2. Slug-locale matching: slug.current == slug AND locale == targetLocale
+ */
+export declare class CollisionDetectionService {
+    private client;
+    constructor(client: SanityClient);
+    /**
+     * Detect if a collision exists for the given source document and target locale
+     *
+     * @param options - Options specifying the source document, target locale, and optional slug
+     * @returns CollisionResult indicating whether a collision was found and details
+     */
+    detectCollision(options: CollisionDetectionOptions): Promise<CollisionResult>;
+    /**
+     * Find an existing document by parent reference and locale
+     *
+     * @param sourceDocumentId - The ID of the source/parent document
+     * @param targetLocale - The target locale code
+     * @param documentType - Optional document type to filter by
+     */
+    private findByParentReference;
+    /**
+     * Find an existing document by slug and locale
+     *
+     * @param slug - The document slug to match
+     * @param targetLocale - The target locale code
+     * @param documentType - Optional document type to filter by
+     */
+    private findBySlugAndLocale;
+    /**
+     * Check if multiple collisions exist for bulk translation operations
+     *
+     * @param sourceDocumentId - The source document being translated
+     * @param targetLocales - Array of target locale codes
+     * @param slug - Optional slug for slug-locale matching
+     * @param documentType - Optional document type to filter by
+     * @returns Map of locale code to collision result
+     */
+    detectBulkCollisions(sourceDocumentId: string, targetLocales: string[], slug?: string, documentType?: string): Promise<Map<string, CollisionResult>>;
+}

package/dist-types/services/documentCreationService.d.ts

@@ -1,5 +1,6 @@
 import { SanityDocument, SanityClient } from 'sanity';
 import { TranslationResponse } from './translationService';
+import { CollisionResolutionMode, ExistingDocumentHandling } from '../types/pluginConfig';
 /**
  * Options for document creation from translation
  */
@@ -31,6 +32,18 @@ export interface DocumentCreationOptions {
      * Used to write translated content back to the correct location.
      */
     bodyFieldName?: string;
+    /**
+     * How to handle collisions when a translated document already exists.
+     * - 'replace': Overwrite the existing document with new translations
+     * - 'create': Create a new document (default behavior if not specified)
+     */
+    collisionResolutionMode?: CollisionResolutionMode;
+    /**
+     * How to handle the existing document when creating a new one (only for 'create' mode).
+     * - 'draft': Set the existing document to draft state
+     * - 'delete': Delete the existing document
+     */
+    existingDocumentHandling?: ExistingDocumentHandling;
 }
 export interface SlugFallbackInfo {
     documentId: string;
@@ -39,12 +52,29 @@ export interface SlugFallbackInfo {
     locale: string;
     reason: string;
 }
+/**
+ * Information about a collision that was detected and resolved
+ */
+export interface CollisionResolutionInfo {
+    /** Whether a collision was detected */
+    collisionDetected: boolean;
+    /** The resolution action that was taken */
+    resolutionAction?: 'replaced' | 'created_new' | 'none';
+    /** The ID of the document that was replaced, updated, or deleted */
+    existingDocumentId?: string;
+    /** How the existing document was handled (for 'create' mode) */
+    existingDocumentAction?: 'set_to_draft' | 'deleted' | 'none';
+    /** How the collision was detected */
+    matchedBy?: 'parent' | 'slug-locale';
+}
 export interface DocumentCreationResult {
     success: boolean;
     documentId?: string;
     document?: SanityDocument;
     error?: string;
     slugFallback?: SlugFallbackInfo;
+    /** Information about collision detection and resolution */
+    collisionInfo?: CollisionResolutionInfo;
 }
 export interface BulkDocumentCreationResult {
     totalDocuments: number;
@@ -63,12 +93,48 @@ export interface RollbackInfo {
 export declare class DocumentCreationService {
     private client;
     private defaultCreationMode;
+    private collisionDetectionService;
+    private defaultCollisionResolutionMode;
+    private defaultExistingDocumentHandling;
     constructor(client: SanityClient, defaultCreationMode?: 'draft' | 'published');
     /**
      * Set the default document creation mode
      * @param mode - The creation mode to use by default ('draft' or 'published')
      */
     setDefaultCreationMode(mode: 'draft' | 'published'): void;
+    /**
+     * Set the default collision resolution mode
+     * @param mode - How to handle collisions ('replace' or 'create')
+     */
+    setDefaultCollisionResolutionMode(mode: CollisionResolutionMode): void;
+    /**
+     * Set the default existing document handling mode
+     * @param handling - How to handle existing documents when creating new ('draft' or 'delete')
+     */
+    setDefaultExistingDocumentHandling(handling: ExistingDocumentHandling): void;
+    /**
+     * Configure collision resolution defaults
+     * @param mode - Collision resolution mode
+     * @param handling - Existing document handling (only applicable when mode is 'create')
+     */
+    setCollisionResolutionConfig(mode: CollisionResolutionMode, handling?: ExistingDocumentHandling): void;
+    /**
+     * Replace an existing document with new translated content
+     * Requirements: EARS 4 - Resolution Behavior - Replace
+     *
+     * @param existingDocument - The document to replace
+     * @param newDocument - The new translated document content
+     * @param creationMode - Whether to create as draft or published
+     */
+    private replaceExistingDocument;
+    /**
+     * Handle an existing document when creating a new translation (for 'create' mode)
+     * Requirements: EARS 5 - Resolution Behavior - Create
+     *
+     * @param existingDocument - The existing document to handle
+     * @param handling - How to handle the existing document ('draft' or 'delete')
+     */
+    private handleExistingDocument;
     /**
      * Create a new Sanity document from translation response
      * Requirements: 1.1, 1.2, 2.1, 3.2, 3.4

package/dist-types/services/unifiedConfigStorage.d.ts

@@ -12,6 +12,7 @@
 import { SanityClient } from 'sanity';
 import { OAuthConfig } from '../types/oauth';
 import { LocaleConfig } from '../types/locale';
+import { CollisionResolutionMode, ExistingDocumentHandling } from '../types/pluginConfig';
 /**
  * Unified plugin configuration structure
  */
@@ -24,6 +25,9 @@ export interface UnifiedPluginConfig {
     requestContentType?: 'application/json' | 'application/x-protobuf';
     responseAcceptHeader?: 'application/json' | 'application/x-protobuf';
     defaultDocumentCreationMode?: 'draft' | 'published';
+    /** Collision resolution settings */
+    collisionResolutionMode?: CollisionResolutionMode;
+    existingDocumentHandling?: ExistingDocumentHandling;
     /** Locale configuration */
     locales?: LocaleConfig['locales'];
     defaultLocale?: string;
@@ -122,6 +126,27 @@ export declare class UnifiedConfigStorage {
      * Get default document creation mode with fallback to default
      */
     getDefaultDocumentCreationMode(): Promise<'draft' | 'published'>;
+    /**
+     * Get collision resolution mode with fallback to default ('replace')
+     */
+    getCollisionResolutionMode(): Promise<CollisionResolutionMode>;
+    /**
+     * Get existing document handling mode with fallback to default ('draft')
+     * Only applicable when collision resolution mode is 'create'
+     */
+    getExistingDocumentHandling(): Promise<ExistingDocumentHandling>;
+    /**
+     * Get complete collision resolution configuration
+     * Returns both the resolution mode and existing document handling settings
+     */
+    getCollisionResolutionConfig(): Promise<{
+        collisionResolutionMode: CollisionResolutionMode;
+        existingDocumentHandling: ExistingDocumentHandling;
+    }>;
+    /**
+     * Set collision resolution configuration
+     */
+    setCollisionResolutionConfig(mode: CollisionResolutionMode, handling?: ExistingDocumentHandling): Promise<void>;
     /**
      * Get debug mode status
      */

package/dist-types/types/dialog.d.ts

@@ -68,6 +68,12 @@ export interface LocaleSelectionDialogOptions extends BaseDialogOptions {
     showCreationModeOption?: boolean;
     /** Default creation mode to pre-select */
     defaultCreationMode?: 'draft' | 'published';
+    /** Whether to show collision resolution override options */
+    showCollisionResolutionOverride?: boolean;
+    /** Default collision resolution mode from config */
+    defaultCollisionResolutionMode?: CollisionResolutionMode;
+    /** Default existing document handling from config */
+    defaultExistingDocumentHandling?: ExistingDocumentHandling;
 }
 /**
  * Locale selection result
@@ -77,6 +83,10 @@ export interface LocaleSelectionResult {
     locales: string[];
     /** Selected creation mode (if showCreationModeOption was true) */
     creationMode?: 'draft' | 'published';
+    /** Collision resolution mode (if override was enabled) */
+    collisionResolutionMode?: CollisionResolutionMode;
+    /** Existing document handling (if override was enabled) */
+    existingDocumentHandling?: ExistingDocumentHandling;
 }
 /**
  * Dialog result types
@@ -103,4 +113,6 @@ export interface DialogManager {
     closeAll(): void;
 }
 import type { LocaleDefinition } from './locale';
+import type { CollisionResolutionMode, ExistingDocumentHandling } from './pluginConfig';
 export type { LocaleDefinition } from './locale';
+export type { CollisionResolutionMode, ExistingDocumentHandling } from './pluginConfig';

package/dist-types/types/pluginConfig.d.ts

@@ -14,6 +14,20 @@ export type DocumentCreationMode = 'draft' | 'published';
  * Specifies the serialization format for translation API communication
  */
 export type ContentType = 'application/json' | 'application/x-protobuf';
+/**
+ * Collision resolution mode options
+ * Determines how to handle existing translated documents when a collision is detected
+ * - 'replace': Overwrite the existing translated document with new translations
+ * - 'create': Create a new translated document alongside the existing one
+ */
+export type CollisionResolutionMode = 'replace' | 'create';
+/**
+ * Existing document handling options (only applicable when CollisionResolutionMode is 'create')
+ * Determines what happens to the existing translated document when creating a new one
+ * - 'draft': Set the existing document to draft state
+ * - 'delete': Delete the existing document
+ */
+export type ExistingDocumentHandling = 'draft' | 'delete';
 /**
  * Complete plugin configuration interface
  * Represents all configurable settings for the Easyling Translation Plugin
@@ -31,6 +45,10 @@ export interface PluginConfiguration {
     responseAcceptHeader?: ContentType;
     /** Default mode for creating translated documents (draft or published) */
     defaultDocumentCreationMode?: DocumentCreationMode;
+    /** How to handle collisions when a translated document already exists for the same source and locale */
+    collisionResolutionMode?: CollisionResolutionMode;
+    /** How to handle existing documents when creating new translations (only applicable when mode is 'create') */
+    existingDocumentHandling?: ExistingDocumentHandling;
     /** Array of configured locales for translation */
     locales?: LocaleDefinition[];
     /** Default source locale code */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easyling/sanity-connector",
-  "version": "1.3.0-rc.9",
+  "version": "1.4.0",
   "description": "A *Sanity Studio v4* plugin that enables document translation with support for single and bulk operations, using Easyling's AI translation capabilities.",
   "main": "dist/index.js",
   "module": "dist/index.js",