@easyling/sanity-connector 0.0.2-rc.1 → 0.0.2-rc.2

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

@@ -0,0 +1,373 @@
+import { ExtendedDocumentContent } from './contentExtractor';
+/**
+ * Field object structure supporting translation-invariant fields
+ */
+export interface TranslatableField {
+    /** The actual field value */
+    value: unknown;
+    /** Do Not Translate flag - if true, the field should not be translated */
+    dnt?: boolean;
+    /** Type of the field value from Sanity (e.g., 'string', 'number', 'date', 'slug', 'array', 'object') */
+    type?: string;
+}
+export interface TranslationRequest {
+    documentId: string;
+    endpoint: string;
+    payload: TranslationRequestPayload;
+}
+/**
+ * Request payload sent to the translation service
+ *
+ * @example Single locale (backward compatible):
+ * ```json
+ * {
+ *   "content": {
+ *     "body": "<h1>Welcome</h1><p>This is sample content.</p>",
+ *     "title": "Welcome Article",
+ *     "slug": "welcome-article",
+ *     "fields": {
+ *       "author": { "value": "John Doe", "dnt": false },
+ *       "category": { "value": "General", "dnt": true }
+ *     }
+ *   },
+ *   "format": "html",
+ *   "metadata": {
+ *     "documentId": "article-123",
+ *     "documentType": "article",
+ *     "title": "Welcome Article",
+ *     "sourceLanguage": "en",
+ *     "targetLanguage": "es"
+ *   }
+ * }
+ * ```
+ *
+ * @example Multiple locales:
+ * ```json
+ * {
+ *   "content": {
+ *     "body": "<h1>Welcome</h1><p>This is sample content.</p>",
+ *     "title": "Welcome Article",
+ *     "slug": "welcome-article",
+ *     "fields": {
+ *       "author": { "value": "John Doe", "dnt": false },
+ *       "category": { "value": "General", "dnt": true }
+ *     }
+ *   },
+ *   "format": "html",
+ *   "metadata": {
+ *     "documentId": "article-123",
+ *     "documentType": "article",
+ *     "title": "Welcome Article",
+ *     "sourceLanguage": "en",
+ *     "targetLocales": ["es", "fr", "de"]
+ *   }
+ * }
+ * ```
+ */
+export interface TranslationRequestPayload {
+    /** Content to be translated */
+    content: {
+        /** HTML content extracted from Sanity document */
+        body: string;
+        /** Document title */
+        title: string;
+        /** Document slug */
+        slug: string;
+        /** Additional document fields with translation control via dnt flag */
+        fields: Record<string, TranslatableField | any>;
+    };
+    /** Content format - always 'html' for this plugin */
+    format: 'html';
+    /** Metadata about the document and translation request */
+    metadata: {
+        /** Unique identifier for the source document */
+        documentId: string;
+        /** Sanity document type (e.g., 'article', 'page', 'post') */
+        documentType: string;
+        /** Document title (same as content.title) */
+        title: string;
+        /** Source language code (optional, e.g., 'en', 'fr', 'es') */
+        sourceLanguage?: string;
+        /** Target language code (optional, e.g., 'en', 'fr', 'es') - for backward compatibility */
+        targetLanguage?: string;
+        /** Array of target locale codes (e.g., ['es', 'fr', 'de']) - for multi-locale support */
+        targetLocales?: string[];
+    };
+}
+/**
+ * Translated document structure
+ */
+export interface TranslatedDocument {
+    /**
+     * Translated HTML content
+     * - Must be valid HTML
+     * - Should preserve original structure
+     * - Will be converted back to Portable Text by the plugin
+     */
+    body: string;
+    /**
+     * Translated document title
+     * - Must be non-empty string
+     * - No HTML tags allowed
+     */
+    title: string;
+    /**
+     * Translated/localized slug
+     * - Must contain only lowercase letters, numbers, hyphens, and underscores
+     * - Should be URL-friendly and unique
+     * - Pattern: ^[a-z0-9-_]+$
+     */
+    slug: string;
+    /**
+     * Additional translated document fields
+     * - Must be an object (can be empty)
+     * - Translatable text fields should be translated
+     * - Non-translatable fields (dates, IDs) should be preserved
+     * - Fields marked with dnt=true should remain unchanged
+     */
+    fields: Record<string, TranslatableField>;
+    /**
+     * Target locale code for this translation (e.g., 'es', 'fr', 'de')
+     */
+    locale?: string;
+}
+/**
+ * Response format expected from the translation service
+ *
+ * @example Single locale success response:
+ * ```json
+ * {
+ *   "success": true,
+ *   "translatedDocuments": [
+ *     {
+ *       "body": "<h1>Translated HTML</h1><p>Translated content...</p>",
+ *       "title": "Translated Title",
+ *       "slug": "translated-slug",
+ *       "fields": {
+ *         "author": { "value": "Translated Author", "dnt": false },
+ *         "category": { "value": "General", "dnt": true }
+ *       },
+ *       "locale": "es"
+ *     }
+ *   ],
+ *   "sourceLocale": "en",
+ *   "requestId": "req-123"
+ * }
+ * ```
+ *
+ * @example Multi-locale success response:
+ * ```json
+ * {
+ *   "success": true,
+ *   "translatedDocuments": [
+ *     {
+ *       "body": "<h1>HTML traducido</h1><p>Contenido traducido...</p>",
+ *       "title": "Título traducido",
+ *       "slug": "titulo-traducido",
+ *       "fields": {
+ *         "author": { "value": "Autor traducido", "dnt": false },
+ *         "category": { "value": "General", "dnt": true }
+ *       },
+ *       "locale": "es"
+ *     },
+ *     {
+ *       "body": "<h1>HTML traduit</h1><p>Contenu traduit...</p>",
+ *       "title": "Titre traduit",
+ *       "slug": "titre-traduit",
+ *       "fields": {
+ *         "author": { "value": "Auteur traduit", "dnt": false },
+ *         "category": { "value": "General", "dnt": true }
+ *       },
+ *       "locale": "fr"
+ *     }
+ *   ],
+ *   "sourceLocale": "en",
+ *   "requestId": "req-123"
+ * }
+ * ```
+ *
+ * @example Error Response:
+ * ```json
+ * {
+ *   "success": false,
+ *   "error": "Translation failed: Unsupported language pair",
+ *   "requestId": "req-123"
+ * }
+ * ```
+ */
+export interface TranslationResponse {
+    /** Indicates whether the translation was successful */
+    success: boolean;
+    /**
+     * Array of translated documents (required when success is true)
+     * Contains one translated document per target locale
+     */
+    translatedDocuments?: TranslatedDocument[];
+    /** Source locale code (e.g., 'en') */
+    sourceLocale?: string;
+    /**
+     * Error message (required when success is false)
+     * Should provide a clear description of what went wrong
+     */
+    error?: string;
+    /**
+     * Optional unique request identifier for tracking
+     * Useful for debugging and request correlation
+     */
+    requestId?: string;
+    /** @deprecated Use translatedDocuments array instead */
+    translatedContent?: TranslatedDocument;
+    /** @deprecated Use translatedDocuments array instead */
+    translations?: {
+        [localeCode: string]: {
+            content: TranslatedDocument;
+            status: 'completed' | 'failed' | 'pending';
+            error?: string;
+        };
+    };
+}
+export interface BulkTranslationSummary {
+    totalDocuments: number;
+    processedDocuments: number;
+    failedDocuments: number;
+    requests: TranslationRequest[];
+    responses: TranslationResponse[];
+}
+export declare class TranslationService {
+    private placeholderEndpoint;
+    private accessToken?;
+    private projectId?;
+    private requestContentType;
+    private responseAcceptHeader;
+    constructor(placeholderEndpoint?: string, requestContentType?: 'application/json' | 'application/x-protobuf', responseAcceptHeader?: 'application/json' | 'application/x-protobuf');
+    /**
+     * Infer the Sanity field type from a value
+     *
+     * @param value - The field value to inspect
+     * @returns The inferred Sanity type string
+     */
+    private inferSanityType;
+    /**
+     * Set authentication token and project ID
+     * Requirements: 4.1, 4.2, 4.3
+     *
+     * @param token - Access token for API authentication
+     * @param projectId - Project ID to include in requests
+     */
+    setAuthToken(token: string, projectId: string): void;
+    /**
+     * Clear authentication data
+     */
+    clearAuth(): void;
+    /**
+     * Update configuration for content types and endpoint
+     * Allows partial updates - only provided parameters will be updated
+     * Requirements: 1.1, 2.3, 3.3
+     *
+     * @param endpoint - Optional translation API endpoint URL
+     * @param requestContentType - Optional request Content-Type header value
+     * @param responseAcceptHeader - Optional response Accept header value
+     */
+    setConfiguration(endpoint?: string, requestContentType?: 'application/json' | 'application/x-protobuf', responseAcceptHeader?: 'application/json' | 'application/x-protobuf'): void;
+    /**
+     * Convert internal payload to Protocol Buffer binary format
+     * Requirements: Uses @easyling/sanity protobuf library
+     *
+     * @param payload - Internal translation request payload
+     * @returns Binary protobuf message
+     */
+    private convertPayloadToProtobuf;
+    /**
+     * Convert protobuf payload to JSON for logging purposes only
+     *
+     * @param payload - Internal translation request payload
+     * @returns JSON representation for logging
+     */
+    private convertPayloadToProtobufJSON;
+    /**
+     * Normalize field values to ensure consistency
+     * Extracts values from TranslatableField objects and handles various formats
+     */
+    private normalizeTranslatedFields;
+    /**
+     * Convert binary protobuf response to internal format
+     * Requirements: Uses @easyling/sanity protobuf library
+     *
+     * @param binaryData - Binary protobuf response data
+     * @returns Internal translation response format
+     */
+    private convertProtobufBinaryToResponse;
+    /**
+     * Convert protobuf JSON response back to internal format (for legacy support)
+     * Requirements: Uses @easyling/sanity protobuf library
+     *
+     * @param jsonData - JSON response data
+     * @returns Internal translation response format
+     */
+    private convertProtobufJSONToResponse;
+    /**
+     * Prepare a translation request for a single document
+     * Requirements: 1.2, 1.3, 3.3, 2.5, 2.7
+     *
+     * @param content - Document content to translate
+     * @param documentType - Type of the document
+     * @param sourceLanguage - Source language code (optional)
+     * @param targetLanguage - Single target language code (optional, for backward compatibility)
+     * @param targetLocales - Array of target locale codes (optional, for multi-locale support)
+     */
+    prepareTranslationRequest(content: ExtendedDocumentContent, documentType?: string, sourceLanguage?: string, targetLanguage?: string, targetLocales?: string[]): TranslationRequest;
+    /**
+     * Translate a single document
+     * Requirements: 1.2, 1.3, 3.3, 2.5, 2.7
+     *
+     * @param content - Document content to translate
+     * @param documentType - Type of the document
+     * @param sourceLanguage - Source language code (optional)
+     * @param targetLanguage - Single target language code (optional, for backward compatibility)
+     * @param targetLocales - Array of target locale codes (optional, for multi-locale support)
+     */
+    translateDocument(content: ExtendedDocumentContent, documentType?: string, sourceLanguage?: string, targetLanguage?: string, targetLocales?: string[]): Promise<TranslationResponse>;
+    /**
+     * Send translation request to the configured endpoint
+     *
+     * Uses the @easyling/sanity Protocol Buffer library to format messages as JSON
+     * (not binary protobuf) for better compatibility with various backends.
+     * Handles the new array-based response format with backward compatibility.
+     * The service now expects translatedDocuments as an array, but will convert
+     * legacy formats (translatedContent or translations object) to the new format.
+     *
+     * Supports dual mode operation:
+     * - Authenticated mode: Uses Bearer token authentication when configured
+     * - Legacy mode: Works without authentication for backward compatibility
+     */
+    sendTranslationRequest(request: TranslationRequest): Promise<TranslationResponse>;
+    /**
+     * Log translation request to console for verification
+     * Requirements: 1.3, 2.4
+     */
+    logTranslationRequest(request: TranslationRequest): void;
+    /**
+     * Process bulk translation for multiple documents
+     * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.7
+     *
+     * @param contents - Array of document contents to translate
+     * @param documentType - Type of the documents
+     * @param sourceLanguage - Source language code (optional)
+     * @param targetLanguage - Single target language code (optional, for backward compatibility)
+     * @param targetLocales - Array of target locale codes (optional, for multi-locale support)
+     */
+    processBulkTranslation(contents: ExtendedDocumentContent[], documentType?: string, sourceLanguage?: string, targetLanguage?: string, targetLocales?: string[]): Promise<BulkTranslationSummary>;
+    /**
+     * Log bulk translation summary
+     * Requirements: 2.5
+     */
+    private logBulkTranslationSummary;
+    /**
+     * Update the placeholder endpoint
+     */
+    setEndpoint(endpoint: string): void;
+    /**
+     * Get the current endpoint
+     */
+    getEndpoint(): string;
+}

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

