@redseat/api 0.0.1

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name": "@redseat/api",
+    "version": "0.0.1",
+    "description": "TypeScript API client library for interacting with Redseat servers",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "files": [
+        "dist/**/*",
+        "README.md",
+        "*.md"
+    ],
+    "keywords": [
+        "redseat",
+        "api",
+        "client",
+        "typescript"
+    ],
+    "author": "Arnaud JEZEQUEL <arnaud.jezequel@gmail.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/yourusername/redseat-svelte.git",
+        "directory": "packages/api"
+    },
+    "scripts": {
+        "build": "tsc",
+        "test": "vitest run",
+        "test:watch": "vitest"
+    },
+    "dependencies": {
+        "axios": "^1.11.0",
+        "rxjs": "^7.8.2"
+    },
+    "devDependencies": {
+        "typescript": "^5.8.3",
+        "vite": "^7.3.0",
+        "vitest": "^4.0.16"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/server.md

@@ -0,0 +1,196 @@
+# ServerApi
+
+The `ServerApi` class provides server-level operations for managing libraries, settings, plugins, and credentials.
+
+## Overview
+
+`ServerApi` handles operations that are not specific to a single library, such as:
+- Listing and creating libraries
+- Getting current user information
+- Managing server settings
+- Listing plugins and credentials
+- Adding credentials to libraries
+
+## Constructor
+
+```typescript
+new ServerApi(client: RedseatClient)
+```
+
+**Parameters:**
+- `client`: An initialized `RedseatClient` instance
+
+**Example:**
+```typescript
+import { RedseatClient, ServerApi } from '@redseat/api';
+
+const client = new RedseatClient({ /* ... */ });
+const serverApi = new ServerApi(client);
+```
+
+## Methods
+
+### `getLibraries(): Promise<ILibrary[]>`
+
+Retrieves all libraries available to the current user.
+
+**Returns:** Promise resolving to an array of `ILibrary` objects
+
+**Example:**
+```typescript
+const libraries = await serverApi.getLibraries();
+libraries.forEach(library => {
+    console.log(`Library: ${library.name} (${library.type})`);
+});
+```
+
+### `getMe(): Promise<any>`
+
+Gets information about the current authenticated user.
+
+**Returns:** Promise resolving to user information object
+
+**Example:**
+```typescript
+const user = await serverApi.getMe();
+console.log(`Logged in as: ${user.name}`);
+```
+
+### `addLibrary(library: Partial<ILibrary>): Promise<ILibrary>`
+
+Creates a new library.
+
+**Parameters:**
+- `library`: Partial library object with required fields:
+  - `name`: Library name (required)
+  - `type`: Library type - `'photos'`, `'shows'`, `'movies'`, or `'iptv'` (required)
+  - `source`: Optional source type
+  - `crypt`: Optional boolean to enable encryption
+  - `hidden`: Optional boolean to hide library
+
+**Returns:** Promise resolving to the created `ILibrary` object with generated `id`
+
+**Example:**
+```typescript
+const newLibrary = await serverApi.addLibrary({
+    name: 'My Photos',
+    type: 'photos',
+    crypt: true // Enable encryption
+});
+console.log(`Created library with ID: ${newLibrary.id}`);
+```
+
+### `getSetting(key: string): Promise<string>`
+
+Retrieves a server setting value by key.
+
+**Parameters:**
+- `key`: The setting key to retrieve
+
+**Returns:** Promise resolving to the setting value as a string
+
+**Example:**
+```typescript
+const maxUploadSize = await serverApi.getSetting('max_upload_size');
+console.log(`Max upload size: ${maxUploadSize}`);
+```
+
+### `getPlugins(): Promise<any[]>`
+
+Retrieves all available plugins on the server.
+
+**Returns:** Promise resolving to an array of plugin objects
+
+**Example:**
+```typescript
+const plugins = await serverApi.getPlugins();
+plugins.forEach(plugin => {
+    console.log(`Plugin: ${plugin.name} - ${plugin.description}`);
+});
+```
+
+### `getCredentials(): Promise<any[]>`
+
+Retrieves all available credentials configured on the server.
+
+**Returns:** Promise resolving to an array of credential objects
+
+**Example:**
+```typescript
+const credentials = await serverApi.getCredentials();
+credentials.forEach(cred => {
+    console.log(`Credential: ${cred.name} (${cred.type})`);
+});
+```
+
+### `addLibraryCredential(credential: any): Promise<ILibrary>`
+
+Adds a credential to a library. This is used to configure external service access for libraries.
+
+**Parameters:**
+- `credential`: Credential configuration object (structure depends on credential type)
+
+**Returns:** Promise resolving to the updated `ILibrary` object
+
+**Example:**
+```typescript
+const library = await serverApi.addLibraryCredential({
+    libraryId: 'library-123',
+    credentialId: 'credential-456',
+    // Additional credential-specific configuration
+});
+```
+
+## Usage Examples
+
+### Complete Workflow: Create Library and Get Info
+
+```typescript
+import { RedseatClient, ServerApi } from '@redseat/api';
+
+// Initialize
+const client = new RedseatClient({ /* ... */ });
+const serverApi = new ServerApi(client);
+
+// Get current user
+const user = await serverApi.getMe();
+console.log(`User: ${user.name}`);
+
+// List existing libraries
+const libraries = await serverApi.getLibraries();
+console.log(`Found ${libraries.length} libraries`);
+
+// Create a new encrypted photo library
+const newLibrary = await serverApi.addLibrary({
+    name: 'Encrypted Photos',
+    type: 'photos',
+    crypt: true
+});
+
+// Get server settings
+const maxUpload = await serverApi.getSetting('max_upload_size');
+console.log(`Max upload size: ${maxUpload}`);
+```
+
+### Error Handling
+
+```typescript
+try {
+    const libraries = await serverApi.getLibraries();
+} catch (error) {
+    if (error.response?.status === 401) {
+        console.error('Authentication failed');
+    } else if (error.response?.status === 403) {
+        console.error('Insufficient permissions');
+    } else {
+        console.error('Failed to get libraries:', error.message);
+    }
+}
+```
+
+## Related Documentation
+
+- [RedseatClient Documentation](client.md) - HTTP client used by ServerApi
+- [LibraryApi Documentation](libraries.md) - Library-specific operations
+- [README](README.md) - Package overview
+

package/test.md

@@ -0,0 +1,291 @@
+# Testing Guide
+
+This document describes how to run tests for the `@redseat/api` package and what each test file covers.
+
+## Running Tests
+
+### Run All Tests
+
+```bash
+npm test
+```
+
+This runs all tests once and exits.
+
+### Run Tests in Watch Mode
+
+```bash
+npm run test:watch
+```
+
+This runs tests in watch mode, automatically re-running tests when files change.
+
+### Run Specific Test File
+
+```bash
+npx vitest run src/encryption.test.ts
+```
+
+### Run Tests with Coverage
+
+```bash
+npx vitest run --coverage
+```
+
+## Test Framework
+
+The package uses [Vitest](https://vitest.dev/) as the test framework. Vitest is a fast unit test framework powered by Vite, designed to be compatible with Jest.
+
+### Configuration
+
+Test configuration is in `vitest.config.ts`:
+- Environment: Node.js
+- Globals: Enabled (no need to import `describe`, `it`, `expect`)
+
+## Test Files
+
+### `src/encryption.test.ts`
+
+Tests for the encryption module (`src/encryption.ts`).
+
+**What it tests:**
+- **Key Derivation (`deriveKey`)**
+  - Derives text keys from passphrases
+  - Derives file keys from passphrases
+  - Verifies text and file keys are different (different salts)
+  - Verifies same passphrase produces same key
+
+- **IV Generation (`getRandomIV`)**
+  - Generates 16-byte IVs
+  - Generates different IVs on each call
+
+- **Text Encryption/Decryption (`encryptText` / `decryptText`)**
+  - Encrypts and decrypts text correctly
+  - Produces different encrypted output for same text (due to random IV)
+  - Handles empty strings
+  - Handles special characters and unicode
+  - Verifies encrypted format: `${IV}.${encryptedData}` (base64url)
+
+- **Buffer Encryption/Decryption (`encryptBuffer` / `decryptBuffer`)**
+  - Encrypts and decrypts binary data correctly
+  - Requires correct IV for decryption
+  - Handles empty buffers
+  - Handles large buffers
+
+- **File Encryption (`encryptFile`)**
+  - Encrypts files with thumbnails
+  - Encrypts files without thumbnails
+  - Includes correct MIME types in encrypted structure
+  - Returns correct IV and thumbnail size
+
+- **File Decryption (`decryptFile` / `decryptFileThumb`)**
+  - Decrypts file data from encrypted structure
+  - Decrypts thumbnail data from encrypted structure
+  - Handles files without thumbnails
+  - Verifies file format structure (IV, sizes, MIME types, data)
+
+- **Filename Encryption (`encryptFilename`)**
+  - Encrypts filenames with given IV
+  - Returns base64url encoded encrypted filename
+
+- **Endianness Compatibility**
+  - Handles both big-endian and little-endian size fields
+  - Backward compatibility with old file formats
+
+**Example test:**
+```typescript
+it('should encrypt and decrypt text correctly', async () => {
+    const key = await deriveKey('password', 'text');
+    const encrypted = await encryptText(key, 'Hello World');
+    const decrypted = await decryptText(key, encrypted);
+    expect(decrypted).toBe('Hello World');
+});
+```
+
+---
+
+### `src/crypto.test.ts`
+
+Tests for crypto utility functions (`src/crypto.ts`).
+
+**What it tests:**
+- **Platform Detection (`getCryptoSubtle` / `getCryptoRandomValues`)**
+  - Returns SubtleCrypto instance
+  - Returns random number generator function
+  - Works in Node.js environment
+
+- **Base64 Encoding/Decoding**
+  - `uint8ArrayFromBase64`: Converts base64 to Uint8Array
+  - `uint8ArrayFromBase64Url`: Converts base64url to Uint8Array
+  - `arrayBufferToBase64`: Converts ArrayBuffer to base64
+  - Handles padding correctly
+  - Handles base64url format (dashes and underscores)
+
+- **Base64 URL Conversion**
+  - `base64ToBase64Url`: Converts standard base64 to base64url
+  - `base64UrlToBase64`: Converts base64url to standard base64
+  - Handles character substitution (`+`/`-`, `/`/`_`)
+  - Handles padding removal/addition
+
+- **String Padding (`padRight`)**
+  - Pads strings to specified length
+  - Handles strings longer than target length
+  - Handles empty strings
+  - Uses correct padding character
+
+**Example test:**
+```typescript
+it('should convert base64 string to Uint8Array', () => {
+    const base64 = 'SGVsbG8gV29ybGQ='; // "Hello World"
+    const result = uint8ArrayFromBase64(base64);
+    expect(result).toBeInstanceOf(Uint8Array);
+    expect(String.fromCharCode(...result)).toBe('Hello World');
+});
+```
+
+---
+
+### `src/library-upload.test.ts`
+
+Tests for `LibraryApi.uploadMedia()` method.
+
+**What it tests:**
+- **Encrypted Library Uploads**
+  - Throws error if encryption key is not set
+  - Encrypts data when key is set via `setKey()`
+  - Encrypts filename using text encryption
+  - Includes IV and thumbnail size in metadata
+  - Handles thumbnail encryption
+  - Validates thumbnail can only be specified for encrypted libraries
+
+- **Non-Encrypted Library Uploads**
+  - Uploads without encryption
+  - Uses original filename
+  - Does not require encryption key
+
+- **Input Validation**
+  - Handles ArrayBuffer input
+  - Handles Uint8Array input
+  - Normalizes different buffer types correctly
+  - Validates metadata structure
+
+- **FormData Structure**
+  - Creates FormData with correct structure
+  - Info field is first, file field is last
+  - Includes correct metadata in info field
+  - Uses correct filename in file field
+
+- **Progress Callback**
+  - Calls progress callback during upload
+  - Provides correct loaded/total values
+
+- **Error Handling**
+  - Throws appropriate errors for missing keys
+  - Throws errors for invalid configurations
+  - Handles network errors gracefully
+
+**Example test:**
+```typescript
+it('should throw error if key is not set', async () => {
+    libraryApi = new LibraryApi(client, 'lib1', encryptedLibrary);
+    await expect(
+        libraryApi.uploadMedia(data, {
+            metadata: {},
+            fileMime: 'image/jpeg'
+        })
+    ).rejects.toThrow('Encryption key not set');
+});
+```
+
+---
+
+## Test Structure
+
+All test files follow this structure:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { /* functions to test */ } from './module';
+
+describe('Module Name', () => {
+    describe('Function Group', () => {
+        it('should do something', () => {
+            // Test implementation
+        });
+    });
+});
+```
+
+## Writing New Tests
+
+When adding new functionality:
+
+1. **Add tests to existing file** if testing existing module
+2. **Create new test file** if testing new module (follow naming: `module-name.test.ts`)
+3. **Test both success and error cases**
+4. **Test edge cases** (empty inputs, null values, etc.)
+5. **Use descriptive test names** that explain what is being tested
+
+### Example: Adding Test for New Function
+
+```typescript
+// In appropriate test file
+describe('newFunction', () => {
+    it('should handle normal case', () => {
+        const result = newFunction('input');
+        expect(result).toBe('expected');
+    });
+
+    it('should handle edge case', () => {
+        const result = newFunction('');
+        expect(result).toBe('');
+    });
+
+    it('should throw error for invalid input', () => {
+        expect(() => newFunction(null)).toThrow();
+    });
+});
+```
+
+## Continuous Integration
+
+Tests should be run:
+- Before committing code
+- In CI/CD pipeline
+- Before releasing new versions
+
+## Coverage Goals
+
+Aim for:
+- **High coverage** on core functionality (encryption, API methods)
+- **Edge case coverage** for error handling
+- **Integration tests** for complex workflows
+
+## Debugging Tests
+
+### Run Single Test
+
+```bash
+npx vitest run -t "test name"
+```
+
+### Debug Mode
+
+```bash
+node --inspect-brk node_modules/.bin/vitest run
+```
+
+Then attach debugger in VS Code or Chrome DevTools.
+
+### Verbose Output
+
+```bash
+npx vitest run --reporter=verbose
+```
+
+## Related Documentation
+
+- [Vitest Documentation](https://vitest.dev/)
+- [Encryption Documentation](encryption.md) - Details on encryption functions being tested
+- [README](README.md) - Package overview
+