@snowcone-app/sdk 0.1.10

package/dist/websocket-GXMYofWp.d.cts

@@ -0,0 +1,330 @@
+type OptionSelection = Record<string, string>;
+interface OptionAttribute {
+    key: string;
+    affectsCombinations: boolean;
+    choices: string[];
+    type?: string;
+}
+interface Combination {
+    variantId: string;
+    price?: number;
+    [key: string]: string | number | undefined;
+}
+declare function resolveBestCombination(selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): Combination | undefined;
+/**
+ * Computes which choices should be disabled for each attribute based on the current selection
+ * and the list of valid combinations. Non-affecting attributes never disable choices.
+ */
+declare function computeDisabledChoices(selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): Record<string, string[]>;
+/**
+ * Derives a reasonable default selection based on the best combination.
+ * - For attributes that affect combinations, choose the value from the best combo.
+ * - For non-affecting attributes, leave unset (caller may choose first choice if desired).
+ */
+declare function deriveDefaultSelection(attributes: Record<string, OptionAttribute>, combinations: Combination[]): OptionSelection;
+/**
+ * Returns the price (if any) of the current best combination for the given selection.
+ */
+declare function getPricePreview(selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): number | undefined;
+/**
+ * Finds the best matching combination for a given selection.
+ * Filters selection to only include attributes that affect combinations.
+ * @param selection Current selection state
+ * @param combinations All valid combinations
+ * @param attributes All product attributes
+ * @returns The best matching combination or undefined
+ */
+declare function findBestCombination(selection: OptionSelection, combinations: Combination[], attributes?: Record<string, OptionAttribute>): Combination | undefined;
+/**
+ * Checks if a specific option is available based on the current selection and combinations.
+ * This is useful for checking individual options without computing all disabled choices.
+ * @param optionName The specific option/choice to check
+ * @param attributeName The attribute this option belongs to
+ * @param selection Current selection state
+ * @param attributes All product attributes
+ * @param combinations All valid combinations
+ * @returns true if the option is available, false if disabled
+ */
+declare function isOptionAvailable(optionName: string, attributeName: string, selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): boolean;
+
+/**
+ * Framework adapter pattern for supporting multiple UI frameworks
+ * Provides a common interface for React, Web Components, Vue, Svelte, etc.
+ */
+
+/**
+ * Common component properties that all frameworks must support
+ */
+interface ComponentProps {
+    className?: string;
+    style?: Record<string, any>;
+    children?: any;
+    [key: string]: any;
+}
+/**
+ * Event handler definition
+ */
+interface EventHandler<T = any> {
+    name: string;
+    handler: (event: T) => void;
+}
+/**
+ * Component lifecycle hooks
+ */
+interface ComponentLifecycleHooks {
+    onMount?: () => void;
+    onUnmount?: () => void;
+    onUpdate?: (prevProps: ComponentProps) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Component state management
+ */
+interface ComponentState<T = any> {
+    get(): T;
+    set(value: T | ((prev: T) => T)): void;
+    subscribe(callback: (value: T) => void): () => void;
+}
+/**
+ * Component context interface
+ */
+interface ComponentContext<T = any> {
+    provide(value: T): void;
+    consume(): T | undefined;
+    subscribe(callback: (value: T) => void): () => void;
+}
+/**
+ * Framework-specific rendering result
+ */
+type RenderResult = any;
+/**
+ * Framework adapter interface
+ */
+interface FrameworkAdapter<TProps = ComponentProps> {
+    /**
+     * Framework name for identification
+     */
+    name: 'react' | 'vue' | 'svelte' | 'lit' | 'vanilla' | string;
+    /**
+     * Create a stateful value
+     */
+    createState<T>(initialValue: T): ComponentState<T>;
+    /**
+     * Create a context provider/consumer
+     */
+    createContext<T>(name: string): ComponentContext<T>;
+    /**
+     * Register lifecycle hooks
+     */
+    useLifecycle(lifecycle: ComponentLifecycleHooks): void;
+    /**
+     * Register event handlers
+     */
+    useEvents(handlers: EventHandler[]): void;
+    /**
+     * Create a ref to a DOM element
+     */
+    createRef<T extends HTMLElement>(): {
+        current: T | null;
+    };
+    /**
+     * Render method for the framework
+     */
+    render(component: ComponentDescriptor, props: TProps): RenderResult;
+    /**
+     * Get framework-specific utilities
+     */
+    getUtilities(): FrameworkUtilities;
+}
+/**
+ * Framework-specific utilities
+ */
+interface FrameworkUtilities {
+    /**
+     * Batch multiple state updates
+     */
+    batchUpdates?: (callback: () => void) => void;
+    /**
+     * Schedule an update for the next tick
+     */
+    nextTick?: (callback: () => void) => void;
+    /**
+     * Create a computed/derived value
+     */
+    computed?: <T>(deps: any[], compute: () => T) => T;
+    /**
+     * Create a memoized value
+     */
+    memo?: <T>(value: T, deps: any[]) => T;
+}
+/**
+ * Component descriptor for cross-framework components
+ */
+interface ComponentDescriptor {
+    name: string;
+    props: ComponentProps;
+    state?: Record<string, any>;
+    methods?: Record<string, Function>;
+    lifecycle?: ComponentLifecycleHooks;
+    render: (adapter: FrameworkAdapter) => RenderResult;
+}
+/**
+ * Product-specific component context
+ */
+interface ProductComponentContext {
+    product?: any;
+    optionAttributes: Record<string, OptionAttribute>;
+    combinations: Combination[];
+    selection: OptionSelection;
+    updateSelection: (selection: OptionSelection) => void;
+}
+/**
+ * Base component factory
+ */
+declare function createComponent<TProps extends ComponentProps = ComponentProps>(descriptor: ComponentDescriptor, adapter: FrameworkAdapter<TProps>): any;
+/**
+ * Create a framework-agnostic component definition
+ */
+declare function defineComponent<TProps extends ComponentProps = ComponentProps>(definition: {
+    name: string;
+    props?: Record<string, any>;
+    state?: Record<string, any>;
+    methods?: Record<string, Function>;
+    lifecycle?: ComponentLifecycleHooks;
+    render: (props: TProps, adapter: FrameworkAdapter<TProps>) => RenderResult;
+}): ComponentDescriptor;
+/**
+ * Adapter registry for managing multiple frameworks
+ */
+declare class AdapterRegistry {
+    private adapters;
+    register(adapter: FrameworkAdapter): void;
+    get(name: string): FrameworkAdapter | undefined;
+    getAll(): FrameworkAdapter[];
+}
+declare const adapterRegistry: AdapterRegistry;
+
+interface PlacementSettings {
+    tiles?: 0.25 | 0.5 | 1 | 2 | 4 | 8 | 16;
+}
+interface WebSocketConfig {
+    productId: string;
+    mockupIds: string[];
+    variantId: string;
+    accountId: string;
+    sig: string;
+    width: number;
+    /** Aspect ratio for mockup rendering (e.g. '2:3' for portrait). Server default: '16:9' */
+    ar?: string;
+    placementSettings?: Record<string, PlacementSettings>;
+}
+interface MockupResult {
+    mockupId: string;
+    imageUrl: string;
+    renderUrl: string;
+    imageSize: number;
+    /** The request version this mockup corresponds to (for stale detection) */
+    requestVersion?: number;
+    /** The placement this mockup corresponds to */
+    placement?: string;
+}
+interface WebSocketMessage {
+    type: string;
+    sessionId?: string;
+    mockups?: MockupResult[];
+    imageUrl?: string;
+    renderUrl?: string;
+    mockupId?: string;
+    imageSize?: number;
+    message?: string;
+    placement?: string;
+    missingPlacements?: string[];
+    /** The request version this response corresponds to (for stale detection) */
+    requestVersion?: number;
+}
+interface RealtimeMockupState {
+    isConnected: boolean;
+    sessionId: string | null;
+    isConfigured: boolean;
+    mockupResults: MockupResult[];
+    status: string;
+    logs: string[];
+    lastError: string | null;
+}
+interface RealtimeMockupCallbacks {
+    onConnected?: (sessionId: string) => void;
+    onDisconnected?: () => void;
+    onConfigReceived?: () => void;
+    /** Called when server confirms it received a blob for a placement */
+    onBlobReceived?: (placement: string) => void;
+    /** Called when a blob is actually sent to server (after throttle completes) */
+    onBlobSent?: (placement: string) => void;
+    onMockupRendered?: (result: MockupResult) => void;
+    onAllMockupsRendered?: (results: MockupResult[]) => void;
+    onError?: (error: string) => void;
+    onLog?: (message: string, type: 'info' | 'sent' | 'received') => void;
+}
+declare class RealtimeMockupService {
+    private wsUrl;
+    private ws;
+    private config;
+    private configSent;
+    private sessionId;
+    private isConfigured;
+    private mockupResults;
+    private status;
+    private logs;
+    private lastError;
+    private callbacks;
+    private canvasBlobs;
+    private colors;
+    private lastSendTime;
+    private throttleTimeouts;
+    private requestVersion;
+    private lastSentVersion;
+    private latestSentVersionByPlacement;
+    private sendVersionInBlob;
+    constructor(wsUrl?: string);
+    setCallbacks(callbacks: RealtimeMockupCallbacks): void;
+    getState(): RealtimeMockupState;
+    private addLog;
+    connect(): void;
+    private handleMessage;
+    disconnect(): void;
+    sendConfig(config: WebSocketConfig): boolean;
+    /**
+     * Update only the mockupIds without changing other config.
+     * Server will use already-cached blobs to render the requested mockups.
+     * This is the preferred method for priority-based rendering.
+     */
+    updateMockupIds(mockupIds: string[]): boolean;
+    sendCanvasBlob(placement: string, blob: Blob, mockupCount?: number, baseThrottleMs?: number, notifyCallback?: boolean): boolean;
+    private sendBlobImmediately;
+    /**
+     * Enable sending version number in blob messages.
+     * Call this once the server supports the new format: <placement>\n<version>\n<blob>
+     */
+    enableVersionInBlob(enabled?: boolean): void;
+    /**
+     * Flush all pending throttled blobs immediately.
+     * Call this when the user finishes an action (e.g., mouse up after drag/flip)
+     * to ensure the final state is sent without waiting for throttle.
+     */
+    flushPendingBlobs(): void;
+    /**
+     * Check if there are pending blobs waiting to be sent (in throttle queue)
+     */
+    hasPendingBlobs(): boolean;
+    sendColorBlob(placement: string, hexColor: string): boolean;
+    createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
+    sendInitialEmptyCanvases(placements: Array<{
+        label: string;
+        width?: number;
+        height?: number;
+    }>): Promise<void>;
+    setInitialData(canvasBlobs: Map<string, Blob>, colors: Map<string, string>): void;
+    clearLogs(): void;
+    clearMockups(): void;
+}
+
+export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type ProductComponentContext as P, type RenderResult as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, createComponent as h, defineComponent as i, adapterRegistry as j, RealtimeMockupService as k, type WebSocketMessage as l, type RealtimeMockupState as m, type RealtimeMockupCallbacks as n, computeDisabledChoices as o, deriveDefaultSelection as p, getPricePreview as q, resolveBestCombination as r, findBestCombination as s, isOptionAvailable as t };

