@redseat/api 0.0.1

package/README.md

@@ -0,0 +1,132 @@
+# @redseat/api
+
+TypeScript API client library for interacting with Redseat servers. This package provides a comprehensive set of APIs for managing libraries, media, tags, people, series, movies, and more.
+
+## Overview
+
+The `@redseat/api` package is organized into three main API classes:
+
+- **RedseatClient**: Low-level HTTP client with automatic token management and local server detection
+- **ServerApi**: Server-level operations (libraries, settings, plugins, credentials)
+- **LibraryApi**: Library-specific operations (media, tags, people, series, movies, encryption)
+
+## Quick Start
+
+```typescript
+import { RedseatClient, ServerApi, LibraryApi } from '@redseat/api';
+import { IServer, ILibrary } from '@redseat/api';
+
+// Initialize the client
+const client = new RedseatClient({
+    server: {
+        id: 'server-id',
+        url: 'example.com',
+        port: 443
+    },
+    getIdToken: async () => {
+        // Return your ID token from your auth provider
+        return 'your-id-token';
+    }
+});
+
+// Get server API
+const serverApi = new ServerApi(client);
+
+// Get libraries
+const libraries = await serverApi.getLibraries();
+
+// Get library API for a specific library
+const library = libraries[0];
+const libraryApi = new LibraryApi(client, library.id!, library);
+
+// For encrypted libraries, set the encryption key
+if (library.crypt) {
+    await libraryApi.setKey('your-passphrase');
+}
+
+// Get media
+const medias = await libraryApi.getMedias();
+```
+
+## Documentation
+
+- **[client.md](client.md)** - RedseatClient documentation
+  - HTTP client configuration
+  - Automatic token refresh
+  - Local server detection
+  - Request/response interceptors
+
+- **[server.md](server.md)** - ServerApi documentation
+  - Server-level operations
+  - Library management
+  - Settings and plugins
+  - Credentials management
+
+- **[libraries.md](libraries.md)** - LibraryApi documentation
+  - Media operations (upload, download, update)
+  - Tags, people, series, movies management
+  - Face recognition operations
+  - Encryption support for encrypted libraries
+
+- **[encryption.md](encryption.md)** - Encryption module documentation
+  - Key derivation (PBKDF2)
+  - Text and binary encryption/decryption
+  - File encryption with thumbnails
+  - Cross-platform compatibility
+
+- **[test.md](test.md)** - Testing guide
+  - How to run tests
+  - Test file descriptions
+  - Test coverage information
+
+- **[agents.md](agents.md)** - AI agent instructions
+  - Documentation maintenance guidelines
+  - Code change workflow
+  - Best practices for keeping docs updated
+
+## Package Exports
+
+### Classes
+- `RedseatClient` - HTTP client with authentication
+- `ServerApi` - Server-level API operations
+- `LibraryApi` - Library-level API operations
+
+### Interfaces
+- `IFile` - Media file interface
+- `ILibrary` - Library interface
+- `ITag` - Tag interface
+- `IPerson` - Person interface
+- `ISerie` - Series interface
+- `IMovie` - Movie interface
+- `IServer` - Server interface
+- `MediaRequest` - Media query filter
+- And more (see `src/interfaces.ts`)
+
+### Encryption Functions
+- `deriveKey()` - Derive encryption key from passphrase
+- `encryptText()` / `decryptText()` - Text encryption
+- `encryptBuffer()` / `decryptBuffer()` - Binary encryption
+- `encryptFile()` / `decryptFile()` - File encryption with metadata
+- `getRandomIV()` - Generate random IV
+
+### Utilities
+- `fetchServerToken()` - Fetch server authentication token
+- Base64 encoding/decoding utilities
+- Crypto utilities for cross-platform support
+
+## Installation
+
+```bash
+npm install @redseat/api
+```
+
+## Requirements
+
+- Node.js 15+ (for Web Crypto API support)
+- TypeScript 5.0+
+- Axios 1.11.0+
+
+## License
+
+See the main project LICENSE file.
+

