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

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

@@ -0,0 +1,11 @@
+/**
+ * Type definitions index
+ * Centralized exports for all plugin types
+ */
+export type { LocaleDefinition, LocaleConfig, LocaleValidationResult, LocaleSelectionOptions } from './locale';
+export type { BaseDialogOptions, ConfirmationDialogOptions, SuccessDialogOptions, ErrorDialogOptions, LocaleSelectionDialogOptions, DialogResult, DialogManager } from './dialog';
+export type { EnhancedTranslationRequest, EnhancedTranslationResponse, TranslationProgress, BulkTranslationRequest, EnhancedBulkTranslationSummary, TranslationRequestPayload, TranslationResponse, TranslatableField } from './translation';
+export type { OAuthConfig, AuthenticationResult, StoredAuthData, AuthState, AuthStateData } from './oauth';
+export { OAuthErrorType, OAuthError } from './oauth';
+export type { DNTFieldPreference, DNTPreferences, DNTTypeConfig, DNTStorage } from './dnt';
+export type { PluginConfiguration, DocumentCreationMode, ContentType } from './pluginConfig';

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

@@ -0,0 +1,115 @@
+/**
+ * Locale configuration type definitions
+ * Requirements: 5.1, 5.2, 5.3
+ */
+/**
+ * Individual locale definition with metadata
+ */
+export interface LocaleDefinition {
+    /** Locale code in ISO 639-1 + ISO 3166-1 format (e.g., "en-US", "fr-FR") */
+    code: string;
+    /** Human-readable display name (e.g., "English (United States)") */
+    displayName: string;
+    /** Whether this locale is enabled for translation */
+    enabled: boolean;
+    /** Timestamp when this locale was created */
+    createdAt: string;
+    /** Timestamp when this locale was last updated */
+    updatedAt: string;
+}
+/**
+ * Complete locale configuration for the plugin
+ */
+export interface LocaleConfig {
+    /** Array of configured locales */
+    locales: LocaleDefinition[];
+    /** Optional default locale code */
+    defaultLocale?: string;
+    /** Timestamp when configuration was last updated */
+    lastUpdated: string;
+    /** Configuration version for migration purposes */
+    version: string;
+}
+/**
+ * Validation result for locale operations
+ */
+export interface LocaleValidationResult {
+    /** Whether the validation passed */
+    isValid: boolean;
+    /** Array of validation error messages */
+    errors: string[];
+    /** Array of validation warning messages */
+    warnings: string[];
+}
+/**
+ * Options for locale selection operations
+ */
+export interface LocaleSelectionOptions {
+    /** Available locales to choose from */
+    availableLocales: LocaleDefinition[];
+    /** Currently selected locale codes */
+    selectedLocales: string[];
+    /** Whether multiple locales can be selected */
+    allowMultiple: boolean;
+    /** Whether selection is required (cannot be empty) */
+    required: boolean;
+}
+/**
+ * Locale code validation regex (ISO 639-1 + ISO 3166-1 format)
+ * Format: two lowercase letters, hyphen, two uppercase letters (e.g., en-US, fr-FR)
+ */
+export declare const LOCALE_CODE_REGEX: RegExp;
+/**
+ * Validates a locale code format
+ * Requirements: 1.2, 1.3
+ *
+ * @param code - The locale code to validate
+ * @returns True if the code matches ISO 639-1 + ISO 3166-1 format
+ *
+ * @example
+ * validateLocaleCode('en-US') // true
+ * validateLocaleCode('fr-FR') // true
+ * validateLocaleCode('en_US') // false
+ * validateLocaleCode('EN-US') // false
+ * validateLocaleCode('e-US') // false
+ */
+export declare function validateLocaleCode(code: string): boolean;
+/**
+ * Validates a locale definition object
+ * Requirements: 1.2, 1.3
+ *
+ * @param locale - The locale definition to validate
+ * @returns Validation result with errors and warnings
+ */
+export declare function validateLocaleDefinition(locale: Partial<LocaleDefinition>): LocaleValidationResult;
+/**
+ * Validates a locale configuration object
+ * Requirements: 1.2, 1.3
+ *
+ * @param config - The locale configuration to validate
+ * @returns Validation result with errors and warnings
+ */
+export declare function validateLocaleConfig(config: Partial<LocaleConfig>): LocaleValidationResult;
+/**
+ * Checks if a locale code exists in a locale configuration
+ *
+ * @param config - The locale configuration to search
+ * @param code - The locale code to find
+ * @returns True if the locale code exists in the configuration
+ */
+export declare function localeExists(config: LocaleConfig, code: string): boolean;
+/**
+ * Gets enabled locales from a configuration
+ *
+ * @param config - The locale configuration
+ * @returns Array of enabled locale definitions
+ */
+export declare function getEnabledLocales(config: LocaleConfig): LocaleDefinition[];
+/**
+ * Finds a locale definition by code
+ *
+ * @param config - The locale configuration to search
+ * @param code - The locale code to find
+ * @returns The locale definition or undefined if not found
+ */
+export declare function findLocaleByCode(config: LocaleConfig, code: string): LocaleDefinition | undefined;

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

