synxed-sdk 0.1.1 → 0.1.3

package/README.md

@@ -7,12 +7,12 @@ The official Synxed SDK for frontend developers to integrate high-quality music
 
 ## Features
 
-- ** Simple Integration**: Play songs or playlists with just a few lines of code.
-- **🎧 High-Fidelity Streaming**: Robust HLS support via `hls.js` for seamless playback across all browsers.
-- **📊 Built-in Analytics**: Automatic session tracking and stream event reporting.
-- **🛠 Framework Agnostic**: Works with React, Vue, Angular, or Vanilla JS.
-- **🔒 Secure**: Designed for private, signed-URL streaming with backend proxy support.
-- **💪 Type Safe**: Fully written in TypeScript with comprehensive definitions.
+- **Simple integration**: Play songs, playlists, or **24/7 live radio** with a few lines of code.
+- **High-fidelity streaming**: Robust HLS support via `hls.js` for seamless playback across browsers (on-demand content).
+- **Built-in analytics**: Session `stream_start` plus automatic **`heartbeat`** intervals from the server `initAck` (including radio, which uses `positionMs: 0`).
+- **Framework-agnostic core**: `SynxedPlayer` works in React, Vue, Angular, or vanilla JS.
+- **Optional web UI**: Vanilla DOM overlay (`SynxedWebPlayer`) with **mini**, **wide**, and **large** layouts — works in any framework; **theme** and **placement** are fully configurable.
+- **Type-safe**: Written in TypeScript with full definitions.
 
 ## Installation
 
@@ -28,100 +28,169 @@ npm install hls.js
 
 ## Quick Start
 
-### Initialize the Player
+### Initialize the player
 
 ```typescript
 import { SynxedPlayer } from "synxed-sdk";
 
 const player = new SynxedPlayer({
   apiKey: "YOUR_SYNXED_API_KEY",
-  serverUrl: "https://api.synxed.com", // or your local backend URL
+  serverUrl: "https://api.synxed.com", // or your backend URL
   autoConnect: true,
 });
 ```
 
-### Play a Playlist
-
-Provide a playlist code generated from the Synxed platform.
+### Play a playlist
 
 ```typescript
-// Start playback from a playlist
 player.playPlaylist({
   playlistCode: "sxpl_VZCCGQAQJV",
 });
 ```
 
-### Play a Single Song
+### Play a single song
 
 ```typescript
-// Play a song from the global catalog
 player.playSong({
   catalogTrackId: "2dcad8e0-3695-4971-9e35-f762f3f9d3a5",
 });
 
-// Or an internal track from your own library
 player.playSong({
   internalTrackId: "track-uuid-here",
 });
 ```
 
-### Control Playback
+### Live radio
+
+Continuous **non-HLS** stream (not seekable). The SDK sends `CONTENT_KIND_RADIO` (`4`) over the same `/sdk` socket; the server returns a direct `playbackUrl` (e.g. MPEG stream).
+
+```typescript
+await player.playRadio({ listenerId: "optional-stable-id" });
+```
+
+- **`skip` / `previous` / `skipTo` / `seek`**: no-ops for radio (the live edge keeps moving on the server).
+- **`pause` / `resume`**: local audio only; when the user resumes, they rejoin the live stream.
+- **Metadata**: poll the REST endpoint (unauthenticated on most deployments):
+
+```typescript
+import { fetchRadioNowPlaying } from "synxed-sdk";
+
+const np = await fetchRadioNowPlaying("https://api.synxed.com");
+// { title, station?, isLive? } — poll every 10–15s for “now playing” UI
+```
+
+### Optional web player UI (vanilla — no React required)
+
+```typescript
+import { SynxedWebPlayer } from "synxed-sdk";
+
+const ui = SynxedWebPlayer.mount({
+  apiKey: "YOUR_SYNXED_API_KEY",
+  serverUrl: "https://api.synxed.com",
+  source: { type: "radio" },
+  mode: "wide",
+  avatarUrl: "/dj.webp",
+  attribution: "DJ Jesse · Synxed × Your Brand",
+  theme: {
+    accent: "#ef4444",
+    glow: "rgba(239, 68, 68, 0.35)",
+    background: "#0a0707",
+  },
+  position: { placement: "top-left", offsetX: 16, offsetY: 16 },
+});
+
+// Later: ui.destroy();
+```
+
+Mount into your own container instead of a fixed overlay:
+
+```typescript
+SynxedWebPlayer.mount({
+  container: document.getElementById("player-slot")!,
+  apiKey: "...",
+  serverUrl: "...",
+  source: { type: "playlist", playlistCode: "sxpl_..." },
+});
+```
+
+**Modes**: `mini` (avatar only), `wide` (pill bar, default), `large` (card + visualizer). Skip controls are hidden for radio.
+
+In React/Vue, create the player in `useEffect` / `onMounted` and call `destroy()` on teardown — same class, no separate React package.
+
+### Playback controls
 
 ```typescript
 player.pause();
 player.resume();
 player.stop();
-player.seek(30000); // Seek to 30 seconds
+player.seek(30000); // on-demand only; no-op for radio
 player.setVolume(0.8);
-player.skip(); // Skip to next track in playlist
+player.skip();
+player.previous();
+player.skipTo(2);
 ```
 
