@useinsider/guido 2.1.0-beta.425dfd0 → 2.1.0-beta.42f5dfa

package/dist/src/extensions/Blocks/Recommendation/services/configService.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Recommendation Config Service
+ *
+ * Service for managing Recommendation block configuration via Stripo's node config API.
+ * This replaces the Pinia store for persistent configuration data.
+ *
+ * Key features:
+ * - Reads/writes config to/from node using `getNodeConfig`/`setNodeConfig`
+ * - Configuration persists with the template HTML
+ * - Each block has independent configuration (no global state)
+ * - Integrates with Stripo's undo/redo via `ModificationDescription`
+ *
+ * Usage pattern similar to legacy `blockConfigurationService`:
+ * @example
+ * // Read config
+ * const config = RecommendationConfigService.getConfig(node);
+ * // Update config
+ * RecommendationConfigService.updateConfig(api, node, { strategy: 'mostPopular' }, 'Changed algorithm');
+ * @see https://plugin.stripo.email/extensions/reference/blocks/Block
+ */
+import type { RecommendationNodeConfig, PartialNodeConfig } from '../types/nodeConfig';
+import type { ImmutableHtmlNode } from '@stripoinc/ui-editor-extensions';
+import { ModificationDescription } from '@stripoinc/ui-editor-extensions';
+/**
+ * Stripo Extension API interface for document modifications
+ * Extracted to allow type-safe usage without importing full Stripo types
+ */
+interface DocumentModifier {
+    modifyHtml: (node: ImmutableHtmlNode) => {
+        setNodeConfig: (config: Record<string, unknown>) => DocumentModifier;
+        setAttribute: (name: string, value: string) => DocumentModifier;
+        setStyle: (prop: string, value: string) => DocumentModifier;
+        setInnerHtml: (html: string) => DocumentModifier;
+    };
+    apply: (desc: ModificationDescription) => void;
+}
+interface DocumentModifierApi {
+    getDocumentModifier: () => DocumentModifier;
+}
+/**
+ * Service for managing Recommendation block configuration
+ *
+ * All methods are static for easy usage without instantiation.
+ * The service follows the same patterns as the legacy `blockConfigurationService`.
+ */
+export declare class RecommendationConfigService {
+    /**
+     * Get configuration from a node, with defaults for missing values
+     *
+     * This is the primary way to read configuration from a block.
+     * Always returns a complete config object with defaults merged in.
+     * @example
+     * const config = RecommendationConfigService.getConfig(this.currentNode);
+     * console.log(config.strategy); // 'mostPopular'
+     * @param node - The immutable HTML node to read config from
+     * @returns Complete configuration with defaults for missing values
+     */
+    static getConfig(node: ImmutableHtmlNode | null | undefined): RecommendationNodeConfig;
+    /**
+     * Check if a node has valid configuration stored
+     *
+     * Used for migration detection - returns false for legacy templates
+     * that need their configuration migrated.
+     * @param node - The immutable HTML node to check
+     * @returns True if node has valid config with version number
+     */
+    static hasConfig(node: ImmutableHtmlNode | null | undefined): boolean;
+    /**
+     * Get the configuration version from a node
+     * @param node - The immutable HTML node to check
+     * @returns Config version number, or 0 if no config exists
+     */
+    static getConfigVersion(node: ImmutableHtmlNode | null | undefined): number;
+    /**
+     * Update specific configuration values
+     *
+     * Merges the updates with existing config and persists to node.
+     * This is the primary way to update configuration from controls.
+     * @example
+     * RecommendationConfigService.updateConfig(
+     *   this.api,
+     *   this.currentNode,
+     *   { strategy: 'complementaryItems' },
+     *   'Changed recommendation algorithm'
+     * );
+     * @param api - Stripo extension API with document modifier
+     * @param node - The immutable HTML node to update
+     * @param updates - Partial config with values to update
+     * @param description - Human-readable description for undo/redo
+     * @returns The new complete configuration
+     */
+    static updateConfig(api: DocumentModifierApi, node: ImmutableHtmlNode, updates: PartialNodeConfig, description: string): RecommendationNodeConfig;
+    /**
+     * Initialize configuration for a new block
+     *
+     * Called when a block is first created (dropped into template).
+     * Can optionally merge in partial config from migration.
+     * @example
+     * // In Block.onCreated lifecycle
+     * RecommendationConfigService.initializeConfig(this.api, node);
+     * @param api - Stripo extension API with document modifier
+     * @param node - The immutable HTML node to initialize
+     * @param partialConfig - Optional partial config to merge with defaults
+     * @returns The initialized configuration
+     */
+    static initializeConfig(api: DocumentModifierApi, node: ImmutableHtmlNode, partialConfig?: PartialNodeConfig): RecommendationNodeConfig;
+    /**
+     * Save complete configuration to a node
+     *
+     * Low-level method - prefer `updateConfig` or `initializeConfig` in most cases.
+     * @param api - Stripo extension API with document modifier
+     * @param node - The immutable HTML node to save to
+     * @param config - Complete configuration to save
+     * @param description - Human-readable description for undo/redo
+     */
+    static saveConfig(api: DocumentModifierApi, node: ImmutableHtmlNode, config: RecommendationNodeConfig, description: string): void;
+    /**
+     * Migrate configuration from legacy data-attributes
+     *
+     * Reads existing data-attributes and creates a proper node config.
+     * Used when loading templates created before node config was implemented.
+     * @param api - Stripo extension API with document modifier
+     * @param node - The block node to migrate
+     * @returns The migrated configuration
+     */
+    static migrateFromDataAttributes(api: DocumentModifierApi, node: ImmutableHtmlNode): RecommendationNodeConfig;
+    /**
+     * Check if configuration needs migration
+     * @param node - The block node to check
+     * @returns True if migration is needed
+     */
+    static needsMigration(node: ImmutableHtmlNode | null | undefined): boolean;
+    /**
+     * Clone default config to avoid mutations
+     */
+    private static cloneDefaults;
+    /**
+     * Merge partial config with defaults
+     *
+     * Deep merges nested objects like currency, omnibus settings.
+     */
+    private static mergeWithDefaults;
+    /**
+     * Deep merge for nested objects
+     *
+     * Recursively merges source into target, preserving existing values
+     * that aren't explicitly overwritten.
+     */
+    private static deepMerge;
+}
+export {};

package/dist/src/extensions/Blocks/Recommendation/services/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Recommendation Extension Services
+ *
+ * This module re-exports all services for the Recommendation extension.
+ */
+export { RecommendationConfigService } from './configService';