@virtualdisplay.io/client 3.7.0 → 4.0.0-alpha.2

package/dist/index.d.ts

@@ -1,821 +1 @@
-import { Logger } from '@virtualdisplay-io/logger';
-
-/**
- * Pure domain aggregate for managing attribute values
- * No side effects - only business logic and state management
- */
-declare class Attribute {
-    private readonly attributeName;
-    private readonly values;
-    constructor(name: string);
-    addValue(attributeValue: AttributeValue): void;
-    getDefaultMutations(): Mutation[];
-    getCurrentValue(): AttributeValue | undefined;
-    getValue(valueName: string): AttributeValue | undefined;
-    getAllValues(): AttributeValue[];
-    hasValue(valueName: string): boolean;
-    get name(): string;
-    get currentSelection(): string | undefined;
-    clear(): void;
-}
-
-/**
- * Configuration for a single attribute
- */
-export declare interface AttributeConfig {
-    readonly name: string;
-    readonly values: DynamicValue<AttributeValueConfig[]>;
-}
-
-/**
- * Public API for selecting attribute values
- * Provides fluent interface for client usage
- */
-export declare class AttributeSelector {
-    private readonly attributeService;
-    private readonly attributeName;
-    constructor(attributeService: AttributeService, attributeName: string);
-    /**
-     * Select a value for this attribute
-     * Fire-and-forget: returns immediately, 3D updates asynchronously
-     * @returns this AttributeSelector for method chaining
-     * @throws {VirtualdisplayError} When value not found for attribute
-     */
-    select(value: string): AttributeSelector;
-    get name(): string;
-    get currentValue(): string | undefined;
-    get availableValues(): string[];
-    /**
-     * Register a callback to be called when any value's selection state changes
-     * This registers the callback on all AttributeValue objects for this attribute
-     * @param callback Function to call when selection state changes
-     * @returns this AttributeSelector for method chaining
-     */
-    onChange(callback: () => void): AttributeSelector;
-    /**
-     * Get all AttributeValue objects for direct property access
-     * @returns Array of AttributeValue objects
-     */
-    getValues(): AttributeValue[];
-    /**
-     * Get a specific AttributeValue object by value name
-     * @param value The value name to find
-     * @returns AttributeValue object or undefined if not found
-     */
-    getValue(value: string): AttributeValue | undefined;
-    private getAttribute;
-}
-
-/**
- * Application service for managing attributes
- * Handles business logic and coordinates with other domains via events
- */
-declare class AttributeService {
-    private attributes;
-    private readonly eventBus;
-    private isInitialized;
-    private mappingConfig;
-    private readonly selections;
-    private readonly currentState;
-    constructor(eventBus: EventBus);
-    /**
-     * Load mapping configuration and apply defaults
-     * @throws {VirtualdisplayError} When mapping configuration is invalid
-     */
-    loadMapping(config: MappingConfiguration): void;
-    selectAttributeValue(attributeName: string, value: string): void;
-    getAttribute(name: string): Attribute | undefined;
-    getAllAttributes(): Attribute[];
-    get initialized(): boolean;
-    private syncStateWithAttributes;
-    clear(): void;
-    /**
-     * Create context for dynamic evaluation
-     */
-    private createContext;
-    /**
-     * Evaluate a property that might be static or dynamic
-     */
-    private evaluateProperty;
-    /**
-     * Evaluate the entire mapping with current context
-     */
-    private evaluateMapping;
-    /**
-     * Create a single attribute from configuration
-     */
-    private createAttributeFromConfig;
-    /**
-     * Initialize selections from default values
-     */
-    private initializeSelections;
-    /**
-     * Check if the mapping configuration contains dynamic elements
-     */
-    private hasDynamicMapping;
-    /**
-     * Update current state map with visible nodes per attribute
-     */
-    private updateCurrentState;
-    private getVisibleNodesForAttribute;
-    /**
-     * Get initial mutations for default selections
-     */
-    private getInitialMutations;
-    /**
-     * Calculate mutations by comparing old and new state
-     */
-    private calculateMutations;
-    /**
-     * Check if a node is visible in the given state
-     */
-    private isNodeVisible;
-}
-
-/**
- * Pure domain entity representing a single attribute value
- * No side effects - only business logic and data
- */
-declare class AttributeValue {
-    private readonly attributeValue;
-    private readonly nodeIds;
-    private selected;
-    onChange?: () => void;
-    constructor(value: string, nodeIds: string[], isSelected?: boolean);
-    getMutations(): Mutation[];
-    setSelected(selected: boolean): void;
-    get value(): string;
-    get nodeList(): string[];
-    hasNode(nodeId: string): boolean;
-    get isSelected(): boolean;
-    setOnChange(callback: () => void): void;
-}
-
-/**
- * Configuration for a single attribute value
- * All properties can be static or dynamic
- */
-export declare interface AttributeValueConfig {
-    readonly value: DynamicValue<string>;
-    readonly nodeIds: DynamicValue<string[]>;
-    readonly isSelected?: DynamicValue<boolean>;
-}
-
-/**
- * Camera control API for positioning and zoom
- * Uses chaining pattern for building commands
- */
-export declare class Camera {
-    private readonly eventBus;
-    private commands;
-    constructor(eventBus: EventBus);
-    /**
-     * Rotate camera horizontally
-     * @param degrees - Absolute rotation in degrees (0 = front view)
-     */
-    rotate(degrees: number): this;
-    /**
-     * Tilt camera vertically
-     * @param degrees - Absolute tilt in degrees (0 = top view, 90 = horizontal)
-     */
-    tilt(degrees: number): this;
-    /**
-     * Zoom camera
-     * @param percentage - Zoom percentage (100 = normal, >100 = zoom in, <100 = zoom out)
-     */
-    zoom(percentage: number): this;
-    /**
-     * Execute accumulated camera commands
-     */
-    set(): void;
-    /**
-     * Reset camera to initial position
-     * This is not chainable and executes immediately
-     */
-    reset(): void;
-}
-
-/**
- * Camera command
- */
-export declare interface CameraCommand {
-    readonly action: 'rotate' | 'tilt' | 'zoom' | 'reset';
-    readonly value?: number;
-}
-
-/**
- * Camera configuration options
- */
-export declare interface CameraConfig {
-    readonly initialRotate?: number;
-    readonly initialTilt?: number;
-    readonly initialZoom?: number;
-    readonly minZoom?: number;
-    readonly maxZoom?: number;
-    readonly minTilt?: number;
-    readonly maxTilt?: number;
-}
-
-/**
- * Camera message sent to server
- */
-export declare interface CameraMessage {
-    readonly type: typeof MESSAGE_TYPES.CAMERA;
-    readonly commands: CameraCommand[];
-}
-
-/**
- * Configuration options for VirtualdisplayClient
- */
-export declare interface ClientOptions {
-    readonly parent: string | HTMLElement;
-    readonly model: string;
-    readonly license: string;
-    readonly debug?: boolean;
-    readonly language?: string;
-    readonly arEnabled?: boolean;
-    readonly fullscreenEnabled?: boolean;
-    readonly loadingIndicatorEnabled?: boolean;
-    readonly ui?: UIConfig;
-    readonly camera?: CameraConfig;
-}
-
-/**
- * Configuration message sent to server
- */
-export declare interface ConfigMessage {
-    readonly type: typeof MESSAGE_TYPES.CONFIG;
-    readonly config: ViewerConfig;
-}
-
-declare interface CreateNodeParams {
-    id: string;
-    name: string;
-    type: NodeType;
-    visible: boolean;
-}
-
-/**
- * Central Event Registry
- */
-export declare interface DomainEvents extends Record<string, unknown> {
-    [EVENT_NAMES.IFRAME_READY]: VoidEvent;
-    [EVENT_NAMES.MUTATION_MESSAGE]: MessageEvent_2<MutationMessage>;
-    [EVENT_NAMES.CONFIG_MESSAGE]: MessageEvent_2<ConfigMessage>;
-    [EVENT_NAMES.CAMERA_MESSAGE]: MessageEvent_2<CameraMessage>;
-    [EVENT_NAMES.MESSAGE_RECEIVED]: MessageEvent_2;
-    [EVENT_NAMES.STATE_CHANGED]: StateChangedEvent;
-    [EVENT_NAMES.INITIAL_STATE_RECEIVED]: VoidEvent;
-}
-
-/**
- * A value that can be static or dynamically computed
- */
-declare type DynamicValue<T> = T | ((context: MappingContext) => T);
-
-export declare function enableDebugMode(): void;
-
-/**
- * Error codes for Virtualdisplay client errors
- */
-export declare const ERROR_CODES: {
-    readonly NO_MAPPING: "NO_MAPPING";
-    readonly ATTRIBUTE_NOT_FOUND: "ATTRIBUTE_NOT_FOUND";
-    readonly VALUE_NOT_FOUND: "VALUE_NOT_FOUND";
-    readonly INVALID_MAPPING: "INVALID_MAPPING";
-    readonly PARENT_NOT_FOUND: "PARENT_NOT_FOUND";
-    readonly INVALID_MUTATIONS: "INVALID_MUTATIONS";
-    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
-};
-
-export declare type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
-
-/**
- * Event name constants for type-safe event communication
- */
-export declare const EVENT_NAMES: {
-    readonly IFRAME_READY: "iframe:ready";
-    readonly MUTATION_MESSAGE: "mutation:message";
-    readonly CONFIG_MESSAGE: "config:message";
-    readonly CAMERA_MESSAGE: "camera:message";
-    readonly MESSAGE_RECEIVED: "message:received";
-    readonly STATE_CHANGED: "state:changed";
-    readonly INITIAL_STATE_RECEIVED: "state:initial-received";
-    readonly SNAPSHOT_MESSAGE: "snapshot:take";
-};
-
-/**
- * EventBus for domain coordination
- * Provides loose coupling between domains via events
- */
-declare class EventBus {
-    private readonly listeners;
-    on<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
-    emit<K extends keyof DomainEvents>(event: K, payload: DomainEvents[K]): void;
-    /**
-     * Register a listener that will be called only once
-     * The listener is automatically removed after the first call
-     */
-    once<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
-    /**
-     * Remove a specific listener for an event
-     */
-    off<K extends keyof DomainEvents>(event: K, listener: EventListener_2<DomainEvents[K]>): void;
-}
-
-declare type EventListener_2<T> = (payload: T) => void;
-
-export declare function isDebugMode(): boolean;
-
-export declare const logger: Logger;
-
-/**
- * Complete mapping configuration
- * Defines how product attributes map to 3D nodes
- */
-export declare interface MappingConfiguration {
-    readonly attributes: AttributeConfig[];
-}
-
-/**
- * Context provided to dynamic value functions
- */
-declare interface MappingContext {
-    getValue: (attributeName: string) => string | undefined;
-    getAllValues: () => Map<string, string>;
-}
-
-export declare const mappingSchema: {
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "title": "Virtualdisplay mapping configuration",
-    "description": "Schema for attribute-based 3D model configuration",
-    "type": "object",
-    "required": ["attributes"],
-    "definitions": {
-        "attribute": {
-            "type": "object",
-            "description": "A configurable attribute with multiple possible values",
-            "required": ["name", "values"],
-            "properties": {
-                "name": {
-                    "type": "string",
-                    "description": "Unique attribute name (e.g., 'Color', 'Size')",
-                    "minLength": 1,
-                    "pattern": "^\\S.*\\S$|^\\S$"
-                },
-                "values": {
-                    "type": "array",
-                    "description": "Possible values for this attribute",
-                    "minItems": 1,
-                    "items": {
-                        "$ref": "#/definitions/attributeValue"
-                    }
-                }
-            }
-        },
-        "attributeValue": {
-            "type": "object",
-            "description": "A single value option for an attribute",
-            "required": ["value", "nodeIds"],
-            "properties": {
-                "value": {
-                    "type": "string",
-                    "description": "Display value (e.g., 'Red', 'Large')",
-                    "minLength": 1,
-                    "pattern": "^\\S.*\\S$|^\\S$"
-                },
-                "nodeIds": {
-                    "type": "array",
-                    "description": "3D model node IDs controlled by this value",
-                    "items": {
-                        "type": "string",
-                        "description": "Node ID in the 3D model"
-                    }
-                },
-                "isSelected": {
-                    "type": "boolean",
-                    "description": "Whether this value is selected by default",
-                    "default": false
-                }
-            }
-        }
-    },
-    "properties": {
-        "attributes": {
-            "type": "array",
-            "description": "List of all configurable attributes",
-            "minItems": 1,
-            "items": {
-                "$ref": "#/definitions/attribute"
-            }
-        }
-    }
-};
-
-/**
- * Validator for mapping configuration using AJV
- */
-export declare class MappingValidator {
-    private static readonly ajv;
-    private static readonly validateFn;
-    /**
-     * Validate complete mapping configuration
-     * @throws {VirtualdisplayError} When mapping configuration is invalid
-     */
-    static validate(config: MappingConfiguration): void;
-    /**
-     * Check if configuration contains dynamic values (functions)
-     */
-    static containsDynamicValues(config: MappingConfiguration): boolean;
-    /**
-     * Basic structure validation for dynamic mappings
-     */
-    private static validateBasicStructure;
-}
-
-/**
- * Union of all possible messages
- */
-export declare type Message = MutationMessage | StateMessage | ConfigMessage | CameraMessage | SnapshotRequestMessage | SnapshotDevelopedMessage;
-
-/**
- * Types of messages exchanged between client and server
- * Using lowercase format to match server
- */
-export declare const MESSAGE_TYPES: {
-    readonly MUTATION: "mutation";
-    readonly STATE: "state";
-    readonly CONFIG: "config";
-    readonly CAMERA: "camera";
-    readonly SNAPSHOT: "snapshot";
-};
-
-/**
- * Generic message event - used for all message passing
- */
-declare interface MessageEvent_2<T extends Message = Message> {
-    message: T;
-}
-
-/**
- * Represents a 3D node in the scene
- * Live object that can be updated to reflect state changes
- */
-export declare class ModelNode {
-    readonly id: string;
-    readonly name: string;
-    readonly type: NodeType;
-    private visible;
-    onChange?: () => void;
-    constructor(params: CreateNodeParams);
-    get isVisible(): boolean;
-    show(): void;
-    hide(): void;
-}
-
-/**
- * DTO for model node data received from server
- */
-export declare interface ModelNodeDto {
-    readonly id: string;
-    readonly name: string;
-    readonly type: string;
-    readonly visible: boolean;
-}
-
-/**
- * A mutation represents a change to be applied to a 3D node
- * This is a pure data class with no side effects
- */
-export declare class Mutation {
-    readonly type: MutationType;
-    readonly nodeId: string;
-    constructor(type: MutationType, nodeId: string);
-    static show(nodeId: string): Mutation;
-    static hide(nodeId: string): Mutation;
-    inverse(): Mutation;
-    equals(other: Mutation): boolean;
-    toDto(): MutationDto;
-}
-
-/**
- * Types of mutations that can be applied to 3D nodes
- */
-export declare const MUTATION_TYPES: {
-    readonly SHOW: "show";
-    readonly HIDE: "hide";
-};
-
-/**
- * Data Transfer Object for mutations
- * Plain object for client-server communication without methods
- */
-export declare interface MutationDto {
-    readonly type: MutationType;
-    readonly nodeId: string;
-}
-
-/**
- * Mutation message sent to server
- */
-export declare interface MutationMessage {
-    readonly type: typeof MESSAGE_TYPES.MUTATION;
-    readonly mutations: MutationDto[];
-}
-
-export declare type MutationType = typeof MUTATION_TYPES[keyof typeof MUTATION_TYPES];
-
-/**
- * Types of nodes in the 3D scene
- */
-export declare const NODE_TYPES: {
-    readonly MESH: "mesh";
-    readonly VARIANT: "variant";
-};
-
-/**
- * Public API for controlling individual nodes
- * Provides direct node manipulation without attribute mapping
- */
-export declare class NodeSelector {
-    private readonly eventBus;
-    private readonly stateService;
-    private readonly nodeId;
-    constructor(eventBus: EventBus, stateService: StateService, nodeId: string);
-    show(): void;
-    hide(): void;
-    toggle(): void;
-    get id(): string;
-    get isVisible(): boolean;
-    getNode(): ModelNode | undefined;
-    get type(): string | undefined;
-    get name(): string | undefined;
-    private emitMutation;
-}
-
-declare type NodeType = typeof NODE_TYPES[keyof typeof NODE_TYPES];
-
-/**
- * Represents a photo being captured
- * Pure domain object that manages callbacks for when the photo is developed
- */
-export declare class Photo {
-    private readonly filename;
-    private readonly callbacks;
-    private developed;
-    private photoData;
-    constructor(filename: string);
-    /**
-     * Register a callback for when the photo is developed
-     * If the photo is already developed, the callback is called immediately
-     *
-     * @param callback Function to call with photo data
-     * @returns This Photo instance for chaining
-     */
-    onDeveloped(callback: (photo: PhotoData) => void): this;
-    /**
-     * Get the filename for this photo
-     */
-    getFilename(): string;
-    /**
-     * Mark the photo as developed and notify all callbacks
-     * This method is called by the SnapshotMessageHandler when the photo data arrives
-     */
-    develop(photoData: PhotoData): void;
-}
-
-export declare interface PhotoData {
-    readonly filename: string;
-    readonly data: string;
-}
-
-/**
- * API for taking screenshots of the 3D model
- * Following the camera analogy: take() triggers capture, onDeveloped() gets result
- */
-export declare class Snapshot {
-    private readonly eventBus;
-    private readonly validExtensions;
-    private readonly messageHandler;
-    constructor(eventBus: EventBus);
-    /**
-     * Take a snapshot of the current 3D model view
-     *
-     * @param filename The filename for the snapshot (must include valid extension)
-     * @returns Photo object for registering callbacks
-     * @throws VirtualdisplayError if filename is invalid
-     */
-    take(filename: string): Photo;
-    /**
-     * Validate filename has a valid image extension
-     */
-    private validateFilename;
-}
-
-/**
- * Snapshot developed message received from server
- */
-export declare interface SnapshotDevelopedMessage {
-    readonly type: typeof MESSAGE_TYPES.SNAPSHOT;
-    readonly filename: string;
-    readonly data: string;
-}
-
-/**
- * Snapshot request message sent to server
- */
-export declare interface SnapshotRequestMessage {
-    readonly type: typeof MESSAGE_TYPES.SNAPSHOT;
-    readonly filename: string;
-}
-
-declare interface StateChangedEvent {
-    nodes: ModelNode[];
-}
-
-/**
- * State message received from server
- * Contains array of model node DTOs
- */
-export declare interface StateMessage {
-    readonly type: typeof MESSAGE_TYPES.STATE;
-    readonly nodes: ModelNodeDto[];
-    readonly isInitial: boolean;
-}
-
-/**
- * Application service for managing node state
- * Handles state updates from server and emits node change events
- */
-declare class StateService {
-    private readonly nodes;
-    private readonly eventBus;
-    private hasReceivedInitialSync;
-    constructor(eventBus: EventBus);
-    private handleMessage;
-    private updateState;
-    private updateOrCreateNode;
-    private createNewNode;
-    getNode(id: string): ModelNode | undefined;
-    getAllNodes(): ModelNode[];
-    get isReady(): boolean;
-    get nodeCount(): number;
-    clear(): void;
-}
-
-/**
- * UI configuration options
- */
-export declare interface UIConfig {
-    readonly arEnabled?: boolean;
-    readonly fullscreenEnabled?: boolean;
-    readonly loadingIndicatorEnabled?: boolean;
-}
-
-/**
- * Viewer configuration
- */
-export declare interface ViewerConfig {
-    readonly ui?: UIConfig;
-    readonly camera?: CameraConfig;
-}
-
-/**
- * Main Virtualdisplay Client
- * Provides the public API for 3D product visualization
- */
-export declare class VirtualdisplayClient {
-    private readonly eventBus;
-    private readonly attributeService;
-    private readonly stateService;
-    private readonly messageHandler;
-    private readonly viewerService;
-    private readonly cameraApi;
-    private readonly snapshotApi;
-    private readonly options;
-    private iframe;
-    constructor(options: ClientOptions);
-    private initializeLogging;
-    private createAndConnectIframe;
-    private setupInitialConfig;
-    /**
-     * Load attribute mapping configuration
-     * @throws {VirtualdisplayError} When mapping configuration is invalid
-     */
-    setMapping(config: MappingConfiguration): void;
-    /**
-     * Get attribute selector for fluent API
-     * @throws {VirtualdisplayError} When no mapping is configured or attribute not found
-     */
-    getAttribute(name: string): AttributeSelector;
-    /**
-     * Get node selector for direct node control
-     * @param nodeId The node ID to control
-     * @returns NodeSelector if node exists, undefined otherwise
-     */
-    getNodeSelector(nodeId: string): NodeSelector | undefined;
-    getNode(id: string): ModelNode | undefined;
-    getNodes(): ModelNode[];
-    /**
-     * Check if the client has received initial state and is ready
-     */
-    get isReady(): boolean;
-    /**
-     * Register a callback to be called when the client is ready
-     * If already ready, the callback is called immediately
-     */
-    onReady(callback: () => void): void;
-    /**
-     * Get the viewer service for UI configuration
-     */
-    get viewer(): VirtualdisplayViewerService;
-    /**
-     * Get the camera control API
-     */
-    get camera(): Camera;
-    /**
-     * Get the snapshot API for taking screenshots
-     */
-    get snapshot(): Snapshot;
-    destroy(): void;
-}
-
-/**
- * Custom error class for Virtualdisplay client errors
- */
-export declare class VirtualdisplayError extends Error {
-    readonly code: ErrorCode;
-    constructor(message: string, code: ErrorCode);
-    static noMapping(): VirtualdisplayError;
-    static attributeNotFound(attributeName: string): VirtualdisplayError;
-    static valueNotFound(attributeName: string, valueName: string): VirtualdisplayError;
-    static invalidMapping(reason?: string): VirtualdisplayError;
-    static parentNotFound(selector: string): VirtualdisplayError;
-    static invalidMutations(reason?: string): VirtualdisplayError;
-}
-
-/**
- * Service responsible for managing viewer UI configuration
- * Sends CONFIG messages to control AR button, fullscreen button, and loading indicator
- */
-export declare class VirtualdisplayViewerService {
-    private readonly eventBus;
-    constructor(eventBus: EventBus);
-    /**
-     * Send initial configuration based on client options
-     * Supports both individual properties and ui object
-     */
-    sendInitialConfig(options: ClientOptions): void;
-    /**
-     * Build UI configuration from client options
-     *
-     * Supports both legacy properties (options.arEnabled) and the newer ui object
-     * for backward compatibility. Legacy properties take precedence when both exist.
-     */
-    private buildUIConfig;
-    /**
-     * Extract UI values from options, with legacy properties taking precedence
-     */
-    private extractUIValues;
-    /**
-     * Build viewer configuration from UI config and camera config
-     */
-    private buildViewerConfig;
-    /**
-     * Update AR button visibility
-     */
-    setArEnabled(enabled: boolean): void;
-    /**
-     * Update fullscreen button visibility
-     */
-    setFullscreenEnabled(enabled: boolean): void;
-    /**
-     * Update loading indicator visibility
-     */
-    setLoadingIndicatorEnabled(enabled: boolean): void;
-    /**
-     * Update multiple UI settings at once
-     */
-    updateUIConfig(config: Partial<UIConfig>): void;
-    /**
-     * Hide all UI elements
-     */
-    hideAllUI(): void;
-    /**
-     * Show all UI elements
-     */
-    showAllUI(): void;
-    /**
-     * Send UI configuration to server
-     */
-    private sendUIConfig;
-    /**
-     * Send full viewer configuration to server
-     */
-    private sendConfig;
-}
-
-declare interface VoidEvent {
-}
-
 export { }