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

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

@@ -0,0 +1,159 @@
+/**
+ * Locale configuration management service
+ * Requirements: 1.1, 1.4, 1.5, 5.4, 5.5, 5.6
+ *
+ * Provides CRUD operations for locale configuration management with validation,
+ * persistence, and error handling capabilities.
+ */
+import { LocaleConfig, LocaleDefinition, LocaleValidationResult } from '../types/locale';
+/**
+ * Storage interface for locale configuration persistence
+ * This allows for different storage implementations (localStorage, Sanity config, etc.)
+ */
+export interface LocaleStorageAdapter {
+    load(): Promise<LocaleConfig | null>;
+    save(config: LocaleConfig): Promise<void>;
+}
+/**
+ * Error types for locale service operations
+ */
+export declare class LocaleServiceError extends Error {
+    code: string;
+    details?: unknown | undefined;
+    constructor(message: string, code: string, details?: unknown | undefined);
+}
+/**
+ * Service for managing locale configuration with CRUD operations
+ * Requirements: 1.1, 1.4, 1.5, 5.4, 5.5, 5.6
+ */
+export declare class LocaleService {
+    private config;
+    private storageAdapter;
+    /**
+     * Creates a new LocaleService instance
+     *
+     * @param storageAdapter - Optional storage adapter for persistence
+     * @param initialConfig - Optional initial configuration (defaults to empty config)
+     */
+    constructor(storageAdapter?: LocaleStorageAdapter | null, initialConfig?: LocaleConfig);
+    /**
+     * Loads locale configuration from storage
+     * Requirements: 1.4, 5.4
+     *
+     * @returns Promise resolving to the loaded configuration
+     * @throws LocaleServiceError if loading fails
+     */
+    loadConfig(): Promise<LocaleConfig>;
+    /**
+     * Saves locale configuration to storage
+     * Requirements: 1.5, 5.5
+     *
+     * @param config - Optional configuration to save (defaults to current config)
+     * @returns Promise resolving when save is complete
+     * @throws LocaleServiceError if saving fails
+     */
+    saveConfig(config?: LocaleConfig): Promise<void>;
+    /**
+     * Gets the current locale configuration
+     *
+     * @returns Current locale configuration
+     */
+    getConfig(): LocaleConfig;
+    /**
+     * Gets all locales from the configuration
+     *
+     * @returns Array of all locale definitions
+     */
+    getAllLocales(): LocaleDefinition[];
+    /**
+     * Gets all enabled locales from the configuration
+     *
+     * @returns Array of enabled locale definitions
+     */
+    getEnabledLocales(): LocaleDefinition[];
+    /**
+     * Gets a locale by its code
+     *
+     * @param code - Locale code to find
+     * @returns Locale definition or undefined if not found
+     */
+    getLocaleByCode(code: string): LocaleDefinition | undefined;
+    /**
+     * Checks if a locale code exists in the configuration
+     *
+     * @param code - Locale code to check
+     * @returns True if the locale exists
+     */
+    hasLocale(code: string): boolean;
+    /**
+     * Adds a new locale to the configuration
+     * Requirements: 1.1, 1.2, 1.3
+     *
+     * @param locale - Locale definition to add
+     * @returns Promise resolving to validation result
+     * @throws LocaleServiceError if locale is invalid or already exists
+     */
+    addLocale(locale: Omit<LocaleDefinition, 'createdAt' | 'updatedAt'>): Promise<LocaleValidationResult>;
+    /**
+     * Updates an existing locale in the configuration
+     * Requirements: 1.6, 1.7
+     *
+     * @param code - Code of the locale to update
+     * @param updates - Partial locale definition with updates
+     * @returns Promise resolving to validation result
+     * @throws LocaleServiceError if locale not found or updates are invalid
+     */
+    updateLocale(code: string, updates: Partial<Omit<LocaleDefinition, 'code' | 'createdAt' | 'updatedAt'>>): Promise<LocaleValidationResult>;
+    /**
+     * Removes a locale from the configuration
+     * Requirements: 1.6
+     *
+     * @param code - Code of the locale to remove
+     * @returns Promise resolving when removal is complete
+     * @throws LocaleServiceError if locale not found
+     */
+    removeLocale(code: string): Promise<void>;
+    /**
+     * Sets the default locale
+     *
+     * @param code - Code of the locale to set as default
+     * @returns Promise resolving when update is complete
+     * @throws LocaleServiceError if locale not found
+     */
+    setDefaultLocale(code: string): Promise<void>;
+    /**
+     * Clears the default locale
+     *
+     * @returns Promise resolving when update is complete
+     */
+    clearDefaultLocale(): Promise<void>;
+    /**
+     * Validates the current configuration
+     * Requirements: 5.6
+     *
+     * @returns Validation result
+     */
+    validateCurrentConfig(): LocaleValidationResult;
+    /**
+     * Resets configuration to default state
+     * Requirements: 5.6
+     *
+     * @returns Promise resolving when reset is complete
+     */
+    resetToDefault(): Promise<void>;
+    /**
+     * Imports a locale configuration
+     * Useful for bulk import or migration scenarios
+     *
+     * @param config - Configuration to import
+     * @returns Promise resolving to validation result
+     * @throws LocaleServiceError if configuration is invalid
+     */
+    importConfig(config: LocaleConfig): Promise<LocaleValidationResult>;
+    /**
+     * Exports the current locale configuration
+     *
+     * @returns Current configuration as a plain object
+     */
+    exportConfig(): LocaleConfig;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Locale Storage Adapter for Sanity Configuration
+ * Requirements: 5.1, 5.2, 5.3, 5.7
+ *
+ * Now delegates to UnifiedConfigStorage for centralized configuration management.
+ * Locale settings are stored in the EL_PluginConfiguration document alongside
+ * OAuth and DNT configurations.
+ */
+import { SanityClient } from 'sanity';
+import { LocaleConfig } from '../types/locale';
+import { LocaleStorageAdapter } from './localeService';
+/**
+ * Locale configuration storage adapter
+ * Now uses UnifiedConfigStorage for centralized management
+ * Requirements: 5.1, 5.2, 5.3, 5.7
+ */
+export declare class SanityLocaleStorageAdapter implements LocaleStorageAdapter {
+    private unifiedStorage;
+    private client;
+    constructor(client: SanityClient);
+    /**
+     * Load locale configuration from unified storage
+     * Requirements: 5.2, 5.4
+     */
+    load(): Promise<LocaleConfig | null>;
+    /**
+     * Save locale configuration to unified storage
+     * Requirements: 5.3, 5.5
+     */
+    save(config: LocaleConfig): Promise<void>;
+    /**
+     * Load from legacy locale-specific document
+     * @private
+     */
+    private loadLegacy;
+    /**
+     * Delete legacy locale document after migration
+     * @private
+     */
+    private deleteLegacy;
+}

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

@@ -0,0 +1,45 @@
+/**
+ * OAuth Configuration Storage Adapter
+ * Requirements: 9.1, 9.4
+ *
+ * Now delegates to UnifiedConfigStorage for centralized configuration management.
+ * OAuth settings are stored in the EL_PluginConfiguration document alongside
+ * locale and DNT configurations.
+ */
+import { SanityClient } from 'sanity';
+import { OAuthConfig } from '../types/oauth';
+/**
+ * OAuth configuration storage adapter
+ * Now uses UnifiedConfigStorage for centralized management
+ * Requirements: 9.1, 9.4
+ */
+export declare class OAuthConfigStorage {
+    private unifiedStorage;
+    private client;
+    constructor(client: SanityClient);
+    /**
+     * Load OAuth configuration from unified storage
+     * Requirements: 9.1, 9.4
+     */
+    load(): Promise<OAuthConfig | null>;
+    /**
+     * Save OAuth configuration to unified storage
+     * Requirements: 9.1, 9.4
+     */
+    save(config: OAuthConfig): Promise<void>;
+    /**
+     * Delete OAuth configuration
+     * Only clears OAuth fields, preserves other configuration
+     */
+    delete(): Promise<void>;
+    /**
+     * Load from legacy OAuth-specific document
+     * @private
+     */
+    private loadLegacy;
+    /**
+     * Delete legacy OAuth document after migration
+     * @private
+     */
+    private deleteLegacy;
+}

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

@@ -0,0 +1,47 @@
+/**
+ * Easyling Authentication Service
+ *
+ * Manages Easyling authentication configuration for the Sanity Translation Plugin.
+ * Handles validation and storage of access tokens and project IDs.
+ */
+import { OAuthConfig } from '../types/oauth';
+/**
+ * Easyling Authentication Service
+ *
+ * Provides methods for managing Easyling authentication configuration.
+ */
+export declare class OAuthService {
+    private config;
+    /**
+     * Create a new Easyling Authentication Service instance
+     *
+     * @param config - Easyling configuration (access token and project ID)
+     * @throws {OAuthError} If configuration is invalid
+     */
+    constructor(config: OAuthConfig);
+    /**
+     * Validate configuration
+     *
+     * @param config - Configuration to validate
+     * @throws {OAuthError} If configuration is invalid
+     */
+    private validateConfig;
+    /**
+     * Get the access token
+     *
+     * @returns The configured access token
+     */
+    getAccessToken(): string;
+    /**
+     * Get the project ID
+     *
+     * @returns The configured project ID
+     */
+    getProjectId(): string;
+    /**
+     * Get the complete configuration
+     *
+     * @returns The complete OAuth configuration
+     */
+    getConfig(): OAuthConfig;
+}

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

@@ -0,0 +1,188 @@
+/**
+ * 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>;
+    /**
+     * 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

@@ -0,0 +1,53 @@
+/**
+ * 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>;
+}