-## Listening for Events
+## Listening for events
 
 ```typescript
-// Track state changes (idle, loading, playing, paused, error)
 player.on("stateChange", (state) => {
   console.log("Player status:", state.status);
 });
 
-// High-resolution time updates (60fps)
 player.on("timeUpdate", ({ currentTime, duration }) => {
   const progress = (currentTime / duration) * 100;
   console.log(`Progress: ${progress.toFixed(2)}%`);
 });
 
-// Error handling
 player.on("error", (err) => {
   console.error("Playback Error:", err.message);
 });
 ```
 
-## API Reference
+## API reference
 
 ### `new SynxedPlayer(config)`
 
-- `apiKey`: `string` (Required) Your developer API key.
-- `serverUrl`: `string` (Required) Your Synxed backend URL.
-- `autoConnect`: `boolean` (Default: `true`) Connect to the streaming socket immediately.
+- `apiKey`: `string` (required)
+- `serverUrl`: `string` (required)
+- `autoConnect`: `boolean` (default `true`)
 
 ### Methods
 
-- `playSong(options)`: `Promise<void>` Plays a single track by `catalogTrackId` or `internalTrackId`.
-- `playPlaylist(options)`: `Promise<void>` Starts playback from a `playlistCode`.
-- `pause()`: `void` Pauses the current stream.
-- `resume()`: `void` Resumes a paused stream.
-- `stop()`: `void` Stops playback and releases audio resources.
-- `skip()`: `void` Skips to the next track in the playlist.
-- `seek(ms)`: `void` Seeks to a specific position in milliseconds.
-- `setVolume(0-1)`: `void` Sets the volume.
-- `destroy()`: `void` Cleans up the player, listeners, and disconnects.
+- `playSong(options)`: `Promise<void>`
+- `playPlaylist(options)`: `Promise<void>`
+- `playRadio(options?)`: `Promise<void>` — live radio (`listenerId` optional)
+- `pause()` / `resume()` / `stop()`
+- `skip()` / `previous()` / `skipTo(index)` — playlist / on-demand only
+- `seek(ms)` — on-demand only (no-op for radio)
+- `setVolume(0–1)`
+- `destroy()`
+
+### Getters
+
+- `currentTrack`: current `TrackInfo | null`
+- `contentKind`: last `play*` kind (`ContentKind` enum, including `RADIO`)
+
+### `fetchRadioNowPlaying(serverUrl, init?)`
+
+`Promise<RadioNowPlaying | null>` — wraps `GET {serverUrl}/radio/now-playing`.
 
 ### Events
 
