velora-node-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2025-2026 CrickDevs
+
+All rights reserved.
+
+This software is provided for use only. You may not copy, modify,
+distribute, sublicense, or sell this software without explicit permission.

package/README.md

@@ -0,0 +1,503 @@
+# Velora SDK
+
+Node.js SDK for the Velora local API, providing easy access to the Velora Electron app's playback controls, state queries, and real-time event streaming.
+
+## Features
+
+- **HTTP & WebSocket Support** — Read current track, playback state, and playback queue; control playback (play, pause, skip, seek)
+- **App Registration** — Secure request-based authorization with user consent
+- **Token Management** — Automatic token polling and permission checking
+- **Real-time Events** — Connect to WebSocket for track changes and playback state updates
+- **Auto-reconnection** — Exponential backoff reconnection on WebSocket disconnect
+- **TypeScript Ready** — Full type definitions for all APIs
+- **Error Classification** — Specific error types for easier error handling
+
+## Installation
+
+```bash
+npm install velora-node-sdk
+```
+
+## Quick Start
+
+### 1. Register Your App
+
+```typescript
+import { VeloraClient } from 'velora-node-sdk';
+
+const client = new VeloraClient();
+
+const registrationConfig = {
+  app: {
+    name: 'My awesome app',
+    description: 'An application that is awesome!',
+    developer: 'ItsMeDev',
+    website: 'https://example.com',
+    icon: 'https://example.com/icon.png',
+  },
+  permissions: ['read', 'write'],
+};
+
+const requestId = await client.registerApp(registrationConfig);
+console.log('Registration request ID:', requestId);
+```
+
+### 2. Poll for User Approval
+
+```typescript
+const maxWaitMs = 5 * 60 * 1000;
+await client.requestAccessToken(requestId, maxWaitMs);
+console.log('User approved! Token acquired.');
+```
+
+### 3. Use HTTP Endpoints
+
+```typescript
+const health = await client.getHealth();
+console.log('Velora is running on port:', health.port);
+
+const track = await client.getCurrentTrack();
+console.log(`Now playing: ${track.track.title} by ${track.track.artist}`);
+
+const playbackState = await client.getPlaybackState();
+console.log('Is playing:', playbackState.is_playing);
+
+const queue = await client.getPlaybackQueue();
+console.log('Queue size:', queue.queue.length);
+
+const user = await client.getUserPublic();
+console.log('User:', user.user.name);
+```
+
+### 4. Control Playback
+
+```typescript
+await client.play('OrZoMJcXje2');
+await client.pause();
+await client.next();
+await client.seek(60000);
+await client.toggle();
+```
+
+### 5. Listen to Real-time Events
+
+```typescript
+await client.connectWebSocket();
+
+client.on('track_changed', (data) => {
+  console.log(`Track changed: ${data.title} by ${data.artist}`);
+});
+
+client.on('playback_state_changed', (data) => {
+  console.log('Playing:', data.is_playing);
+});
+
+client.on('ws:connected', () => {
+  console.log('WebSocket connected');
+});
+
+client.on('ws:disconnected', () => {
+  console.log('WebSocket disconnected');
+});
+
+client.on('ws:error', (error) => {
+  console.error('WebSocket error:', error);
+});
+```
+
+## API Reference
+
+### VeloraClient
+
+#### Constructor
+
+```typescript
+new VeloraClient(config?: ClientConfig)
+```
+
+**Options:**
+
+- `host` (string, default: `127.0.0.1`) — Velora server host
+- `port` (number, default: `39031`) — Velora server port
+- `token` (string, optional) — Pre-existing access token
+- `requestedPermissions` (array, optional) — Permissions for pre-existing token
+- `httpOptions` (object, optional) — HTTP client options (timeout, maxRetries)
+- `wsOptions` (object, optional) — WebSocket options
+
+#### Authentication Methods
+
+##### `registerApp(appConfig: RegisterAppRequest): Promise<string>`
+
+Register your app and request permissions. Returns a `request_id` to poll.
+
+```typescript
+const requestId = await client.registerApp({
+  app: {
+    name: 'My App',
+    description: 'Optional description',
+    developer: 'Developer name',
+    website: 'https://example.com',
+    icon: 'https://example.com/icon.png',
+  },
+  permissions: ['read', 'write'],
+});
+```
+
+##### `requestAccessToken(requestId: string, maxWaitMs?: number): Promise<void>`
+
+Poll for user approval. Waits up to `maxWaitMs` (default 5 minutes).
+
+```typescript
+await client.requestAccessToken(requestId);
+```
+
+##### `isAuthenticated(): boolean`
+
+Check if client has a valid token.
+
+```typescript
+if (client.isAuthenticated()) {
+  console.log('Ready to use API');
+}
+```
+
+##### `getToken(): string | null`
+
+Get the current access token.
+
+##### `setToken(token: string, permissions?: PermissionType[]): void`
+
+Manually set a token (e.g., from storage).
+
+```typescript
+client.setToken('velora_...', ['read', 'write']);
+```
+
+##### `clearCredentials(): void`
+
+Clear token and permissions.
+
+```typescript
+client.clearCredentials();
+```
+
+#### Read Endpoints
+
+All read endpoints require `read` permission.
+
+##### `getHealth(): Promise<HealthResponse>`
+
+Check Velora server status.
+
+```typescript
+const health = await client.getHealth();
+```
+
+##### `getCurrentTrack(): Promise<CurrentTrackResponse>`
+
+Get the current playing track.
+
+```typescript
+const response = await client.getCurrentTrack();
+console.log(response.track.title);
+```
+
+##### `getPlaybackState(): Promise<PlaybackStateResponse>`
+
+Get playback flags (is_playing, shuffle, repeat).
+
+```typescript
+const state = await client.getPlaybackState();
+```
+
+##### `getPlaybackQueue(): Promise<PlaybackQueueResponse>`
+
+Get the current playback queue and metadata.
+
+```typescript
+const queue = await client.getPlaybackQueue();
+```
+
+##### `getUserPublic(): Promise<UserPublicResponse>`
+
+Get the signed-in user's public profile snapshot.
+
+```typescript
+const user = await client.getUserPublic();
+```
+
+#### Write Endpoints
+
+All write endpoints require `write` permission.
+
+##### `play(trackId?: string): Promise<PlayResponse>`
+
+Start playback or resume. Optionally specify a track ID.
+
+```typescript
+await client.play();
+await client.play('OrZoMJcXje2');
+```
+
+##### `pause(): Promise<PauseResponse>`
+
+Pause playback.
+
+```typescript
+await client.pause();
+```
+
+##### `next(): Promise<NextResponse>`
+
+Skip to next track.
+
+```typescript
+await client.next();
+```
+
+##### `seek(position: number): Promise<SeekResponse>`
+
+Seek to a position in milliseconds.
+
+```typescript
+await client.seek(60000);
+```
+
+##### `toggle(): Promise<ToggleResponse>`
+
+Toggle between play and pause.
+
+```typescript
+await client.toggle();
+```
+
+#### WebSocket Methods
+
+##### `connectWebSocket(): Promise<void>`
+
+Establish WebSocket connection to receive real-time events.
+
+```typescript
+await client.connectWebSocket();
+```
+
+##### `disconnectWebSocket(): Promise<void>`
+
+Close WebSocket connection.
+
+```typescript
+await client.disconnectWebSocket();
+```
+
+##### `isWSConnected(): boolean`
+
+Check if WebSocket is connected.
+
+```typescript
+if (client.isWSConnected()) {
+  console.log('Receiving real-time updates');
+}
+```
+
+#### WebSocket Events
+
+##### `track_changed`
+
+Emitted when the track changes.
+
+```typescript
+client.on('track_changed', (data: TrackChangedData) => {
+  console.log(data.id, data.title, data.artist);
+});
+```
+
+##### `playback_state_changed`
+
+Emitted when playback state changes.
+
+```typescript
+client.on('playback_state_changed', (data: PlaybackStateChangedData) => {
+  console.log('is_playing:', data.is_playing);
+  console.log('shuffle:', data.shuffle);
+  console.log('repeat:', data.repeat);
+});
+```
+
+##### `ws:connected`
+
+Emitted when WebSocket connects.
+
+```typescript
+client.on('ws:connected', () => {
+  console.log('WebSocket connected');
+});
+```
+
+##### `ws:disconnected`
+
+Emitted when WebSocket disconnects.
+
+```typescript
+client.on('ws:disconnected', () => {
+  console.log('WebSocket disconnected');
+});
+```
+
+##### `ws:connecting`
+
+Emitted before each connection attempt.
+
+```typescript
+client.on('ws:connecting', () => {
+  console.log('Attempting to connect...');
+});
+```
+
+##### `ws:error`
+
+Emitted on WebSocket errors.
+
+```typescript
+client.on('ws:error', (error: Error) => {
+  console.error('WebSocket error:', error.message);
+});
+```
+
+## Error Handling
+
+The SDK provides specific error classes to help identify issues:
+
+```typescript
+import { 
+  VeloraError,
+  AuthError,
+  NetworkError,
+  ValidationError,
+  TimeoutError,
+} from 'velora-node-sdk';
+
+try {
+  await client.getCurrentTrack();
+} catch (error) {
+  if (error instanceof AuthError) {
+    console.error('Permission denied or invalid token');
+  } else if (error instanceof NetworkError) {
+    console.error('Network issue:', error.message);
+  } else if (error instanceof ValidationError) {
+    console.error('Invalid input:', error.message);
+  } else if (error instanceof TimeoutError) {
+    console.error('Request timed out');
+  } else if (error instanceof VeloraError) {
+    console.error('Velora error:', error.message, error.code);
+  }
+}
+```
+
+### Error Classes
+
+- **VeloraError** — Base error class; all Velora errors extend this
+- **AuthError** — Authentication or authorization failure (401/403)
+- **NetworkError** — Network or connection issue
+- **ValidationError** — Invalid input or request body
+- **TimeoutError** — Request timeout
+- **RateLimitError** — Rate limit exceeded (429)
+- **RequestError** — HTTP error (4xx or 5xx)
+
+## Configuration
+
+### HTTP Options
+
+```typescript
+const client = new VeloraClient({
+  httpOptions: {
+    timeout: 30000,
+    maxRetries: 3,
+  },
+});
+```
+
+- `timeout` — Request timeout in milliseconds (default: 30000)
+- `maxRetries` — Max retry attempts for 5xx errors (default: 3)
+
+### WebSocket Options
+
+```typescript
+const client = new VeloraClient({
+  wsOptions: {
+    initialBackoffMs: 1000,
+    maxBackoffMs: 60000,
+  },
+});
+```
+
+- `initialBackoffMs` — Initial reconnect backoff (default: 1000ms)
+- `maxBackoffMs` — Max reconnect backoff (default: 60000ms)
+
+## Connection Lifecycle
+
+### Basic Flow
+
+1. Create client
+2. Register app (or use pre-existing token)
+3. Poll for user approval (if registering)
+4. Call `connect()` to verify health and optionally start WebSocket
+5. Use HTTP or WebSocket APIs
+6. Call `disconnect()` when done
+
+### With Pre-existing Token
+
+```typescript
+const client = new VeloraClient({
+  token: 'velora_...',
+  requestedPermissions: ['read', 'write'],
+});
+
+const track = await client.getCurrentTrack();
+```
+
+### Error Recovery
+
+HTTP client automatically retries on 5xx errors with exponential backoff. WebSocket client auto-reconnects on disconnect with backoff.
+
+```typescript
+client.on('ws:error', (error) => {
+  console.log('Disconnected, will attempt to reconnect...');
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions. All APIs are strictly typed:
+
+```typescript
+import { VeloraClient, CurrentTrackResponse, TrackChangedData } from 'velora-node-sdk';
+
+const client = new VeloraClient();
+
+const response: CurrentTrackResponse = await client.getCurrentTrack();
+
+client.on('track_changed', (data: TrackChangedData) => {
+  console.log(data.title);
+});
+```
+
+## Permissions
+
+- `read` — Access to all GET endpoints and WebSocket
+- `write` — Access to all POST endpoints (play, pause, seek, etc.)
+
+Check permissions at runtime:
+
+```typescript
+if (client.getPermissions().includes('write')) {
+  await client.play();
+}
+```
+
+## Localhost only
+
+The Velora local API only accepts connections from `127.0.0.1` or `::1`. The SDK enforces this at the client level.
+
+## License
+
+MIT

package/dist/auth/CredentialManager.d.ts

@@ -0,0 +1,17 @@
+import { PermissionType, RegisterAppRequest } from '../types';
+export declare class CredentialManager {
+    private token;
+    private permissions;
+    private appName;
+    private baseUrl;
+    constructor(baseUrl: string, initialToken?: string);
+    getToken(): string | null;
+    setToken(token: string, permissions?: PermissionType[]): void;
+    getPermissions(): PermissionType[];
+    hasPermission(permission: PermissionType): boolean;
+    getAuthHeader(): string | null;
+    isAuthenticated(): boolean;
+    clear(): void;
+    register(appConfig: RegisterAppRequest): Promise<string>;
+    requestAccessToken(requestId: string, maxWaitMs?: number): Promise<void>;
+}

package/dist/auth/CredentialManager.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialManager = void 0;
+const errors_1 = require("../types/errors");
+class CredentialManager {
+    constructor(baseUrl, initialToken) {
+        this.permissions = [];
+        this.appName = null;
+        this.baseUrl = baseUrl;
+        this.token = initialToken || null;
+    }
+    getToken() {
+        return this.token;
+    }
+    setToken(token, permissions) {
+        this.token = token;
+        if (permissions) {
+            this.permissions = permissions;
+        }
+    }
+    getPermissions() {
+        return this.permissions;
+    }
+    hasPermission(permission) {
+        return this.permissions.includes(permission);
+    }
+    getAuthHeader() {
+        if (!this.token)
+            return null;
+        return `Bearer ${this.token}`;
+    }
+    isAuthenticated() {
+        return this.token !== null && this.token.length > 0;
+    }
+    clear() {
+        this.token = null;
+        this.permissions = [];
+        this.appName = null;
+    }
+    async register(appConfig) {
+        if (!appConfig.app.name) {
+            throw new errors_1.ValidationError('app.name is required', 'app.name');
+        }
+        const payload = {
+            app: {
+                name: appConfig.app.name,
+                ...(appConfig.app.description && { description: appConfig.app.description }),
+                ...(appConfig.app.developer && { developer: appConfig.app.developer }),
+                ...(appConfig.app.website && { website: appConfig.app.website }),
+                ...(appConfig.app.icon && { icon: appConfig.app.icon }),
+            },
+            permissions: appConfig.permissions || ['read'],
+        };
+        this.appName = appConfig.app.name;
+        try {
+            const response = await fetch(`${this.baseUrl}/register`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                let errorMsg = body;
+                try {
+                    const errorJson = JSON.parse(body);
+                    errorMsg = errorJson.error || body;
+                }
+                catch { }
+                throw new errors_1.RequestError(`Registration failed: ${errorMsg}`, response.status);
+            }
+            const data = await response.json();
+            return data.request_id;
+        }
+        catch (error) {
+            if (error instanceof errors_1.RequestError)
+                throw error;
+            throw new errors_1.RequestError(error instanceof Error ? error.message : 'Registration failed', 0);
+        }
+    }
+    async requestAccessToken(requestId, maxWaitMs = 300000) {
+        if (!requestId) {
+            throw new errors_1.ValidationError('request_id is required', 'request_id');
+        }
+        const startTime = Date.now();
+        const pollIntervalMs = 1000;
+        while (Date.now() - startTime < maxWaitMs) {
+            try {
+                const response = await fetch(`${this.baseUrl}/request-status?request_id=${encodeURIComponent(requestId)}`);
+                if (!response.ok) {
+                    throw new errors_1.RequestError(`Request status failed`, response.status);
+                }
+                const data = await response.json();
+                if (data.status === 'approved') {
+                    const approvedData = data;
+                    this.token = approvedData.access_token;
+                    this.permissions = approvedData.permissions;
+                    return;
+                }
+                if (data.status === 'denied') {
+                    throw new errors_1.AuthError('Registration request was denied');
+                }
+                await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+            }
+            catch (error) {
+                if (error instanceof (errors_1.ValidationError || errors_1.AuthError || errors_1.RequestError)) {
+                    throw error;
+                }
+                throw new errors_1.RequestError(error instanceof Error ? error.message : 'Failed to get access token', 0);
+            }
+        }
+        throw new errors_1.RequestError('Request access token timeout', 0);
+    }
+}
+exports.CredentialManager = CredentialManager;

package/dist/auth/index.d.ts

@@ -0,0 +1 @@
+export { CredentialManager } from './CredentialManager';

package/dist/auth/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialManager = void 0;
+var CredentialManager_1 = require("./CredentialManager");
+Object.defineProperty(exports, "CredentialManager", { enumerable: true, get: function () { return CredentialManager_1.CredentialManager; } });

package/dist/client/VeloraClient.d.ts

@@ -0,0 +1,32 @@
+import { ClientConfig, RegisterAppRequest, HealthResponse, CurrentTrackResponse, PlaybackStateResponse, PlaybackQueueResponse, UserPublicResponse, PlayResponse, PauseResponse, NextResponse, SeekResponse, ToggleResponse } from '../types';
+import { EventEmitter } from 'events';
+export declare class VeloraClient extends EventEmitter {
+    private credentialManager;
+    private httpClient;
+    private wsClient;
+    private baseUrl;
+    private wsBaseUrl;
+    constructor(config?: ClientConfig);
+    isAuthenticated(): boolean;
+    registerApp(appConfig: RegisterAppRequest): Promise<string>;
+    requestAccessToken(requestId: string, maxWaitMs?: number): Promise<void>;
+    getHealth(): Promise<HealthResponse>;
+    getCurrentTrack(): Promise<CurrentTrackResponse>;
+    getPlaybackState(): Promise<PlaybackStateResponse>;
+    getPlaybackQueue(): Promise<PlaybackQueueResponse>;
+    getUserPublic(): Promise<UserPublicResponse>;
+    play(trackId?: string): Promise<PlayResponse>;
+    pause(): Promise<PauseResponse>;
+    next(): Promise<NextResponse>;
+    seek(position: number): Promise<SeekResponse>;
+    toggle(): Promise<ToggleResponse>;
+    connectWebSocket(): Promise<void>;
+    disconnectWebSocket(): Promise<void>;
+    isWSConnected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    clearCredentials(): void;
+    getToken(): string | null;
+    setToken(token: string, permissions?: ('read' | 'write')[]): void;
+    getPermissions(): ('read' | 'write')[];
+}