@@ -0,0 +1,123 @@
+/**
+ * Unified Configuration Storage Adapter
+ *
+ * Provides centralized persistence for all plugin configuration using Sanity's document storage.
+ * This replaces separate OAuth and Locale storage adapters with a single unified configuration.
+ *
+ * Stores in a single EL_PluginConfiguration document:
+ * - OAuth configuration (projectId, accessToken)
+ * - Locale definitions and settings
+ * - DNT field mappings by document type
+ */
+import { SanityClient } from 'sanity';
+import { OAuthConfig } from '../types/oauth';
+import { LocaleConfig } from '../types/locale';
+/**
+ * Unified plugin configuration structure
+ */
+export interface UnifiedPluginConfig {
+    /** OAuth/authentication settings */
+    projectId?: string;
+    accessToken?: string;
+    /** Translation settings */
+    translationApiEndpoint?: string;
+    requestContentType?: 'application/json' | 'application/x-protobuf';
+    responseAcceptHeader?: 'application/json' | 'application/x-protobuf';
+    defaultDocumentCreationMode?: 'draft' | 'published';
+    /** Locale configuration */
+    locales?: LocaleConfig['locales'];
+    defaultLocale?: string;
+    /** DNT field map: { [documentType]: { [fieldPath]: boolean } } */
+    dntFieldMap?: Record<string, Record<string, boolean>>;
+    /** Configuration version for migrations */
+    version?: string;
+    /** Last updated timestamp */
+    lastUpdated?: string;
+}
+/**
+ * Unified configuration storage adapter for Sanity
+ */
+export declare class UnifiedConfigStorage {
+    private client;
+    constructor(client: SanityClient);
+    /**
+     * Convert array-based DNT configuration (schema format) to map format (internal use)
+     */
+    private convertDNTArrayToMap;
+    /**
+     * Convert map-based DNT configuration (internal format) to array format (schema format)
+     */
+    private convertDNTMapToArray;
+    /**
+     * Load complete unified configuration from Sanity
+     */
+    load(): Promise<UnifiedPluginConfig | null>;
+    /**
+     * Save complete unified configuration to Sanity
+     */
+    save(config: UnifiedPluginConfig): Promise<void>;
+    /**
+     * Update only specific fields without overwriting entire config
+     */
+    update(updates: Partial<UnifiedPluginConfig>): Promise<void>;
+    /**
+     * Delete the unified configuration document
+     */
+    delete(): Promise<void>;
+    /**
+     * Load only OAuth configuration
+     */
+    loadOAuth(): Promise<OAuthConfig | null>;
+    /**
+     * Save OAuth configuration
+     */
+    saveOAuth(oauthConfig: OAuthConfig): Promise<void>;
+    /**
+     * Load only locale configuration
+     */
+    loadLocale(): Promise<LocaleConfig | null>;
+    /**
+     * Save locale configuration
+     */
+    saveLocale(localeConfig: LocaleConfig): Promise<void>;
+    /**
+     * Get DNT field map for a specific document type
+     */
+    getDNTFieldsForType(documentType: string): Promise<Record<string, boolean>>;
+    /**
+     * Set DNT status for a field in a document type
+     */
+    setDNTField(documentType: string, fieldPath: string, dnt: boolean): Promise<void>;
+    /**
+     * Toggle DNT status for a field in a document type
+     */
+    toggleDNTField(documentType: string, fieldPath: string): Promise<boolean>;
+    /**
+     * Get DNT status for a specific field in a document type
+     */
+    getDNTFieldStatus(documentType: string, fieldPath: string): Promise<boolean>;
+    /**
+     * Clear all DNT fields for a document type
+     */
+    clearDNTFieldsForType(documentType: string): Promise<void>;
+    /**
+     * Get all DNT field mappings
+     */
+    getAllDNTFields(): Promise<Record<string, Record<string, boolean>>>;
+    /**
+     * Get translation API endpoint with fallback to default
+     */
+    getTranslationEndpoint(): Promise<string>;
+    /**
+     * Get request content type with fallback to default
+     */
+    getRequestContentType(): Promise<'application/json' | 'application/x-protobuf'>;
+    /**
+     * Get response accept header with fallback to default
+     */
+    getResponseAcceptHeader(): Promise<'application/json' | 'application/x-protobuf'>;
+    /**
+     * Get default document creation mode with fallback to default
+     */
+    getDefaultDocumentCreationMode(): Promise<'draft' | 'published'>;
+}