package/dist/websocket-GXMYofWp.d.ts

@@ -0,0 +1,330 @@
+type OptionSelection = Record<string, string>;
+interface OptionAttribute {
+    key: string;
+    affectsCombinations: boolean;
+    choices: string[];
+    type?: string;
+}
+interface Combination {
+    variantId: string;
+    price?: number;
+    [key: string]: string | number | undefined;
+}
+declare function resolveBestCombination(selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): Combination | undefined;
+/**
+ * Computes which choices should be disabled for each attribute based on the current selection
+ * and the list of valid combinations. Non-affecting attributes never disable choices.
+ */
+declare function computeDisabledChoices(selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): Record<string, string[]>;
+/**
+ * Derives a reasonable default selection based on the best combination.
+ * - For attributes that affect combinations, choose the value from the best combo.
+ * - For non-affecting attributes, leave unset (caller may choose first choice if desired).
+ */
+declare function deriveDefaultSelection(attributes: Record<string, OptionAttribute>, combinations: Combination[]): OptionSelection;
+/**
+ * Returns the price (if any) of the current best combination for the given selection.
+ */
+declare function getPricePreview(selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): number | undefined;
+/**
+ * Finds the best matching combination for a given selection.
+ * Filters selection to only include attributes that affect combinations.
+ * @param selection Current selection state
+ * @param combinations All valid combinations
+ * @param attributes All product attributes
+ * @returns The best matching combination or undefined
+ */
+declare function findBestCombination(selection: OptionSelection, combinations: Combination[], attributes?: Record<string, OptionAttribute>): Combination | undefined;
+/**
+ * Checks if a specific option is available based on the current selection and combinations.
+ * This is useful for checking individual options without computing all disabled choices.
+ * @param optionName The specific option/choice to check
+ * @param attributeName The attribute this option belongs to
+ * @param selection Current selection state
+ * @param attributes All product attributes
+ * @param combinations All valid combinations
+ * @returns true if the option is available, false if disabled
+ */
+declare function isOptionAvailable(optionName: string, attributeName: string, selection: OptionSelection, attributes: Record<string, OptionAttribute>, combinations: Combination[]): boolean;
+
+/**
+ * Framework adapter pattern for supporting multiple UI frameworks
+ * Provides a common interface for React, Web Components, Vue, Svelte, etc.
+ */
+
+/**
+ * Common component properties that all frameworks must support
+ */
+interface ComponentProps {
+    className?: string;
+    style?: Record<string, any>;
+    children?: any;
+    [key: string]: any;
+}
+/**
+ * Event handler definition
+ */
+interface EventHandler<T = any> {
+    name: string;
+    handler: (event: T) => void;
+}
+/**
+ * Component lifecycle hooks
+ */
+interface ComponentLifecycleHooks {
+    onMount?: () => void;
+    onUnmount?: () => void;
+    onUpdate?: (prevProps: ComponentProps) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Component state management
+ */
+interface ComponentState<T = any> {
+    get(): T;
+    set(value: T | ((prev: T) => T)): void;
+    subscribe(callback: (value: T) => void): () => void;
+}
+/**
+ * Component context interface
+ */
+interface ComponentContext<T = any> {
+    provide(value: T): void;
+    consume(): T | undefined;
+    subscribe(callback: (value: T) => void): () => void;
+}
+/**
+ * Framework-specific rendering result
+ */
+type RenderResult = any;
+/**
+ * Framework adapter interface
+ */
+interface FrameworkAdapter<TProps = ComponentProps> {
+    /**
+     * Framework name for identification
+     */
+    name: 'react' | 'vue' | 'svelte' | 'lit' | 'vanilla' | string;
+    /**
+     * Create a stateful value
+     */
+    createState<T>(initialValue: T): ComponentState<T>;
+    /**
+     * Create a context provider/consumer
+     */
+    createContext<T>(name: string): ComponentContext<T>;
+    /**
+     * Register lifecycle hooks
+     */
+    useLifecycle(lifecycle: ComponentLifecycleHooks): void;
+    /**
+     * Register event handlers
+     */
+    useEvents(handlers: EventHandler[]): void;
+    /**
+     * Create a ref to a DOM element
+     */
+    createRef<T extends HTMLElement>(): {
+        current: T | null;
+    };
+    /**
+     * Render method for the framework
+     */
+    render(component: ComponentDescriptor, props: TProps): RenderResult;
+    /**
+     * Get framework-specific utilities
+     */
+    getUtilities(): FrameworkUtilities;
+}
+/**
+ * Framework-specific utilities
+ */
+interface FrameworkUtilities {
+    /**
+     * Batch multiple state updates
+     */
+    batchUpdates?: (callback: () => void) => void;
+    /**
+     * Schedule an update for the next tick
+     */
+    nextTick?: (callback: () => void) => void;
+    /**
+     * Create a computed/derived value
+     */
+    computed?: <T>(deps: any[], compute: () => T) => T;
+    /**
+     * Create a memoized value
+     */
+    memo?: <T>(value: T, deps: any[]) => T;
+}
+/**
+ * Component descriptor for cross-framework components
+ */
+interface ComponentDescriptor {
+    name: string;
+    props: ComponentProps;
+    state?: Record<string, any>;
+    methods?: Record<string, Function>;
+    lifecycle?: ComponentLifecycleHooks;
+    render: (adapter: FrameworkAdapter) => RenderResult;
+}
+/**
+ * Product-specific component context
+ */
+interface ProductComponentContext {
+    product?: any;
+    optionAttributes: Record<string, OptionAttribute>;
+    combinations: Combination[];
+    selection: OptionSelection;
+    updateSelection: (selection: OptionSelection) => void;
+}
+/**
+ * Base component factory
+ */
+declare function createComponent<TProps extends ComponentProps = ComponentProps>(descriptor: ComponentDescriptor, adapter: FrameworkAdapter<TProps>): any;
+/**
+ * Create a framework-agnostic component definition
+ */
+declare function defineComponent<TProps extends ComponentProps = ComponentProps>(definition: {
+    name: string;
+    props?: Record<string, any>;
+    state?: Record<string, any>;
+    methods?: Record<string, Function>;
+    lifecycle?: ComponentLifecycleHooks;
+    render: (props: TProps, adapter: FrameworkAdapter<TProps>) => RenderResult;
+}): ComponentDescriptor;
+/**
+ * Adapter registry for managing multiple frameworks
+ */
+declare class AdapterRegistry {
+    private adapters;
+    register(adapter: FrameworkAdapter): void;
+    get(name: string): FrameworkAdapter | undefined;
+    getAll(): FrameworkAdapter[];
+}
+declare const adapterRegistry: AdapterRegistry;
+
+interface PlacementSettings {
+    tiles?: 0.25 | 0.5 | 1 | 2 | 4 | 8 | 16;
+}
+interface WebSocketConfig {
+    productId: string;
+    mockupIds: string[];
+    variantId: string;
+    accountId: string;
+    sig: string;
+    width: number;
+    /** Aspect ratio for mockup rendering (e.g. '2:3' for portrait). Server default: '16:9' */
+    ar?: string;
+    placementSettings?: Record<string, PlacementSettings>;
+}
+interface MockupResult {
+    mockupId: string;
+    imageUrl: string;
+    renderUrl: string;
+    imageSize: number;
+    /** The request version this mockup corresponds to (for stale detection) */
+    requestVersion?: number;
+    /** The placement this mockup corresponds to */
+    placement?: string;
+}
+interface WebSocketMessage {
+    type: string;
+    sessionId?: string;
+    mockups?: MockupResult[];
+    imageUrl?: string;
+    renderUrl?: string;
+    mockupId?: string;
+    imageSize?: number;
+    message?: string;
+    placement?: string;
+    missingPlacements?: string[];
+    /** The request version this response corresponds to (for stale detection) */
+    requestVersion?: number;
+}
+interface RealtimeMockupState {
+    isConnected: boolean;
+    sessionId: string | null;
+    isConfigured: boolean;
+    mockupResults: MockupResult[];
+    status: string;
+    logs: string[];
+    lastError: string | null;
+}
+interface RealtimeMockupCallbacks {
+    onConnected?: (sessionId: string) => void;
+    onDisconnected?: () => void;
+    onConfigReceived?: () => void;
+    /** Called when server confirms it received a blob for a placement */
+    onBlobReceived?: (placement: string) => void;
+    /** Called when a blob is actually sent to server (after throttle completes) */
+    onBlobSent?: (placement: string) => void;
+    onMockupRendered?: (result: MockupResult) => void;
+    onAllMockupsRendered?: (results: MockupResult[]) => void;
+    onError?: (error: string) => void;
+    onLog?: (message: string, type: 'info' | 'sent' | 'received') => void;
+}
+declare class RealtimeMockupService {
+    private wsUrl;
+    private ws;
+    private config;
+    private configSent;
+    private sessionId;
+    private isConfigured;
+    private mockupResults;
+    private status;
+    private logs;
+    private lastError;
+    private callbacks;
+    private canvasBlobs;
+    private colors;
+    private lastSendTime;
+    private throttleTimeouts;
+    private requestVersion;
+    private lastSentVersion;
+    private latestSentVersionByPlacement;
+    private sendVersionInBlob;
+    constructor(wsUrl?: string);
+    setCallbacks(callbacks: RealtimeMockupCallbacks): void;
+    getState(): RealtimeMockupState;
+    private addLog;
+    connect(): void;
+    private handleMessage;
+    disconnect(): void;
+    sendConfig(config: WebSocketConfig): boolean;
+    /**
+     * Update only the mockupIds without changing other config.
+     * Server will use already-cached blobs to render the requested mockups.
+     * This is the preferred method for priority-based rendering.
+     */
+    updateMockupIds(mockupIds: string[]): boolean;
+    sendCanvasBlob(placement: string, blob: Blob, mockupCount?: number, baseThrottleMs?: number, notifyCallback?: boolean): boolean;
+    private sendBlobImmediately;
+    /**
+     * Enable sending version number in blob messages.
+     * Call this once the server supports the new format: <placement>\n<version>\n<blob>
+     */
+    enableVersionInBlob(enabled?: boolean): void;
+    /**
+     * Flush all pending throttled blobs immediately.
+     * Call this when the user finishes an action (e.g., mouse up after drag/flip)
+     * to ensure the final state is sent without waiting for throttle.
+     */
+    flushPendingBlobs(): void;
+    /**
+     * Check if there are pending blobs waiting to be sent (in throttle queue)
+     */
+    hasPendingBlobs(): boolean;
+    sendColorBlob(placement: string, hexColor: string): boolean;
+    createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
+    sendInitialEmptyCanvases(placements: Array<{
+        label: string;
+        width?: number;
+        height?: number;
+    }>): Promise<void>;
+    setInitialData(canvasBlobs: Map<string, Blob>, colors: Map<string, string>): void;
+    clearLogs(): void;
+    clearMockups(): void;
+}
+
+export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type ProductComponentContext as P, type RenderResult as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, createComponent as h, defineComponent as i, adapterRegistry as j, RealtimeMockupService as k, type WebSocketMessage as l, type RealtimeMockupState as m, type RealtimeMockupCallbacks as n, computeDisabledChoices as o, deriveDefaultSelection as p, getPricePreview as q, resolveBestCombination as r, findBestCombination as s, isOptionAvailable as t };