@@ -0,0 +1,89 @@
+/**
+ * Easyling Authentication Type Definitions
+ *
+ * This file contains all TypeScript interfaces, types, and enums
+ * for Easyling authentication implementation in the Sanity Translation Plugin.
+ */
+/**
+ * Easyling configuration for connecting to the translation service
+ */
+export interface OAuthConfig {
+    /** Project ID for the Easyling project */
+    projectId: string;
+    /** Long-lived access token provided by Easyling */
+    accessToken: string;
+}
+/**
+ * Result of the authentication process
+ */
+export interface AuthenticationResult {
+    /** Whether authentication was successful */
+    success: boolean;
+    /** Access token if authentication succeeded */
+    accessToken?: string;
+    /** Selected project ID if authentication succeeded */
+    projectId?: string;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Stored authentication data persisted in storage
+ */
+export interface StoredAuthData {
+    /** Access token for API requests */
+    accessToken: string;
+    /** Selected project ID */
+    projectId: string;
+    /** Optional project name for display purposes */
+    projectName?: string;
+    /** Timestamp when data was stored (Unix timestamp in milliseconds) */
+    storedAt: number;
+}
+/**
+ * Authentication state enumeration
+ */
+export type AuthState = 'unauthenticated' | 'authenticated' | 'error';
+/**
+ * Authentication state data with additional context
+ */
+export interface AuthStateData {
+    /** Current authentication state */
+    state: AuthState;
+    /** Selected project ID if authenticated */
+    projectId?: string;
+    /** Project name for display if available */
+    projectName?: string;
+    /** Error message if state is 'error' */
+    error?: string;
+}
+/**
+ * Authentication error types for categorizing failures
+ */
+export declare enum OAuthErrorType {
+    /** Invalid configuration */
+    INVALID_CONFIG = "invalid_config",
+    /** Network error during API request */
+    NETWORK_ERROR = "network_error",
+    /** Authentication failed */
+    AUTH_FAILED = "auth_failed",
+    /** Storage operation failed */
+    STORAGE_ERROR = "storage_error"
+}
+/**
+ * Custom error class for OAuth-related errors
+ */
+export declare class OAuthError extends Error {
+    /** Error type for categorization */
+    readonly type: OAuthErrorType;
+    /** Additional error details */
+    readonly details?: unknown;
+    constructor(type: OAuthErrorType, message: string, details?: unknown);
+    /**
+     * Get a user-friendly error message based on error type
+     */
+    getUserMessage(): string;
+    /**
+     * Check if this error is recoverable (user can retry)
+     */
+    isRecoverable(): boolean;
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Plugin configuration type definitions
+ * Requirements: 1.1, 1.5, 2.3, 3.3, 4.2
+ */
+import { LocaleDefinition } from './locale';
+import { DNTTypeConfig } from './dnt';
+/**
+ * Document creation mode options
+ * Determines whether translated documents are created as drafts or published
+ */
+export type DocumentCreationMode = 'draft' | 'published';
+/**
+ * Content type options for requests/responses
+ * Specifies the serialization format for translation API communication
+ */
+export type ContentType = 'application/json' | 'application/x-protobuf';
+/**
+ * Complete plugin configuration interface
+ * Represents all configurable settings for the Easyling Translation Plugin
+ */
+export interface PluginConfiguration {
+    /** Easyling project ID */
+    projectId?: string;
+    /** Long-lived access token for API authentication */
+    accessToken?: string;
+    /** URL endpoint where translation requests are sent */
+    translationApiEndpoint?: string;
+    /** Content-Type header for translation request payloads */
+    requestContentType?: ContentType;
+    /** Accept header for translation response format negotiation */
+    responseAcceptHeader?: ContentType;
+    /** Default mode for creating translated documents (draft or published) */
+    defaultDocumentCreationMode?: DocumentCreationMode;
+    /** Array of configured locales for translation */
+    locales?: LocaleDefinition[];
+    /** Default source locale code */
+    defaultLocale?: string;
+    /** Document-type-based DNT field configurations */
+    dntFieldConfigurations?: DNTTypeConfig[];
+    /** Configuration schema version for migration purposes */
+    version?: string;
+    /** ISO 8601 timestamp of last configuration update */
+    lastUpdated?: string;
+}

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

@@ -0,0 +1,121 @@
+/**
+ * Enhanced translation request/response type definitions
+ * Requirements: 5.1, 5.2, 5.3
+ */
+/**
+ * Enhanced translation request with locale support
+ */
+export interface EnhancedTranslationRequest {
+    /** Unique identifier for the document */
+    documentId: string;
+    /** Sanity document type */
+    documentType: string;
+    /** HTML content to translate */
+    htmlContent: string;
+    /** Array of target locale codes */
+    targetLocales: string[];
+    /** Optional source locale code */
+    sourceLocale?: string;
+    /** Request metadata */
+    metadata: {
+        /** Document title */
+        title: string;
+        /** Request timestamp */
+        timestamp: string;
+        /** Plugin version */
+        pluginVersion: string;
+        /** Unique request identifier */
+        requestId: string;
+    };
+}
+/**
+ * Enhanced translation response with multi-locale support
+ */
+export interface EnhancedTranslationResponse {
+    /** Whether the overall request was successful */
+    success: boolean;
+    /** Unique request identifier */
+    requestId: string;
+    /** Source locale code */
+    sourceLocale?: string;
+    /** Translations for each requested locale */
+    translations: {
+        [localeCode: string]: {
+            /** Translated content */
+            content: string;
+            /** Translation status */
+            status: 'completed' | 'failed' | 'pending';
+            /** Error message if translation failed */
+            error?: string;
+        };
+    };
+    /** Overall error message if request failed */
+    error?: string;
+}
+/**
+ * Translation progress information
+ */
+export interface TranslationProgress {
+    /** Total number of translations requested */
+    total: number;
+    /** Number of completed translations */
+    completed: number;
+    /** Number of failed translations */
+    failed: number;
+    /** Number of pending translations */
+    pending: number;
+    /** Current translation being processed */
+    current?: {
+        documentId: string;
+        locale: string;
+    };
+}
+/**
+ * Bulk translation request with locale selection
+ */
+export interface BulkTranslationRequest {
+    /** Array of document IDs to translate */
+    documentIds: string[];
+    /** Array of target locale codes */
+    targetLocales: string[];
+    /** Optional source locale code */
+    sourceLocale?: string;
+    /** Request metadata */
+    metadata: {
+        /** Request timestamp */
+        timestamp: string;
+        /** Plugin version */
+        pluginVersion: string;
+        /** Unique request identifier */
+        requestId: string;
+    };
+}
+/**
+ * Bulk translation summary with locale breakdown
+ */
+export interface EnhancedBulkTranslationSummary {
+    /** Total number of documents processed */
+    totalDocuments: number;
+    /** Total number of locale translations requested */
+    totalTranslations: number;
+    /** Number of successful translations */
+    successfulTranslations: number;
+    /** Number of failed translations */
+    failedTranslations: number;
+    /** Breakdown by locale */
+    localeBreakdown: {
+        [localeCode: string]: {
+            /** Number of successful translations for this locale */
+            successful: number;
+            /** Number of failed translations for this locale */
+            failed: number;
+            /** Error messages for failed translations */
+            errors: string[];
+        };
+    };
+    /** Individual translation requests */
+    requests: EnhancedTranslationRequest[];
+    /** Individual translation responses */
+    responses: EnhancedTranslationResponse[];
+}
+export type { TranslationRequestPayload, TranslationResponse, TranslatableField } from '../services/translationService';

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

@@ -0,0 +1,65 @@
+/**
+ * HTML formatting utilities for content processing
+ * Requirements: 3.3, 3.4 - Proper HTML formatting and special character escaping
+ */
+export interface HtmlFormattingOptions {
+    preserveWhitespace?: boolean;
+    escapeSpecialChars?: boolean;
+    minifyOutput?: boolean;
+    addLineBreaks?: boolean;
+}
+export declare class HtmlFormatter {
+    /**
+     * Escape HTML special characters for JSON transmission
+     * Requirement 3.4: Properly escape special characters for JSON transmission
+     */
+    static escapeHtml(text: string): string;
+    /**
+     * Unescape HTML entities back to regular characters
+     */
+    static unescapeHtml(html: string): string;
+    /**
+     * Format HTML content with proper structure and indentation
+     * Requirement 3.2: Preserve text structure including paragraphs, lists, and formatting
+     */
+    static formatHtml(html: string, options?: HtmlFormattingOptions): string;
+    /**
+     * Clean HTML content by removing unwanted tags and attributes
+     */
+    static cleanHtml(html: string, allowedTags?: string[]): string;
+    /**
+     * Wrap content in appropriate HTML structure
+     * Requirement 3.3: Include HTML content in structured format
+     */
+    static wrapContent(content: string, wrapper?: string, className?: string): string;
+    /**
+     * Extract text content from HTML, removing all tags
+     */
+    static stripHtml(html: string): string;
+    /**
+     * Validate HTML structure and check for common issues
+     */
+    static validateHtml(html: string): {
+        isValid: boolean;
+        errors: string[];
+    };
+    /**
+     * Convert line breaks to HTML paragraphs
+     */
+    static lineBreaksToParagraphs(text: string): string;
+    /**
+     * Truncate HTML content while preserving structure
+     */
+    static truncateHtml(html: string, maxLength: number, suffix?: string): string;
+}
+export declare const htmlFormatter: {
+    escapeHtml: typeof HtmlFormatter.escapeHtml;
+    unescapeHtml: typeof HtmlFormatter.unescapeHtml;
+    formatHtml: typeof HtmlFormatter.formatHtml;
+    cleanHtml: typeof HtmlFormatter.cleanHtml;
+    wrapContent: typeof HtmlFormatter.wrapContent;
+    stripHtml: typeof HtmlFormatter.stripHtml;
+    validateHtml: typeof HtmlFormatter.validateHtml;
+    lineBreaksToParagraphs: typeof HtmlFormatter.lineBreaksToParagraphs;
+    truncateHtml: typeof HtmlFormatter.truncateHtml;
+};

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

@@ -0,0 +1,14 @@
+/**
+ * Utility functions for the Sanity Translation Plugin
+ * Requirements: 3.3, 3.4, 4.3
+ */
+export * from './htmlFormatter';
+export * from './logger';
+export * from './validator';
+export * from './oauthLogger';
+export * from './oauthErrorFeedback';
+export { HtmlFormatter } from './htmlFormatter';
+export { Logger, LogLevel, defaultLogger } from './logger';
+export { Validator } from './validator';
+export { OAuthLogger, createOAuthLogger } from './oauthLogger';
+export { OAuthErrorFeedback, createOAuthErrorFeedback } from './oauthErrorFeedback';

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

@@ -0,0 +1,104 @@
+/**
+ * Logging utilities with structured output
+ * Requirements: 4.3 - Clear error messages and structured logging
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3
+}
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    message: string;
+    context?: Record<string, any>;
+    error?: Error;
+}
+export interface LoggerConfig {
+    level: LogLevel;
+    enableConsole: boolean;
+    enableStructuredOutput: boolean;
+    prefix?: string;
+}
+export declare class Logger {
+    private config;
+    constructor(config?: Partial<LoggerConfig>);
+    /**
+     * Log debug message
+     */
+    debug(message: string, context?: Record<string, any>): void;
+    /**
+     * Log info message
+     */
+    info(message: string, context?: Record<string, any>): void;
+    /**
+     * Log warning message
+     */
+    warn(message: string, context?: Record<string, any>): void;
+    /**
+     * Log error message
+     * Requirement 4.3: Display clear error messages
+     */
+    error(message: string, error?: Error, context?: Record<string, any>): void;
+    /**
+     * Log translation request with structured format
+     * Requirements: 1.3, 2.4 - Log request body to console for verification
+     */
+    logTranslationRequest(documentId: string, endpoint: string, payload: any): void;
+    /**
+     * Log bulk translation summary
+     * Requirement 2.5: Display summary of processed documents
+     */
+    logBulkTranslationSummary(summary: {
+        totalDocuments: number;
+        processedDocuments: number;
+        failedDocuments: number;
+        duration?: number;
+    }): void;
+    /**
+     * Log document processing progress
+     */
+    logProgress(current: number, total: number, documentId?: string): void;
+    /**
+     * Log validation errors
+     * Requirement 4.3: Clear error messages for validation failures
+     */
+    logValidationError(type: string, errors: string[], context?: Record<string, any>): void;
+    /**
+     * Log performance metrics
+     */
+    logPerformance(operation: string, duration: number, context?: Record<string, any>): void;
+    /**
+     * Core logging method
+     */
+    private log;
+    /**
+     * Output log entry to console with appropriate formatting
+     */
+    private outputToConsole;
+    /**
+     * Serialize error object for logging
+     */
+    private serializeError;
+    /**
+     * Update logger configuration
+     */
+    updateConfig(config: Partial<LoggerConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): LoggerConfig;
+}
+export declare const defaultLogger: Logger;
+export declare const logger: {
+    debug: (message: string, context?: Record<string, any>) => void;
+    info: (message: string, context?: Record<string, any>) => void;
+    warn: (message: string, context?: Record<string, any>) => void;
+    error: (message: string, error?: Error, context?: Record<string, any>) => void;
+    logTranslationRequest: (documentId: string, endpoint: string, payload: any) => void;
+    logBulkTranslationSummary: (summary: any) => void;
+    logProgress: (current: number, total: number, documentId?: string) => void;
+    logValidationError: (type: string, errors: string[], context?: Record<string, any>) => void;
+    logPerformance: (operation: string, duration: number, context?: Record<string, any>) => void;
+};

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

@@ -0,0 +1,75 @@
+/**
+ * OAuth Error Feedback Utility
+ *
+ * Provides user-friendly error feedback for OAuth authentication errors
+ * using Sanity UI toast notifications and dialogs.
+ *
+ * Requirements: 7.2, 7.3, 7.4
+ */
+import { OAuthError, OAuthErrorType } from '../types/oauth';
+import { DialogService } from '../services/dialogService';
+/**
+ * OAuth Error Feedback Handler
+ *
+ * Provides methods for displaying user-friendly error messages
+ * with appropriate help text and retry options.
+ */
+export declare class OAuthErrorFeedback {
+    private dialogService;
+    /**
+     * Create a new OAuth error feedback handler
+     *
+     * @param dialogService - Dialog service instance
+     */
+    constructor(dialogService: DialogService);
+    /**
+     * Show an error dialog for an OAuth error
+     *
+     * Requirements: 7.2, 7.3, 7.4
+     *
+     * @param error - OAuth error to display
+     * @param onRetry - Optional callback for retry action
+     * @returns Promise that resolves to true if user clicked retry, false otherwise
+     */
+    showError(error: OAuthError, onRetry?: () => void): Promise<boolean>;
+    /**
+     * Show an error dialog for a generic error
+     *
+     * Requirements: 7.2, 7.3
+     *
+     * @param message - Error message to display
+     * @param details - Optional additional details
+     * @param showRetry - Whether to show retry button
+     * @param onRetry - Optional callback for retry action
+     * @returns Promise that resolves to true if user clicked retry, false otherwise
+     */
+    showGenericError(message: string, details?: string, showRetry?: boolean, onRetry?: () => void): Promise<boolean>;
+    /**
+     * Show a success message
+     *
+     * @param message - Success message to display
+     * @param details - Optional additional details
+     */
+    showSuccess(message: string, details?: string): void;
+    /**
+     * Get help text for a specific error type
+     *
+     * @param errorType - OAuth error type
+     * @returns Help text for the error type
+     */
+    getHelpText(errorType: OAuthErrorType): string;
+    /**
+     * Format an error for logging (sanitizes sensitive data)
+     *
+     * @param error - Error to format
+     * @returns Formatted error object safe for logging
+     */
+    formatErrorForLogging(error: OAuthError): Record<string, unknown>;
+}
+/**
+ * Create an OAuth error feedback handler
+ *
+ * @param dialogService - Dialog service instance
+ * @returns OAuth error feedback handler
+ */
+export declare function createOAuthErrorFeedback(dialogService: DialogService): OAuthErrorFeedback;