-- `stateChange`: `(state: PlayerState)` Fired when the engine state changes.
-- `timeUpdate`: `({ currentTime, duration })` Fired during playback.
-- `trackChange`: `(track: any)` Fired when a new track starts playing in a playlist.
-- `error`: `(error: Error)` Fired on playback or connection failures.
+- `stateChange`, `timeUpdate`, `trackChange`, `queueUpdated`, `error`, `connected`, `disconnected`
+
+### `TrackInfo`
+
+```typescript
+interface TrackInfo {
+  id: string;
+  kind: "catalog" | "internal";
+  title?: string;
+  artist?: string;
+  duration?: number;
+  albumArt?: string;
+}
+```
 
 ## License
 

package/dist/index.d.mts

@@ -7,6 +7,23 @@ declare class EventEmitter<Events extends Record<string, any>> {
     removeAllListeners(): void;
 }
 
+declare enum ContentKind {
+    UNSPECIFIED = 0,
+    SONG = 1,
+    PLAYLIST = 2,
+    CATEGORY = 3,
+    RADIO = 4
+}
+declare enum ErrorCode {
+    UNSPECIFIED = 0,
+    UNAUTHORIZED = 1,
+    VALIDATION_ERROR = 2,
+    NOT_FOUND = 3,
+    PROCESSING = 4,
+    SERVICE_UNAVAILABLE = 5,
+    BAD_PROTOBUF = 6
+}
+
 interface SynxedConfig {
     apiKey: string;
     serverUrl: string;
@@ -21,8 +38,18 @@ interface PlayPlaylistOptions {
     playlistCode: string;
     listenerId?: string;
 }
+interface PlayRadioOptions {
+    listenerId?: string;
+}
+/** Response shape from `GET /radio/now-playing` */
+interface RadioNowPlaying {
+    title: string;
+    station?: string;
+    isLive?: boolean;
+}
 interface TrackInfo {
     id: string;
+    kind: "catalog" | "internal";
     title?: string;
     artist?: string;
     duration?: number;
@@ -30,7 +57,7 @@ interface TrackInfo {
 }
 interface PlayerState {
     status: 'idle' | 'loading' | 'playing' | 'paused' | 'error';
-    currentTrack?: TrackInfo;
+    currentTrack: TrackInfo | null;
     currentTime: number;
     duration: number;
     volume: number;
@@ -42,6 +69,7 @@ interface SynxedEvents {
         duration: number;
     }) => void;
     trackChange: (track: TrackInfo) => void;
+    queueUpdated: (tracks: TrackInfo[]) => void;
     error: (error: Error) => void;
     connected: () => void;
     disconnected: (reason: string) => void;
@@ -53,18 +81,31 @@ declare class SynxedPlayer extends EventEmitter<SynxedEvents> {
     private playlist;
     private config;
     private status;
+    private volume;
+    private activeContentKind;
+    private heartbeatTimer;
     constructor(config: SynxedConfig);
+    get currentTrack(): TrackInfo | null;
+    /** Active playback init kind from the last `play*` call (RADIO, PLAYLIST, SONG, …). */
+    get contentKind(): ContentKind;
+    private controlPositionMs;
     private setupListeners;
     private connect;
     playSong(options: PlaySongOptions): Promise<void>;
     playPlaylist(options: PlayPlaylistOptions): Promise<void>;
+    playRadio(options?: PlayRadioOptions): Promise<void>;
     pause(): void;
     resume(): void;
     stop(): void;
     skip(): void;
+    previous(): void;
+    skipTo(index: number): void;
     seek(ms: number): void;
     setVolume(volume: number): void;
+    private positionMsForAnalytics;
     private emitAnalytics;
+    private clearHeartbeat;
+    private startHeartbeat;
     private handleServerMessage;
     private handleTrackEnded;
     private updateStatus;
@@ -85,20 +126,102 @@ declare class SynxedProtocolError extends SynxedError {
     constructor(message: string);
 }
 
-declare enum ContentKind {
-    UNSPECIFIED = 0,
-    SONG = 1,
-    PLAYLIST = 2,
-    CATEGORY = 3
+/**
+ * Fetches live radio "now playing" metadata from the Synxed backend.
+ * Poll every 10–15 seconds to keep UI in sync (see integration docs).
+ */
+declare function fetchRadioNowPlaying(serverUrl: string, init?: RequestInit): Promise<RadioNowPlaying | null>;
+
+type SynxedWebPlayerMode = 'mini' | 'wide' | 'large';
+type SynxedWebPlayerPlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'bottom-center';
+interface SynxedWebPlayerTheme {
+    accent?: string;
+    accentMuted?: string;
+    background?: string;
+    backgroundInner?: string;
+    border?: string;
+    text?: string;
+    textMuted?: string;
+    stationText?: string;
+    liveDot?: string;
+    glow?: string;
 }
-declare enum ErrorCode {
-    UNSPECIFIED = 0,
-    UNAUTHORIZED = 1,
-    VALIDATION_ERROR = 2,
-    NOT_FOUND = 3,
-    PROCESSING = 4,
-    SERVICE_UNAVAILABLE = 5,
-    BAD_PROTOBUF = 6
+interface SynxedWebPlayerPosition {
+    placement?: SynxedWebPlayerPlacement;
+    offsetX?: number;
+    offsetY?: number;
+}
+type SynxedWebPlayerSource = {
+    type: 'playlist';
+    playlistCode: string;
+} | {
+    type: 'radio';
+};
+interface SynxedWebPlayerOptions {
+    /** Mount target. If omitted, a fixed overlay root is appended to `document.body`. */
+    container?: HTMLElement;
+    apiKey: string;
+    serverUrl: string;
+    source: SynxedWebPlayerSource;
+    mode?: SynxedWebPlayerMode;
+    theme?: SynxedWebPlayerTheme;
+    position?: SynxedWebPlayerPosition;
+    avatarUrl?: string;
+    attribution?: string;
+    nowPlayingPollMs?: number;
+    powerByLabel?: string;
+    className?: string;
+    /** Extra inline styles on the outer shell */
+    style?: Partial<CSSStyleDeclaration>;
+    onMiniClick?: () => void;
+}
+
+/**
+ * Framework-agnostic web overlay player (vanilla DOM).
+ * Works in React, Vue, Angular, or plain HTML — no React dependency.
+ */
+declare class SynxedWebPlayer {
+    private readonly options;
+    private readonly root;
+    private readonly ownsRoot;
+    private readonly theme;
+    private engine;
+    private pollTimer;
+    private destroyed;
+    private isPlaying;
+    private currentTrack;
+    private nowPlaying;
+    private avatarRing;
+    private titleEl;
+    private artistInlineEl;
+    private artistBlockEl;
+    private footerEl;
+    private playBtn;
+    constructor(options: SynxedWebPlayerOptions);
+    /** Convenience factory — same as `new SynxedWebPlayer(options)`. */
+    static mount(options: SynxedWebPlayerOptions): SynxedWebPlayer;
+    /** Underlying streaming engine (advanced integrations). */
+    get player(): SynxedPlayer | null;
+    get element(): HTMLElement;
+    destroy(): void;
+    private get isRadio();
+    private get mode();
+    private mountShell;
+    private buildAvatar;
+    private buildMini;
+    private buildWide;
+    private buildLarge;
+    private roundControlStyle;
+    private createPlayButton;
+    private buildVisualizer;
+    private decoLines;
+    private initEngine;
+    private startNowPlayingPoll;
+    private stopNowPlayingPoll;
+    private displayLine;
+    private refreshLabels;
+    private setPlayingVisual;
+    private togglePlay;
 }
 
-export { ContentKind, ErrorCode, type PlayPlaylistOptions, type PlaySongOptions, type PlayerState, type SynxedConfig, SynxedConnectionError, SynxedError, type SynxedEvents, SynxedPlaybackError, SynxedPlayer, SynxedProtocolError, type TrackInfo };
+export { ContentKind, ErrorCode, type PlayPlaylistOptions, type PlayRadioOptions, type PlaySongOptions, type PlayerState, type RadioNowPlaying, type SynxedConfig, SynxedConnectionError, SynxedError, type SynxedEvents, SynxedPlaybackError, SynxedPlayer, SynxedProtocolError, SynxedWebPlayer, type SynxedWebPlayerMode, type SynxedWebPlayerOptions, type SynxedWebPlayerPlacement, type SynxedWebPlayerPosition, type SynxedWebPlayerSource, type SynxedWebPlayerTheme, type TrackInfo, fetchRadioNowPlaying };

package/dist/index.d.ts

@@ -7,6 +7,23 @@ declare class EventEmitter<Events extends Record<string, any>> {
     removeAllListeners(): void;
 }
 
+declare enum ContentKind {
+    UNSPECIFIED = 0,
+    SONG = 1,
+    PLAYLIST = 2,
+    CATEGORY = 3,
+    RADIO = 4
+}
+declare enum ErrorCode {
+    UNSPECIFIED = 0,
+    UNAUTHORIZED = 1,
+    VALIDATION_ERROR = 2,
+    NOT_FOUND = 3,
+    PROCESSING = 4,
+    SERVICE_UNAVAILABLE = 5,
+    BAD_PROTOBUF = 6
+}
+
 interface SynxedConfig {
     apiKey: string;
     serverUrl: string;
@@ -21,8 +38,18 @@ interface PlayPlaylistOptions {
     playlistCode: string;
     listenerId?: string;
 }
+interface PlayRadioOptions {
+    listenerId?: string;
+}
+/** Response shape from `GET /radio/now-playing` */
+interface RadioNowPlaying {
+    title: string;
+    station?: string;
+    isLive?: boolean;
+}
 interface TrackInfo {
     id: string;
+    kind: "catalog" | "internal";
     title?: string;
     artist?: string;
     duration?: number;
@@ -30,7 +57,7 @@ interface TrackInfo {
 }
 interface PlayerState {
     status: 'idle' | 'loading' | 'playing' | 'paused' | 'error';
-    currentTrack?: TrackInfo;
+    currentTrack: TrackInfo | null;
     currentTime: number;
     duration: number;
     volume: number;
@@ -42,6 +69,7 @@ interface SynxedEvents {
         duration: number;
     }) => void;
     trackChange: (track: TrackInfo) => void;
+    queueUpdated: (tracks: TrackInfo[]) => void;
     error: (error: Error) => void;
     connected: () => void;
     disconnected: (reason: string) => void;
@@ -53,18 +81,31 @@ declare class SynxedPlayer extends EventEmitter<SynxedEvents> {
     private playlist;
     private config;
     private status;
+    private volume;
+    private activeContentKind;
+    private heartbeatTimer;
     constructor(config: SynxedConfig);
+    get currentTrack(): TrackInfo | null;
+    /** Active playback init kind from the last `play*` call (RADIO, PLAYLIST, SONG, …). */
+    get contentKind(): ContentKind;
+    private controlPositionMs;
     private setupListeners;
     private connect;
     playSong(options: PlaySongOptions): Promise<void>;
     playPlaylist(options: PlayPlaylistOptions): Promise<void>;
+    playRadio(options?: PlayRadioOptions): Promise<void>;
     pause(): void;
     resume(): void;
     stop(): void;
     skip(): void;
+    previous(): void;
+    skipTo(index: number): void;
     seek(ms: number): void;
     setVolume(volume: number): void;
+    private positionMsForAnalytics;
     private emitAnalytics;
+    private clearHeartbeat;
+    private startHeartbeat;
     private handleServerMessage;
     private handleTrackEnded;
     private updateStatus;
@@ -85,20 +126,102 @@ declare class SynxedProtocolError extends SynxedError {
     constructor(message: string);
 }
 
-declare enum ContentKind {
-    UNSPECIFIED = 0,
-    SONG = 1,
-    PLAYLIST = 2,
-    CATEGORY = 3
+/**
+ * Fetches live radio "now playing" metadata from the Synxed backend.
+ * Poll every 10–15 seconds to keep UI in sync (see integration docs).
+ */
+declare function fetchRadioNowPlaying(serverUrl: string, init?: RequestInit): Promise<RadioNowPlaying | null>;
+
+type SynxedWebPlayerMode = 'mini' | 'wide' | 'large';
+type SynxedWebPlayerPlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'bottom-center';
+interface SynxedWebPlayerTheme {
+    accent?: string;
+    accentMuted?: string;
+    background?: string;
+    backgroundInner?: string;
+    border?: string;
+    text?: string;
+    textMuted?: string;
+    stationText?: string;
+    liveDot?: string;
+    glow?: string;
 }
-declare enum ErrorCode {
-    UNSPECIFIED = 0,
-    UNAUTHORIZED = 1,
-    VALIDATION_ERROR = 2,
-    NOT_FOUND = 3,
-    PROCESSING = 4,
-    SERVICE_UNAVAILABLE = 5,
-    BAD_PROTOBUF = 6
+interface SynxedWebPlayerPosition {
+    placement?: SynxedWebPlayerPlacement;
+    offsetX?: number;
+    offsetY?: number;
+}
+type SynxedWebPlayerSource = {
+    type: 'playlist';
+    playlistCode: string;
+} | {
+    type: 'radio';
+};
+interface SynxedWebPlayerOptions {
+    /** Mount target. If omitted, a fixed overlay root is appended to `document.body`. */
+    container?: HTMLElement;
+    apiKey: string;
+    serverUrl: string;
+    source: SynxedWebPlayerSource;
+    mode?: SynxedWebPlayerMode;
+    theme?: SynxedWebPlayerTheme;
+    position?: SynxedWebPlayerPosition;
+    avatarUrl?: string;
+    attribution?: string;
+    nowPlayingPollMs?: number;
+    powerByLabel?: string;
+    className?: string;
+    /** Extra inline styles on the outer shell */
+    style?: Partial<CSSStyleDeclaration>;
+    onMiniClick?: () => void;
+}
+
+/**
+ * Framework-agnostic web overlay player (vanilla DOM).
+ * Works in React, Vue, Angular, or plain HTML — no React dependency.
+ */
+declare class SynxedWebPlayer {
+    private readonly options;
+    private readonly root;
+    private readonly ownsRoot;
+    private readonly theme;
+    private engine;
+    private pollTimer;
+    private destroyed;
+    private isPlaying;
+    private currentTrack;
+    private nowPlaying;
+    private avatarRing;
+    private titleEl;
+    private artistInlineEl;
+    private artistBlockEl;
+    private footerEl;
+    private playBtn;
+    constructor(options: SynxedWebPlayerOptions);
+    /** Convenience factory — same as `new SynxedWebPlayer(options)`. */
+    static mount(options: SynxedWebPlayerOptions): SynxedWebPlayer;
+    /** Underlying streaming engine (advanced integrations). */
+    get player(): SynxedPlayer | null;
+    get element(): HTMLElement;
+    destroy(): void;
+    private get isRadio();
+    private get mode();
+    private mountShell;
+    private buildAvatar;
+    private buildMini;
+    private buildWide;
+    private buildLarge;
+    private roundControlStyle;
+    private createPlayButton;
+    private buildVisualizer;
+    private decoLines;
+    private initEngine;
+    private startNowPlayingPoll;
+    private stopNowPlayingPoll;
+    private displayLine;
+    private refreshLabels;
+    private setPlayingVisual;
+    private togglePlay;
 }
 
-export { ContentKind, ErrorCode, type PlayPlaylistOptions, type PlaySongOptions, type PlayerState, type SynxedConfig, SynxedConnectionError, SynxedError, type SynxedEvents, SynxedPlaybackError, SynxedPlayer, SynxedProtocolError, type TrackInfo };
+export { ContentKind, ErrorCode, type PlayPlaylistOptions, type PlayRadioOptions, type PlaySongOptions, type PlayerState, type RadioNowPlaying, type SynxedConfig, SynxedConnectionError, SynxedError, type SynxedEvents, SynxedPlaybackError, SynxedPlayer, SynxedProtocolError, SynxedWebPlayer, type SynxedWebPlayerMode, type SynxedWebPlayerOptions, type SynxedWebPlayerPlacement, type SynxedWebPlayerPosition, type SynxedWebPlayerSource, type SynxedWebPlayerTheme, type TrackInfo, fetchRadioNowPlaying };