saltfish 0.2.38 → 0.2.40

package/README.md

@@ -0,0 +1,420 @@
+# Saltfish
+
+An interactive video-guided tour system for web applications. Create engaging onboarding experiences and product walkthroughs with synchronized video playback and interactive overlays.
+
+[![npm version](https://img.shields.io/npm/v/saltfish.svg)](https://www.npmjs.com/package/saltfish)
+[![License](https://img.shields.io/npm/l/saltfish.svg)](https://github.com/Saltfish-AB/playlist-player/blob/main/LICENSE)
+
+## Features
+
+- 🎥 **Video-Guided Tours** - Synchronize video content with interactive UI elements
+- 🎯 **Interactive Overlays** - Highlight and interact with elements during video playback
+- 📱 **Responsive Design** - Automatically adapts to different screen sizes
+- 🎨 **Customizable UI** - Shadow DOM encapsulation prevents style conflicts
+- 📊 **Built-in Analytics** - Track user engagement and progress
+- 🔄 **State Persistence** - Resume tours where users left off
+- 🌐 **Multi-language Support** - Built-in i18n capabilities
+- ⚡ **Lightweight** - Minimal bundle size with efficient loading
+
+## Installation
+
+### NPM
+
+```bash
+npm install saltfish
+```
+
+```javascript
+import { SaltfishPlayer } from 'saltfish';
+
+const player = new SaltfishPlayer({
+  token: 'your-token-here',
+  containerId: 'player-container',
+  apiBaseUrl: 'https://api.saltfish.ai' // optional
+});
+
+player.loadPlaylist('playlist-id');
+```
+
+### CDN
+
+```html
+<!-- Include the script -->
+<script src="https://storage.saltfish.ai/player/player.js"></script>
+
+<!-- Create a container -->
+<div id="player-container"></div>
+
+<script>
+  const player = new SaltfishPlayer({
+    token: 'your-token-here',
+    containerId: 'player-container'
+  });
+
+  player.loadPlaylist('playlist-id');
+</script>
+```
+
+## Quick Start
+
+### Basic Usage
+
+```javascript
+// Initialize the player
+const player = new SaltfishPlayer({
+  token: 'your-api-token',
+  containerId: 'player-container',
+  // Optional configuration
+  onComplete: () => {
+    console.log('Tour completed!');
+  },
+  onError: (error) => {
+    console.error('Player error:', error);
+  }
+});
+
+// Load and play a playlist
+await player.loadPlaylist('playlist-id');
+```
+
+### With Custom Configuration
+
+```javascript
+const player = new SaltfishPlayer({
+  token: 'your-api-token',
+  containerId: 'player-container',
+  apiBaseUrl: 'https://api.saltfish.ai',
+  autoplay: true,
+  enableAnalytics: true,
+  startMinimized: false,
+  onStepChange: (stepIndex) => {
+    console.log('Current step:', stepIndex);
+  },
+  onComplete: () => {
+    console.log('Playlist completed!');
+  },
+  onError: (error) => {
+    console.error('Error:', error);
+  }
+});
+
+await player.loadPlaylist('playlist-id');
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | `string` | **required** | Your Saltfish API token |
+| `containerId` | `string` | **required** | DOM element ID where player will be rendered |
+| `apiBaseUrl` | `string` | `'https://api.saltfish.ai'` | API endpoint URL |
+| `autoplay` | `boolean` | `true` | Start playing automatically |
+| `enableAnalytics` | `boolean` | `true` | Enable analytics tracking |
+| `startMinimized` | `boolean` | `false` | Start player in minimized state |
+| `onComplete` | `function` | `undefined` | Callback when playlist completes |
+| `onError` | `function` | `undefined` | Error handler callback |
+| `onStepChange` | `function` | `undefined` | Callback when video step changes |
+
+## API Reference
+
+### Methods
+
+#### `loadPlaylist(playlistId: string): Promise<void>`
+Load and initialize a playlist by ID.
+
+```javascript
+await player.loadPlaylist('playlist-123');
+```
+
+#### `play(): void`
+Start or resume video playback.
+
+```javascript
+player.play();
+```
+
+#### `pause(): void`
+Pause video playback.
+
+```javascript
+player.pause();
+```
+
+#### `minimize(): void`
+Minimize the player to corner of screen.
+
+```javascript
+player.minimize();
+```
+
+#### `maximize(): void`
+Restore player to full size.
+
+```javascript
+player.maximize();
+```
+
+#### `destroy(): void`
+Clean up and remove the player instance.
+
+```javascript
+player.destroy();
+```
+
+#### `getState(): PlayerState`
+Get current player state.
+
+```javascript
+const state = player.getState();
+console.log(state.currentStepIndex, state.isPlaying);
+```
+
+### Events
+
+Listen to player events using the event system:
+
+```javascript
+player.on('stateChange', (newState) => {
+  console.log('Player state changed:', newState);
+});
+
+player.on('videoEnded', () => {
+  console.log('Current video ended');
+});
+
+player.on('error', (error) => {
+  console.error('Player error:', error);
+});
+```
+
+## Player States
+
+The player implements a finite state machine with these states:
+
+- `idle` - Initial state
+- `loading` - Fetching playlist data
+- `playing` - Video is playing
+- `paused` - Video is paused
+- `minimized` - Player minimized to corner
+- `completed` - Playlist finished
+- `error` - Error occurred
+
+## Advanced Usage
+
+### Custom Styling
+
+The player uses Shadow DOM for style encapsulation. To customize appearance, use CSS custom properties:
+
+```css
+#player-container {
+  --saltfish-primary-color: #0066ff;
+  --saltfish-background: #ffffff;
+  --saltfish-text-color: #333333;
+  --saltfish-border-radius: 8px;
+}
+```
+
+### Analytics Integration
+
+Track custom events alongside built-in analytics:
+
+```javascript
+player.on('stateChange', (state) => {
+  // Send to your analytics service
+  analytics.track('Saltfish Player State', {
+    state: state.playerState,
+    step: state.currentStepIndex
+  });
+});
+```
+
+### Session Management
+
+The player automatically manages user sessions with 30-minute persistence:
+
+```javascript
+// Sessions are tracked automatically
+// Resume functionality works out of the box
+const player = new SaltfishPlayer({
+  token: 'your-token',
+  containerId: 'player-container'
+  // User progress is automatically saved and restored
+});
+```
+
+## Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- Opera 76+
+
+## TypeScript Support
+
+Full TypeScript definitions are included:
+
+```typescript
+import { SaltfishPlayer, PlayerConfig, PlayerState } from 'saltfish';
+
+const config: PlayerConfig = {
+  token: 'your-token',
+  containerId: 'player-container',
+  autoplay: true
+};
+
+const player = new SaltfishPlayer(config);
+const state: PlayerState = player.getState();
+```
+
+## Examples
+
+### React Integration
+
+```jsx
+import { useEffect, useRef } from 'react';
+import { SaltfishPlayer } from 'saltfish';
+
+function OnboardingTour() {
+  const containerRef = useRef(null);
+  const playerRef = useRef(null);
+
+  useEffect(() => {
+    if (containerRef.current) {
+      playerRef.current = new SaltfishPlayer({
+        token: process.env.REACT_APP_SALTFISH_TOKEN,
+        containerId: 'saltfish-container',
+        onComplete: () => {
+          console.log('Onboarding completed!');
+        }
+      });
+
+      playerRef.current.loadPlaylist('onboarding-tour');
+    }
+
+    return () => {
+      playerRef.current?.destroy();
+    };
+  }, []);
+
+  return <div id="saltfish-container" ref={containerRef} />;
+}
+```
+
+### Vue Integration
+
+```vue
+<template>
+  <div id="saltfish-container" ref="container"></div>
+</template>
+
+<script>
+import { SaltfishPlayer } from 'saltfish';
+
+export default {
+  name: 'OnboardingTour',
+  mounted() {
+    this.player = new SaltfishPlayer({
+      token: process.env.VUE_APP_SALTFISH_TOKEN,
+      containerId: 'saltfish-container',
+      onComplete: () => {
+        console.log('Tour completed!');
+      }
+    });
+
+    this.player.loadPlaylist('onboarding-tour');
+  },
+  beforeUnmount() {
+    this.player?.destroy();
+  }
+};
+</script>
+```
+
+### Angular Integration
+
+```typescript
+import { Component, OnInit, OnDestroy } from '@angular/core';
+import { SaltfishPlayer } from 'saltfish';
+
+@Component({
+  selector: 'app-onboarding',
+  template: '<div id="saltfish-container"></div>'
+})
+export class OnboardingComponent implements OnInit, OnDestroy {
+  private player: SaltfishPlayer;
+
+  ngOnInit() {
+    this.player = new SaltfishPlayer({
+      token: environment.saltfishToken,
+      containerId: 'saltfish-container',
+      onComplete: () => {
+        console.log('Onboarding completed!');
+      }
+    });
+
+    this.player.loadPlaylist('onboarding-tour');
+  }
+
+  ngOnDestroy() {
+    this.player?.destroy();
+  }
+}
+```
+
+## Troubleshooting
+
+### Player not loading
+
+- Verify your API token is valid
+- Check that the container element exists in the DOM
+- Ensure the playlist ID is correct
+- Check browser console for errors
+
+### Autoplay issues
+
+Some browsers block autoplay. The player automatically handles this:
+
+```javascript
+const player = new SaltfishPlayer({
+  token: 'your-token',
+  containerId: 'player-container',
+  autoplay: true // Player will show fallback UI if autoplay is blocked
+});
+```
+
+### Style conflicts
+
+The player uses Shadow DOM to prevent style conflicts. If you need to customize:
+
+```css
+/* Use CSS custom properties */
+#player-container {
+  --saltfish-z-index: 1000;
+}
+```
+
+## Getting a Token
+
+To use Saltfish, you need an API token. Visit [saltfish.ai](https://saltfish.ai) to:
+
+1. Create an account
+2. Generate an API token
+3. Create playlists and video tours
+
+## Support
+
+- 📧 Email: support@saltfish.ai
+- 🐛 Issues: [GitHub Issues](https://github.com/Saltfish-AB/playlist-player/issues)
+- 📚 Documentation: [docs.saltfish.ai](https://docs.saltfish.ai)
+
+## License
+
+PROPRIETARY - See [LICENSE](./LICENSE) file for details.
+
+## Contributing
+
+We welcome contributions! Please see our [contributing guidelines](https://github.com/Saltfish-AB/playlist-player/blob/main/CONTRIBUTING.md) for details.
+
+---
+
+Made with ❤️ by [Saltfish AB](https://saltfish.ai)