@easyling/sanity-connector 1.4.0 → 2.0.0

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

@@ -1,195 +0,0 @@
-/**
- * OAuth Service Manager
- * Requirements: 6.1, 10.1, 9.2
- *
- * Manages singleton instances of OAuth services and handles initialization.
- * Provides centralized access to OAuth services throughout the plugin.
- */
-import { SanityClient } from 'sanity';
-import { OAuthService } from './oauthService';
-import { TokenStorage } from './tokenStorage';
-import { AuthStateManager } from './authStateManager';
-import { TranslationService } from './translationService';
-import { OAuthConfigStorage } from './oauthConfigStorage';
-/**
- * OAuth Service Manager
- *
- * Singleton manager for OAuth services. Ensures all services are properly
- * initialized and provides centralized access throughout the plugin.
- */
-export declare class OAuthServiceManager {
-    private static instance;
-    private oauthService;
-    private tokenStorage;
-    private authStateManager;
-    private translationService;
-    private oauthConfigStorage;
-    private unifiedConfigStorage;
-    private client;
-    private initialized;
-    /**
-     * Private constructor to enforce singleton pattern
-     * Requirements: 6.1, 10.1
-     */
-    private constructor();
-    /**
-     * Get or create the singleton instance
-     * Requirements: 6.1, 10.1
-     *
-     * @param client - Sanity client instance
-     * @returns Singleton instance of OAuthServiceManager
-     */
-    static getInstance(client: SanityClient): OAuthServiceManager;
-    /**
-     * Reset the singleton instance (useful for testing)
-     */
-    static resetInstance(): void;
-    /**
-     * Initialize OAuth services
-     * Requirements: 6.1, 10.1
-     *
-     * Loads OAuth configuration, initializes OAuth service if configured,
-     * initializes authentication state from storage, and sets up translation
-     * service with authentication if available.
-     *
-     * @returns Promise that resolves when initialization is complete
-     */
-    initialize(): Promise<void>;
-    /**
-     * Set up listener for configuration changes
-     *
-     * Monitors the unified configuration document for changes and reloads
-     * the configuration automatically.
-     */
-    private setupConfigListener;
-    /**
-     * Load OAuth configuration from storage
-     * Requirements: 9.1, 9.4
-     *
-     * @returns OAuth configuration or null if not configured
-     */
-    private loadOAuthConfig;
-    /**
-     * Set up translation service with authentication if available
-     *
-     * Checks for valid stored authentication and configures the translation
-     * service to use it.
-     *
-     * Supports dual mode operation:
-     * - If OAuth is configured and authenticated, sets up OAuth authentication
-     * - If OAuth is not configured, translation service works in legacy mode
-     *
-     * IMPORTANT: This method also syncs configuration from Sanity to localStorage
-     * if configuration exists in Sanity but not in localStorage (migration support).
-     */
-    private setupTranslationServiceAuth;
-    /**
-     * Set up translation service endpoint and settings from configuration
-     *
-     * Loads translation endpoint, content type, and other settings from
-     * unified configuration with fallback to defaults.
-     */
-    private setupTranslationServiceEndpoint;
-    /**
-     * Get OAuth service instance
-     * Requirements: 1.1, 1.2, 1.3
-     *
-     * @returns OAuth service instance or null if not configured
-     */
-    getOAuthService(): OAuthService | null;
-    /**
-     * Get token storage instance
-     * Requirements: 3.3, 3.4, 3.5
-     *
-     * @returns Token storage instance
-     */
-    getTokenStorage(): TokenStorage;
-    /**
-     * Get authentication state manager instance
-     * Requirements: 6.1, 6.2, 6.3
-     *
-     * @returns Authentication state manager instance
-     */
-    getAuthStateManager(): AuthStateManager;
-    /**
-     * Get translation service instance
-     * Requirements: 4.1, 4.2, 4.3
-     *
-     * @returns Translation service instance
-     */
-    getTranslationService(): TranslationService;
-    /**
-     * Get OAuth configuration storage instance
-     * Requirements: 9.1, 9.4
-     *
-     * @returns OAuth configuration storage instance
-     */
-    getOAuthConfigStorage(): OAuthConfigStorage;
-    /**
-     * Check if OAuth is configured
-     * Requirements: 10.1, 10.3
-     *
-     * @returns True if OAuth service is initialized
-     */
-    isOAuthConfigured(): boolean;
-    /**
-     * Detect which authentication method should be used
-     * Requirements: 10.1, 10.3, 10.4
-     *
-     * Determines whether to use OAuth or legacy endpoint-based authentication
-     * based on the presence of OAuth configuration.
-     *
-     * @returns 'oauth' if OAuth is configured, 'legacy' otherwise
-     */
-    getAuthenticationMode(): 'oauth' | 'legacy';
-    /**
-     * Check if user is authenticated with OAuth
-     * Requirements: 10.1, 10.3
-     *
-     * @returns True if OAuth is configured and user has valid authentication
-     */
-    isOAuthAuthenticated(): Promise<boolean>;
-    /**
-     * Get authentication status information
-     * Requirements: 10.1, 10.3, 10.4
-     *
-     * Provides detailed information about the current authentication mode
-     * and status for display to users.
-     *
-     * @returns Object with authentication mode and status details
-     */
-    getAuthenticationStatus(): Promise<{
-        mode: 'oauth' | 'legacy';
-        isOAuthConfigured: boolean;
-        isAuthenticated: boolean;
-        requiresAuthentication: boolean;
-    }>;
-    /**
-     * Check if services are initialized
-     * Requirements: 6.1
-     *
-     * @returns True if initialization is complete
-     */
-    isInitialized(): boolean;
-    /**
-     * Save authentication configuration and data
-     *
-     * Stores the access token and project ID, and configures the translation service.
-     *
-     * @param accessToken - The Easyling access token
-     * @param projectId - The Easyling project ID
-     */
-    saveAuth(accessToken: string, projectId: string): Promise<void>;
-    /**
-     * Logout and clear authentication
-     */
-    logout(): Promise<void>;
-    /**
-     * Refresh configuration from Sanity
-     *
-     * Reloads the translation service endpoint and other settings from Sanity.
-     * This should be called when the configuration has been updated in Sanity
-     * to ensure the plugin is using the latest settings.
-     */
-    refreshConfiguration(): Promise<void>;
-}

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

