@redseat/api 0.0.12 → 0.0.14

package/test.md

@@ -1,291 +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
-
+# 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
+