saltfish
Version:
An interactive video-guided tour system for web applications
375 lines • 10.3 kB
TypeScript
/**
* Player state constants
*/
export declare const PLAYER_STATES: {
readonly IDLE: "idle";
readonly LOADING: "loading";
readonly PLAYING: "playing";
readonly PAUSED: "paused";
readonly WAITING_FOR_INTERACTION: "waitingForInteraction";
readonly AUTOPLAY_BLOCKED: "autoplayBlocked";
readonly MINIMIZED: "minimized";
readonly ERROR: "error";
readonly COMPLETED: "completed";
};
/**
* Position constants
*/
export declare const POSITIONS: {
readonly BOTTOM_RIGHT: "bottom-right";
readonly BOTTOM_LEFT: "bottom-left";
readonly TOP_RIGHT: "top-right";
readonly TOP_LEFT: "top-left";
readonly CENTER: "center";
};
/**
* Position keywords for string matching
*/
export declare const POSITION_KEYWORDS: {
readonly BOTTOM: "bottom";
readonly TOP: "top";
readonly LEFT: "left";
readonly RIGHT: "right";
readonly CENTER: "center";
};
/**
* Storage keys
*/
export declare const STORAGE_KEYS: {
readonly PROGRESS: "saltfish_progress";
readonly SESSION: "saltfish_session";
readonly ANONYMOUS_USER: "saltfish_anonymous_user_data";
};
/**
* Event names
*/
export declare const EVENT_NAMES: {
readonly INITIALIZED: "initialized";
readonly PLAYLIST_STARTED: "playlistStarted";
readonly PLAYLIST_ENDED: "playlistEnded";
readonly PLAYLIST_DISMISSED: "playlistDismissed";
readonly STEP_STARTED: "stepStarted";
readonly STEP_ENDED: "stepEnded";
readonly PLAYER_PAUSED: "playerPaused";
readonly PLAYER_RESUMED: "playerResumed";
readonly PLAYER_MINIMIZED: "playerMinimized";
readonly PLAYER_MAXIMIZED: "playerMaximized";
readonly USER_DATA_LOADED: "userDataLoaded";
readonly INTERACTION_REQUIRED: "interactionRequired";
readonly INTERACTION_COMPLETED: "interactionCompleted";
readonly ERROR: "error";
};
/**
* Dimensions and spacing constants
*/
export declare const DIMENSIONS: {
readonly DEFAULT_MARGIN: 20;
readonly SCREEN_EDGE_MARGIN: 20;
readonly RIGHT_EDGE_MARGIN: 20;
readonly CURSOR_DEFAULT_X: 50;
readonly CURSOR_DEFAULT_Y: 50;
readonly CURSOR_SCALE_ACTIVE: 0.9;
readonly CURSOR_SCALE_SMALL: 0.8;
readonly CURSOR_FLASHLIGHT_RADIUS: 150;
readonly PROGRESS_COMPLETE: 100;
readonly TRANSFORM_CENTER_X: "-50%";
readonly TRANSFORM_CENTER_Y: "-50%";
readonly TRANSFORM_BOTTOM: "-100%";
};
/**
* Timing constants (in milliseconds)
*/
export declare const TIMING: {
readonly DRAG_THRESHOLD_PX: 5;
readonly DRAG_RESET_DELAY: 300;
readonly VIDEO_PROGRESS_POLL_INTERVAL: 50;
readonly CURSOR_UPDATE_THROTTLE: 100;
readonly ANALYTICS_FLUSH_INTERVAL: 30000;
readonly USER_DATA_TIMEOUT: 5000;
readonly STEP_TIMEOUT: 60000;
readonly CURSOR_DEFAULT_DISTANCE: 100;
readonly SESSION_EXPIRY: number;
};
/**
* API constants
*/
export declare const API: {
readonly BASE_URL: "https://player.saltfish.ai";
readonly ENDPOINTS: {
readonly VALIDATE_TOKEN: "/validate-token";
readonly USERS: "/clients/{token}/users/{userId}";
};
};
/**
* State machine event types
*/
export declare const STATE_MACHINE_EVENTS: {
readonly INITIALIZE: "INITIALIZE";
readonly LOAD_MANIFEST: "LOAD_MANIFEST";
readonly MANIFEST_LOADED: "MANIFEST_LOADED";
readonly PLAY: "PLAY";
readonly PAUSE: "PAUSE";
readonly MINIMIZE: "MINIMIZE";
readonly MAXIMIZE: "MAXIMIZE";
readonly VIDEO_ENDED: "VIDEO_ENDED";
readonly TRANSITION_TO_STEP: "TRANSITION_TO_STEP";
readonly ERROR: "ERROR";
readonly COMPLETE_PLAYLIST: "COMPLETE_PLAYLIST";
readonly AUTOPLAY_FALLBACK: "AUTOPLAY_FALLBACK";
};
/**
* CSS class names
*/
export declare const CSS_CLASSES: {
readonly PLAYER: "sf-player";
readonly PLAYER_MINIMIZED: "sf-player--minimized";
readonly VIDEO_CONTAINER: "sf-video-container";
readonly CONTROLS_CONTAINER: "sf-controls-container";
readonly LOGO: "sf-player__logo";
readonly ERROR: "saltfish-error";
};
/**
* Default configuration
*/
export declare const DEFAULTS: {
readonly POSITION: "bottom-right";
readonly ALLOW_DRAG: true;
readonly PERSISTENCE: true;
readonly SESSION_RECORDING: false;
readonly ANALYTICS_ENABLED: true;
};
/**
* Represents the state of the Saltfish playlist Player
*/
export type PlayerState = typeof PLAYER_STATES[keyof typeof PLAYER_STATES];
/**
* Available position options
*/
export type Position = typeof POSITIONS[keyof typeof POSITIONS];
/**
* Configuration options for initializing the Saltfish playlist Player
*/
export interface SaltfishConfig {
/** API token for authentication */
token: string;
/** Whether to enable PostHog session recording for analytics (default: false) */
sessionRecording?: boolean;
/** Whether to enable analytics data collection and sending (default: true) */
enableAnalytics?: boolean;
/** Whether to show the saltfish logo at the bottom of the widget (set from backend) */
showLogo?: boolean;
}
/**
* Options for starting a playlist
*/
export interface PlaylistOptions {
position?: Position;
allowDrag?: boolean;
startNodeId?: string;
once?: boolean;
persistence?: boolean;
}
/**
* User identification data
*/
export interface UserData {
id: string;
[key: string]: any;
}
/**
* Point coordinates for cursor animation
*/
export interface Point {
x: number;
y: number;
time?: number;
}
/**
* Interactive button overlay configuration
*/
export interface ButtonOverlay {
id: string;
text: string;
style?: any;
action: {
type: 'next' | 'goto' | 'url' | 'dom' | 'function';
target: string;
};
}
/**
* DOM interaction target
*/
export interface DOMInteraction {
selector: string;
action: 'click' | 'hover' | 'focus' | 'input';
value?: string;
waitFor?: boolean;
}
/**
* Cursor animation configuration
*/
export interface CursorAnimation {
easing?: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
targetSelector: string;
mode?: 'pointer' | 'selection';
selectionStyles?: {
borderColor?: string;
borderWidth?: string;
borderRadius?: string;
padding?: string | number;
};
}
/**
* Step transition condition
*/
export interface TransitionCondition {
type: 'timeout' | 'dom-click' | 'url-path' | 'dom-element-visible';
target?: string;
value?: any;
timeout?: number;
nextStep: string;
}
/**
* Transcript segment with timing information
*/
export interface TranscriptSegment {
text: string;
start: number;
end: number;
}
/**
* Transcript data for a video step
*/
export interface Transcript {
text: string;
segments: TranscriptSegment[];
}
/**
* Step configuration
*/
export interface Step {
id: string;
videoUrl: string;
compressedVideoUrl?: string;
position?: Position;
buttons?: ButtonOverlay[];
domInteractions?: DOMInteraction[];
cursorAnimations?: CursorAnimation[];
transitions: TransitionCondition[];
transcript?: Transcript;
}
/**
* Device type options
*/
export type DeviceType = 'desktop' | 'mobile' | 'both';
/**
* playlist manifest
*/
export interface playlistManifest {
id: string;
name: string;
version: string;
position: Position;
startStep: string;
steps: Step[];
translations?: Record<string, Record<string, string>>;
cursorColor?: string;
deviceType?: DeviceType;
}
/**
* Analytics event
*/
export interface AnalyticsEvent {
type: 'playlistStart' | 'playlistComplete' | 'stepStarted' | 'stepComplete' | 'interaction' | 'error' | 'playerPaused' | 'playerResumed' | 'playerMinimized' | 'playerMaximized';
playlistId: string;
stepId?: string;
runId: string;
timestamp: number;
data?: any;
}
/**
* Available playlist metadata
*/
export interface PlaylistMetadata {
id: string;
name: string;
description?: string;
thumbnailUrl?: string;
}
/**
* Represents trigger conditions for autoStart playlists
*/
export interface PlaylistTriggers {
once: boolean;
operators: string[];
playlistNotSeen: string[];
playlistSeen: string[];
url: string | null;
}
/**
* Represents a playlist entry with path info returned by the backend
*/
export interface PlaylistPathInfo {
id: string;
path: string;
autoStart: boolean;
isLive: boolean;
triggers?: PlaylistTriggers;
}
/**
* State store
*/
export interface SaltfishStore {
config: SaltfishConfig | null;
user: UserData | null;
userData: any | null;
currentState: PlayerState;
manifest: playlistManifest | null;
currentStepId: string | null;
isMinimized: boolean;
position: {
x: number;
y: number;
} | null;
progress: Record<string, any>;
error: Error | null;
stateMachine: any;
playlistOptions: PlaylistOptions | null;
backendPlaylists?: PlaylistPathInfo[];
initialize: (config: SaltfishConfig) => Promise<void>;
identifyUser: (userId: string, userData?: any) => void;
setUserData: (userData: any) => void;
setManifest: (manifest: playlistManifest, startStepId: string) => void;
play: () => void;
pause: () => void;
minimize: () => void;
maximize: () => void;
setPosition: (x: number, y: number) => void;
goToStep: (stepId: string) => void;
reset: () => void;
setError: (error: Error) => void;
setAutoplayFallback: () => void;
setPlaylistOptions: (options: PlaylistOptions) => void;
setBackendPlaylists?: (playlists: PlaylistPathInfo[]) => void;
completePlaylist: () => void;
resetForNewPlaylist: () => void;
loadPlaylistProgress: (playlistId: string, progress: any) => void;
}
/**
* Player state events
*/
export declare const PLAYER_EVENTS: {
readonly INITIALIZE: "INITIALIZE";
readonly LOAD_MANIFEST: "LOAD_MANIFEST";
readonly MANIFEST_LOADED: "MANIFEST_LOADED";
readonly PLAY: "PLAY";
readonly PAUSE: "PAUSE";
readonly MINIMIZE: "MINIMIZE";
readonly MAXIMIZE: "MAXIMIZE";
readonly VIDEO_ENDED: "VIDEO_ENDED";
readonly TRANSITION_TO_STEP: "TRANSITION_TO_STEP";
readonly ERROR: "ERROR";
readonly COMPLETE_PLAYLIST: "COMPLETE_PLAYLIST";
readonly AUTOPLAY_FALLBACK: "AUTOPLAY_FALLBACK";
};
//# sourceMappingURL=index.d.ts.map