@@ -1,53 +0,0 @@
-/**
- * Token Storage Service
- *
- * Manages secure storage and retrieval of OAuth authentication tokens
- * and related data using Sanity Studio's localStorage wrapper.
- *
- * Requirements: 3.3, 3.4, 3.5, 6.1, 6.4, 8.4
- */
-import { StoredAuthData } from '../types/oauth';
-/**
- * Token Storage Service
- *
- * Provides methods for persisting, retrieving, and managing OAuth authentication data.
- * Uses Sanity Studio's localStorage for persistence with JSON serialization.
- */
-export declare class TokenStorage {
-    /**
-     * Store authentication data securely
-     *
-     * @param data - Authentication data to store
-     * @throws {OAuthError} If storage operation fails
-     */
-    storeAuthData(data: StoredAuthData): Promise<void>;
-    /**
-     * Retrieve stored authentication data
-     *
-     * @returns Stored authentication data or null if not found
-     * @throws {OAuthError} If storage read fails or data is corrupted
-     */
-    getAuthData(): Promise<StoredAuthData | null>;
-    /**
-     * Clear all stored authentication data
-     *
-     * Requirements: 6.4
-     *
-     * @throws {OAuthError} If storage clear operation fails
-     */
-    clearAuthData(): Promise<void>;
-    /**
-     * Check if the stored token is expired
-     *
-     * For long-lived tokens, this always returns false if a token exists.
-     *
-     * @returns True if token is not found, false if token exists
-     */
-    isTokenExpired(): Promise<boolean>;
-    /**
-     * Get a valid access token if available
-     *
-     * @returns Valid access token or null if not found
-     */
-    getValidAccessToken(): Promise<string | null>;
-}

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

@@ -1,385 +0,0 @@
-import { ExtendedDocumentContent } from './contentExtractor';
-/**
- * Field object structure supporting translation-invariant fields
- */
-export interface TranslatableField {
-    /** The actual field value (serialized as string for the protobuf) */
-    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;
-    /**
-     * GROQ-style path for reconstructing the document structure
-     * Example: *[_type == "blogPost" && _id == $documentId][0].article.footnotes[_key == "abc123"].footnote
-     */
-    path?: 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[];
-        /** Whether the title was found at the document's top level (false if extracted from nested fields) */
-        titleFoundAtTopLevel?: boolean;
-    };
-}
-/**
- * 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;
-    /**
-     * Whether the title was found at the document's top level
-     * When false, the translated title should not be written as a top-level field
-     */
-    titleFoundAtTopLevel?: boolean;
-}
-/**
- * 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;
-}