package/dist-types/test-utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Test utilities for component testing
+ */
+import { ReactElement } from 'react';
+import { RenderOptions } from '@testing-library/react';
+declare const customRender: (ui: ReactElement, options?: Omit<RenderOptions, "wrapper">) => import("@testing-library/react").RenderResult<typeof import("@testing-library/dom/types/queries"), HTMLElement, HTMLElement>;
+export * from '@testing-library/react';
+export { customRender as render };

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

@@ -0,0 +1,106 @@
+/**
+ * Dialog system type definitions
+ * Requirements: 5.1, 5.2, 5.3
+ */
+/**
+ * Base dialog configuration options
+ */
+export interface BaseDialogOptions {
+    /** Dialog title */
+    title: string;
+    /** Dialog message or content */
+    message: string;
+    /** Whether the dialog can be closed by clicking outside */
+    closable?: boolean;
+    /** Custom CSS class for styling */
+    className?: string;
+}
+/**
+ * Confirmation dialog options
+ */
+export interface ConfirmationDialogOptions extends BaseDialogOptions {
+    /** Text for the confirm button */
+    confirmText?: string;
+    /** Text for the cancel button */
+    cancelText?: string;
+    /** Visual tone of the dialog */
+    tone?: 'primary' | 'critical' | 'caution';
+    /** Additional details to display */
+    details?: string;
+}
+/**
+ * Success dialog options
+ */
+export interface SuccessDialogOptions extends BaseDialogOptions {
+    /** Additional details about the success */
+    details?: string;
+    /** Auto-close timeout in milliseconds */
+    autoCloseTimeout?: number;
+}
+/**
+ * Error dialog options
+ */
+export interface ErrorDialogOptions extends BaseDialogOptions {
+    /** Error object for detailed information */
+    error?: Error;
+    /** Whether to show a retry button */
+    showRetry?: boolean;
+    /** Text for the retry button */
+    retryText?: string;
+}
+/**
+ * Locale selection dialog options
+ */
+export interface LocaleSelectionDialogOptions extends BaseDialogOptions {
+    /** Available locales to choose from */
+    availableLocales: LocaleDefinition[];
+    /** Currently selected locale codes */
+    selectedLocales: string[];
+    /** Documents being translated (for context) */
+    selectedDocuments: any[];
+    /** Translation mode */
+    mode: 'single' | 'bulk';
+    /** Whether multiple locales can be selected */
+    allowMultiple?: boolean;
+    /** Whether locale selection is required */
+    required?: boolean;
+    /** Whether to show creation mode option in the dialog */
+    showCreationModeOption?: boolean;
+    /** Default creation mode to pre-select */
+    defaultCreationMode?: 'draft' | 'published';
+}
+/**
+ * Locale selection result
+ */
+export interface LocaleSelectionResult {
+    /** Selected locale codes */
+    locales: string[];
+    /** Selected creation mode (if showCreationModeOption was true) */
+    creationMode?: 'draft' | 'published';
+}
+/**
+ * Dialog result types
+ */
+export type DialogResult<T = unknown> = {
+    /** Whether the dialog was confirmed or cancelled */
+    confirmed: boolean;
+    /** Result data from the dialog */
+    data?: T;
+};
+/**
+ * Dialog manager interface for centralized dialog handling
+ */
+export interface DialogManager {
+    /** Show a confirmation dialog */
+    showConfirmation(options: ConfirmationDialogOptions): Promise<boolean>;
+    /** Show a locale selection dialog */
+    showLocaleSelection(options: LocaleSelectionDialogOptions): Promise<LocaleSelectionResult>;
+    /** Show a success notification */
+    showSuccess(options: SuccessDialogOptions): void;
+    /** Show an error dialog */
+    showError(options: ErrorDialogOptions): Promise<boolean>;
+    /** Close all open dialogs */
+    closeAll(): void;
+}
+import type { LocaleDefinition } from './locale';
+export type { LocaleDefinition } from './locale';

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