package/agents.md

@@ -0,0 +1,275 @@
+# AI Agent Instructions
+
+This document provides guidelines for AI agents working with the `@redseat/api` package. Follow these instructions to maintain code quality and keep documentation up to date.
+
+## Getting Started
+
+### Always Read First
+
+1. **Start with [README.md](README.md)**
+   - Understand the package structure
+   - Identify which API classes are relevant to your task
+   - Find links to specialized documentation
+
+2. **Read Relevant Documentation**
+   - [client.md](client.md) - For HTTP client changes
+   - [server.md](server.md) - For server API changes
+   - [libraries.md](libraries.md) - For library API changes
+   - [encryption.md](encryption.md) - For encryption module changes
+   - [test.md](test.md) - For testing changes
+
+3. **Examine Source Code**
+   - Read the actual implementation files in `src/`
+   - Understand the current architecture
+   - Check existing patterns and conventions
+
+## Documentation Maintenance
+
+### When Modifying Existing Functionality
+
+**Required Actions:**
+
+1. **Update the Relevant Documentation File**
+   - If changing `RedseatClient`: Update [client.md](client.md)
+   - If changing `ServerApi`: Update [server.md](server.md)
+   - If changing `LibraryApi`: Update [libraries.md](libraries.md)
+   - If changing encryption: Update [encryption.md](encryption.md)
+
+2. **Update Method Signatures**
+   - Document new parameters
+   - Document changed return types
+   - Document new error cases
+   - Update examples if behavior changed
+
+3. **Update README.md if Needed**
+   - If API signatures changed significantly
+   - If new major features were added
+   - If package exports changed
+
+4. **Keep Examples Current**
+   - Update code examples to reflect new behavior
+   - Ensure examples are runnable
+   - Fix broken examples
+
+**Example Workflow:**
+```
+1. User requests: "Add timeout parameter to getMedia()"
+2. Read libraries.md to see current getMedia() documentation
+3. Modify src/library.ts to add timeout parameter
+4. Update libraries.md with new parameter documentation
+5. Update example code in libraries.md
+6. Check if README.md needs updates (probably not for this change)
+```
+
+### When Adding New Functionality
+
+**Required Actions:**
+
+1. **Document in Appropriate File**
+   - Add new methods to the relevant documentation file
+   - Follow existing formatting and structure
+   - Include parameters, return types, and examples
+
+2. **Update README.md**
+   - Add to package exports list if it's a new public export
+   - Update overview if it's a major feature
+   - Add to quick start if it's commonly used
+
+3. **Include Usage Examples**
+   - Provide at least one example per new method
+   - Show common use cases
+   - Include error handling examples
+
+4. **Update Related Documentation**
+   - If adding new encryption function: Update [encryption.md](encryption.md)
+   - If adding new test: Update [test.md](test.md)
+   - Cross-reference related functionality
+
+**Example Workflow:**
+```
+1. User requests: "Add getMediaStats() method to LibraryApi"
+2. Implement method in src/library.ts
+3. Add documentation to libraries.md in "Media" section
+4. Add example showing usage
+5. Update README.md exports if needed
+6. Add test and update test.md if applicable
+```
+
+## Code Change Workflow
+
+### Before Making Changes
+
+1. **Understand the Request**
+   - What functionality is being added/modified?
+   - Which files are affected?
+   - Are there breaking changes?
+
+2. **Plan the Changes**
+   - Identify all files that need modification
+   - Identify all documentation that needs updates
+   - Consider backward compatibility
+
+3. **Check Dependencies**
+   - Will this change affect other parts of the codebase?
+   - Are there tests that need updating?
+   - Are there examples that need updating?
+
+### During Implementation
+
+1. **Follow Existing Patterns**
+   - Match code style and conventions
+   - Use similar error handling
+   - Follow naming conventions
+
+2. **Write Tests**
+   - Add tests for new functionality
+   - Update tests for modified functionality
+   - Ensure tests pass
+
+3. **Update Documentation As You Go**
+   - Don't wait until the end
+   - Update docs as you implement
+   - This helps catch documentation issues early
+
+### After Implementation
+
+1. **Verify Documentation**
+   - Read through your documentation changes
+   - Ensure examples are correct
+   - Check for typos and formatting
+
+2. **Check Cross-References**
+   - Update links if files moved
+   - Update related documentation
+   - Ensure consistency across files
+
+3. **Test Examples**
+   - Verify code examples are syntactically correct
+   - Ensure examples demonstrate the feature correctly
+   - Check that examples use current API
+
+## Documentation Standards
+
+### Formatting
+
+- Use consistent markdown formatting
+- Use code blocks with language tags for code examples
+- Use proper heading hierarchy (## for sections, ### for subsections)
+- Include parameter tables for complex methods
+
+### Code Examples
+
+- Always include TypeScript type annotations
+- Show both success and error cases when relevant
+- Include imports when showing complete examples
+- Use realistic variable names
+
+### Method Documentation Template
+
+```markdown
+### `methodName(param1: Type1, param2: Type2): Promise<ReturnType>`
+
+Brief description of what the method does.
+
+**Parameters:**
+- `param1`: Description of parameter
+- `param2`: Description of parameter
+
+**Returns:** Promise resolving to description
+
+**Example:**
+\`\`\`typescript
+const result = await libraryApi.methodName('value1', 'value2');
+\`\`\`
+```
+
+## Common Scenarios
+
+### Scenario 1: Adding a New Method to LibraryApi
+
+1. Implement method in `src/library.ts`
+2. Add documentation to [libraries.md](libraries.md) in appropriate section
+3. Add example code
+4. Add test to appropriate test file
+5. Update [test.md](test.md) if new test file created
+6. Check if [README.md](README.md) needs updates
+
+### Scenario 2: Modifying Encryption Function
+
+1. Modify function in `src/encryption.ts`
+2. Update [encryption.md](encryption.md) with changes
+3. Update examples if behavior changed
+4. Update tests in `src/encryption.test.ts`
+5. Check if [libraries.md](libraries.md) needs updates (if LibraryApi uses it)
+
+### Scenario 3: Adding New Export
+
+1. Add export to `src/index.ts`
+2. Update [README.md](README.md) package exports section
+3. Add documentation to appropriate file
+4. Add example in README or relevant doc file
+
+### Scenario 4: Breaking Change
+
+1. Document breaking change clearly
+2. Update all affected documentation
+3. Update examples to show new usage
+4. Consider migration guide if significant
+
+## Quality Checklist
+
+Before completing a task, verify:
+
+- [ ] All code changes are implemented
+- [ ] All relevant documentation is updated
+- [ ] Examples are current and correct
+- [ ] Tests are added/updated
+- [ ] README.md is updated if needed
+- [ ] Cross-references are correct
+- [ ] No broken links
+- [ ] Code follows existing patterns
+- [ ] Documentation is clear and complete
+
+## Error Prevention
+
+### Common Mistakes to Avoid
+
+1. **Forgetting to Update Documentation**
+   - Always update docs when code changes
+   - Don't assume someone else will do it
+
+2. **Outdated Examples**
+   - Verify examples still work
+   - Update examples when API changes
+
+3. **Inconsistent Formatting**
+   - Follow existing documentation style
+   - Use consistent code formatting
+
+4. **Missing Error Cases**
+   - Document when methods throw errors
+   - Show error handling in examples
+
+5. **Incomplete Documentation**
+   - Document all parameters
+   - Document return types
+   - Include usage examples
+
+## Questions?
+
+If you're unsure about:
+- Which documentation file to update
+- How to format documentation
+- Whether a change needs documentation
+
+**Default Action:** Update the documentation. It's better to have slightly redundant documentation than missing documentation.
+
+## Related Documentation
+
+- [README.md](README.md) - Start here for package overview
+- [client.md](client.md) - RedseatClient documentation
+- [server.md](server.md) - ServerApi documentation
+- [libraries.md](libraries.md) - LibraryApi documentation
+- [encryption.md](encryption.md) - Encryption module documentation
+- [test.md](test.md) - Testing guide
+

package/client.md

@@ -0,0 +1,288 @@
+# RedseatClient
+
+The `RedseatClient` class is the low-level HTTP client that handles all communication with Redseat servers. It provides automatic token management, local server detection, and request/response interceptors.
+
+## Overview
+
+`RedseatClient` wraps Axios and adds:
+- Automatic token refresh before expiration
+- Local server detection (for development)
+- 401 error handling with automatic retry
+- Request/response interceptors for authentication
+
+## Constructor
+
+```typescript
+new RedseatClient(options: ClientOptions)
+```
+
+### ClientOptions Interface
+
+```typescript
+interface ClientOptions {
+    server: IServer;
+    getIdToken: () => Promise<string>;
+    refreshThreshold?: number; // milliseconds before expiration to refresh (default: 5 minutes)
+}
+```
+
+**Parameters:**
+- `server`: Server configuration object with `id`, `url`, and optional `port`
+- `getIdToken`: Async function that returns the current ID token from your auth provider
+- `refreshThreshold`: Optional. Milliseconds before token expiration to trigger refresh (default: 300000 = 5 minutes)
+
+**Example:**
+```typescript
+const client = new RedseatClient({
+    server: {
+        id: 'server-123',
+        url: 'example.com',
+        port: 443
+    },
+    getIdToken: async () => {
+        // Get ID token from your auth provider (Firebase, Auth0, etc.)
+        return await getCurrentUserToken();
+    },
+    refreshThreshold: 5 * 60 * 1000 // 5 minutes
+});
+```
+
+## Features
+
+### Automatic Token Refresh
+
+The client automatically refreshes tokens before they expire. The refresh happens:
+- Before each request if the token is expired or expiring soon
+- When a 401 error is received (with automatic retry)
+
+### Local Server Detection
+
+The client automatically detects if a local development server is available by checking `local.{server.url}`. If detected, it uses the local URL instead of the production URL.
+
+### Request Interceptor
+
+All requests are intercepted to:
+1. Check if token needs refresh
+2. Add `Authorization: Bearer {token}` header
+
+### Response Interceptor
+
+All responses are intercepted to:
+1. Handle 401 errors by refreshing token and retrying the request
+2. Prevent infinite retry loops with `_retry` flag
+
+## Methods
+
+### `get<T>(url: string, config?: AxiosRequestConfig)`
+
+Performs a GET request.
+
+**Parameters:**
+- `url`: The endpoint URL (relative to base URL)
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.get<IFile[]>('/libraries/123/medias');
+const medias = response.data;
+```
+
+### `post<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a POST request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.post<ITag>('/libraries/123/tags', {
+    name: 'Vacation'
+});
+const tag = response.data;
+```
+
+### `put<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a PUT request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const formData = new FormData();
+formData.append('file', fileBlob);
+const response = await client.put('/libraries/123/medias/transfert', formData);
+```
+
+### `patch<T>(url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a PATCH request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.patch<ITag>('/libraries/123/tags/tag-id', {
+    rename: 'New Tag Name'
+});
+const updatedTag = response.data;
+```
+
+### `delete<T>(url: string, config?: AxiosRequestConfig)`
+
+Performs a DELETE request.
+
+**Parameters:**
+- `url`: The endpoint URL
+- `config`: Optional Axios request configuration (can include `data` for request body)
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+// Simple delete
+await client.delete('/libraries/123/tags/tag-id');
+
+// Delete with body
+await client.delete('/libraries/123/medias', {
+    data: { ids: ['media-1', 'media-2'] }
+});
+```
+
+### `request<T>(method: Method, url: string, data?: unknown, config?: AxiosRequestConfig)`
+
+Performs a custom HTTP request.
+
+**Parameters:**
+- `method`: HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE', etc.)
+- `url`: The endpoint URL
+- `data`: Request body data
+- `config`: Optional Axios request configuration
+
+**Returns:** `Promise<AxiosResponse<T>>`
+
+**Example:**
+```typescript
+const response = await client.request<IFile>(
+    'GET',
+    '/libraries/123/medias/media-id',
+    undefined,
+    { responseType: 'blob' }
+);
+```
+
+### `setToken(token: string | IToken)`
+
+Manually set the authentication token. Useful when you already have a valid token.
+
+**Parameters:**
+- `token`: Either a token string or an `IToken` object with `token` and `expires` properties
+
+**Example:**
+```typescript
+// Set as string (will be treated as expiring soon)
+client.setToken('your-token-string');
+
+// Set as IToken object with expiration
+client.setToken({
+    token: 'your-token-string',
+    expires: Date.now() + 3600000 // 1 hour from now
+});
+```
+
+## Error Handling
+
+The client automatically handles:
+- **401 Unauthorized**: Refreshes token and retries the request once
+- **Token expiration**: Refreshes token before making requests
+- **Network errors**: Passes through to caller
+
+**Example error handling:**
+```typescript
+try {
+    const response = await client.get('/libraries/123/medias');
+} catch (error) {
+    if (error.response?.status === 401) {
+        // Token refresh failed or invalid credentials
+        console.error('Authentication failed');
+    } else if (error.response?.status === 404) {
+        // Resource not found
+        console.error('Resource not found');
+    } else {
+        // Other error
+        console.error('Request failed:', error.message);
+    }
+}
+```
+
+## Usage with Response Types
+
+The client supports specifying response types for binary data:
+
+```typescript
+// Get as stream
+const stream = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'stream'
+});
+
+// Get as ArrayBuffer
+const buffer = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'arraybuffer'
+});
+
+// Get as Blob
+const blob = await client.get('/libraries/123/medias/media-id', {
+    responseType: 'blob'
+});
+```
+
+## Progress Tracking
+
+For file uploads, you can track progress:
+
+```typescript
+const formData = new FormData();
+formData.append('file', fileBlob);
+
+await client.post('/libraries/123/medias', formData, {
+    onUploadProgress: (progressEvent) => {
+        if (progressEvent.total) {
+            const percent = (progressEvent.loaded / progressEvent.total) * 100;
+            console.log(`Upload progress: ${percent}%`);
+        }
+    }
+});
+```
+
+## Internal Methods (Private)
+
+The following methods are used internally and should not be called directly:
+- `refreshToken()` - Refreshes the authentication token
+- `ensureValidToken()` - Ensures token is valid before requests
+- `isTokenExpiredOrExpiringSoon()` - Checks if token needs refresh
+- `detectLocalUrl()` - Detects local development server
+- `getRegularServerUrl()` - Gets production server URL
+
+## See Also
+
+- [ServerApi Documentation](server.md) - Uses RedseatClient for server operations
+- [LibraryApi Documentation](libraries.md) - Uses RedseatClient for library operations
+- [README](README.md) - Package overview
+

package/dist/auth.d.ts

@@ -0,0 +1,5 @@
+export interface IToken {
+    token: string;
+    expires: number;
+}
+export declare function fetchServerToken(serverId: string, idToken: string): Promise<IToken>;

package/dist/auth.js

@@ -0,0 +1,10 @@
+import axios from 'axios';
+export async function fetchServerToken(serverId, idToken) {
+    const headers = {
+        headers: {
+            Authorization: `Bearer ${idToken}`
+        }
+    };
+    const req = await axios.get(`/servers/${serverId}/token`, headers);
+    return req.data;
+}