@@ -0,0 +1,83 @@
+/**
+ * DNT (Do Not Translate) field preferences types
+ */
+export interface DNTFieldPreference {
+    /** Field path (e.g., 'title', 'content.description') */
+    fieldPath: string;
+    /** Whether this field should not be translated */
+    dnt: boolean;
+    /** Timestamp when preference was set */
+    updatedAt?: string;
+}
+/**
+ * Legacy document-specific DNT preferences (deprecated)
+ * @deprecated Use document-type-based DNT configuration instead
+ */
+export interface DNTPreferences {
+    /** Document ID these preferences apply to */
+    documentId: string;
+    /** Document type */
+    documentType: string;
+    /** Field-level DNT preferences */
+    fields: Record<string, boolean>;
+    /** Last updated timestamp */
+    updatedAt: string;
+}
+/**
+ * Document-type-based DNT field configuration
+ * When a field is marked DNT for a document type, it applies to ALL documents of that type
+ */
+export interface DNTTypeConfig {
+    /** Document type (e.g., 'product', 'article', 'page') */
+    documentType: string;
+    /** Field-level DNT preferences: { [fieldPath]: dnt } */
+    fields: Record<string, boolean>;
+}
+/**
+ * DNT Storage interface - supports document-type-based configuration
+ */
+export interface DNTStorage {
+    /**
+     * Get DNT field configuration for a document type
+     * @param documentType - The type of document (e.g., 'product', 'article')
+     * @returns Map of field paths to DNT status
+     */
+    getFieldsForType(documentType: string): Promise<Record<string, boolean>>;
+    /**
+     * Set DNT status for a specific field in a document type
+     * @param documentType - The type of document
+     * @param fieldPath - The field path
+     * @param dnt - Whether the field should not be translated
+     */
+    setFieldDNT(documentType: string, fieldPath: string, dnt: boolean): Promise<void>;
+    /**
+     * Toggle DNT status for a field in a document type
+     * @param documentType - The type of document
+     * @param fieldPath - The field path
+     * @returns The new DNT status
+     */
+    toggleFieldDNT(documentType: string, fieldPath: string): Promise<boolean>;
+    /**
+     * Get DNT status for a specific field in a document type
+     * @param documentType - The type of document
+     * @param fieldPath - The field path
+     * @returns Whether the field is marked as DNT
+     */
+    getFieldDNT(documentType: string, fieldPath: string): Promise<boolean>;
+    /**
+     * Clear all DNT fields for a document type
+     * @param documentType - The type of document
+     */
+    clearFieldsForType(documentType: string): Promise<void>;
+    /**
+     * Get all DNT configurations (all document types)
+     * @returns Map of document types to their field DNT configurations
+     */
+    getAllDNTFields(): Promise<Record<string, Record<string, boolean>>>;
+    /** @deprecated Use getFieldsForType instead */
+    getPreferences?(documentId: string): Promise<DNTPreferences | null>;
+    /** @deprecated Use setFieldDNT instead */
+    savePreferences?(preferences: DNTPreferences): Promise<void>;
+    /** @deprecated Use clearFieldsForType instead */
+    clearPreferences?(documentId: string): Promise<void>;
+}