@rsweeten/dropbox-sync 0.1.2 → 0.1.3

package/.github/workflows/test-pr.yml

@@ -0,0 +1,30 @@
+name: Test Pull Request
+
+on:
+    pull_request:
+        branches: [main]
+    push:
+        branches: [main]
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+
+        strategy:
+            matrix:
+                node-version: [20.x]
+
+        steps:
+            - uses: actions/checkout@v3
+
+            - name: Use Node.js ${{ matrix.node-version }}
+              uses: actions/setup-node@v3
+              with:
+                  node-version: ${{ matrix.node-version }}
+                  cache: 'npm'
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Run tests
+              run: npm test

package/README.md

@@ -1,9 +1,40 @@
 # Dropbox Sync Module
 
+[![Test Pull Request](https://github.com/sweetenr/dropbox-sync-service/actions/workflows/test-pr.yml/badge.svg)](https://github.com/sweetenr/dropbox-sync-service/actions/workflows/test-pr.yml)
+
 A reusable TypeScript module for syncing files between your application and Dropbox. Features framework-specific adapters for Next.js, SvelteKit, Nuxt, and Angular.
 
 > N.B. This NPM package is neither tested nor supported
 
+## Table of Contents
+
+-   [Features](#features)
+-   [Installation](#installation)
+-   [Quick Start](#quick-start)
+    -   [Core Usage](#core-usage)
+-   [Development Setup](#development-setup)
+-   [Architecture](#architecture)
+    -   [Data Flow](#data-flow)
+-   [Testing](#testing)
+    -   [Test Structure](#test-structure)
+    -   [Running Tests](#running-tests)
+    -   [Testing Approach](#testing-approach)
+    -   [Mock Strategy](#mock-strategy)
+    -   [Test Coverage](#test-coverage)
+-   [Framework-Specific Usage](#framework-specific-usage)
+    -   [Next.js](#nextjs)
+    -   [Nuxt.js](#nuxtjs)
+    -   [SvelteKit](#sveltekit)
+    -   [Angular](#angular)
+-   [API Reference](#api-reference)
+    -   [Core Client](#core-client)
+    -   [Auth Methods](#auth-methods)
+    -   [Sync Methods](#sync-methods)
+    -   [Socket Methods](#socket-methods)
+-   [Socket Events](#socket-events)
+-   [Configuration Options](#configuration-options)
+-   [License](#license)
+
 ## Features
 
 -   **File Synchronization**: Upload local files to Dropbox and download Dropbox files to your local filesystem
@@ -16,7 +47,18 @@ A reusable TypeScript module for syncing files between your application and Drop
 ## Installation
 
 ```bash
-npm install dropbox-sync socket.io socket.io-client
+# Install the package in your project
+npm install dropbox-sync
+# or
+yarn add dropbox-sync
+```
+
+You may also need to install peer dependencies:
+
+```bash
+npm install socket.io socket.io-client
+# or
+yarn add socket.io socket.io-client
 ```
 
 ## Quick Start
@@ -54,6 +96,170 @@ console.log(`Uploaded ${syncResult.uploaded.length} files`)
 console.log(`Downloaded ${syncResult.downloaded.length} files`)
 ```
 
+## Development Setup
+
+To set up this project for local development:
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/dropbox-sync-service.git
+cd dropbox-sync-service
+
+# Install dependencies
+npm install
+
+# Run tests
+npm test
+
+# Build the package
+npm run build
+```
+
+## Architecture
+
+The Dropbox Sync Module architecture is designed with modularity, extensibility, and framework-agnosticism in mind.
+
+```mermaid
+graph TD
+    A[Application] --> B[Framework Adapter]
+    B --> C[Core Client]
+    C --> D[Auth Module]
+    C --> E[Sync Module]
+    C --> F[Socket Module]
+    D --> G[Dropbox API]
+    E --> G
+    F --> H[Socket.IO]
+    H --> E
+    H --> A
+
+    %% File Flow
+    I[Local Files] --> E
+    E --> I
+    G --> E
+    E --> G
+```
+
+### Data Flow
+
+1. **Authentication Flow:**
+
+    ```mermaid
+    sequenceDiagram
+        participant User
+        participant App
+        participant DropboxSync
+        participant Dropbox
+
+        User->>App: Initiate auth
+        App->>DropboxSync: getAuthUrl()
+        DropboxSync->>Dropbox: Request auth URL
+        Dropbox-->>DropboxSync: Auth URL
+        DropboxSync-->>App: Auth URL
+        App-->>User: Redirect to auth URL
+        User->>Dropbox: Authorize app
+        Dropbox-->>App: Auth code (via redirect)
+        App->>DropboxSync: exchangeCodeForToken(code)
+        DropboxSync->>Dropbox: Exchange code for token
+        Dropbox-->>DropboxSync: Access & refresh tokens
+        DropboxSync-->>App: Tokens
+    ```
+
+2. **Sync Flow:**
+
+    ```mermaid
+    sequenceDiagram
+        participant App
+        participant DropboxSync
+        participant Socket
+        participant Dropbox
+        participant LocalFS
+
+        App->>DropboxSync: syncFiles(options)
+        DropboxSync->>LocalFS: Scan local files
+        LocalFS-->>DropboxSync: Local file list
+        DropboxSync->>Dropbox: List files
+        Dropbox-->>DropboxSync: Dropbox file list
+        DropboxSync->>DropboxSync: Create sync queue
+
+        loop For each file to upload
+            DropboxSync->>Dropbox: Upload file
+            DropboxSync->>Socket: Emit progress
+            Socket-->>App: Progress update
+        end
+
+        loop For each file to download
+            DropboxSync->>Dropbox: Download file
+            DropboxSync->>LocalFS: Write file
+            DropboxSync->>Socket: Emit progress
+            Socket-->>App: Progress update
+        end
+
+        DropboxSync-->>App: Sync results
+    ```
+
+## Testing
+
+The Dropbox Sync Module uses Jest for unit testing. Tests are organized to match the structure of the source code.
+
+### Test Structure
+
+```
+__tests__/              # Test utilities and mocks
+src/
+  core/
+    __tests__/          # Core module tests
+      auth.spec.ts      # Authentication tests
+      client.spec.ts    # Client tests
+      socket.spec.ts    # Socket tests
+      sync.spec.ts      # Sync tests
+  adapters/
+    __tests__/          # Framework adapter tests
+      angular.spec.ts   # Angular adapter tests
+      next.spec.ts      # Next.js adapter tests
+      nuxt.spec.ts      # Nuxt adapter tests
+      svelte.spec.ts    # SvelteKit adapter tests
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm test -- --coverage
+
+# Run specific test file
+npm test -- src/core/__tests__/auth.spec.ts
+
+# Run tests in watch mode during development
+npm test -- --watch
+```
+
+### Testing Approach
+
+1. **Unit Tests**: Each module is tested in isolation with mocked dependencies
+2. **Integration Tests**: Tests for interactions between modules
+3. **Adapter Tests**: Tests for framework-specific adapters
+
+### Mock Strategy
+
+-   Dropbox API calls are mocked using Jest mock functions
+-   File system operations are mocked to avoid touching real files
+-   Socket.IO is mocked to test event emission and handling
+
+### Test Coverage
+
+We aim for high test coverage, especially for the core functionality:
+
+| Module   | Coverage |
+| -------- | -------- |
+| Core     | >90%     |
+| Auth     | >95%     |
+| Sync     | >90%     |
+| Socket   | >90%     |
+| Adapters | >85%     |
+
 ## Framework-Specific Usage
 
 ### Next.js

package/__mocks__/nuxt/app.js

@@ -0,0 +1,20 @@
+// Manual mock for nuxt/app module
+module.exports = {
+  useRuntimeConfig: jest.fn().mockReturnValue({
+    public: {
+      dropboxAppKey: 'test-app-key',
+      appUrl: 'https://example.com'
+    },
+    dropboxAppSecret: 'test-app-secret',
+    dropboxRedirectUri: 'https://example.com/api/dropbox/auth/callback'
+  }),
+  useCookie: jest.fn().mockImplementation((name) => {
+    if (name === 'dropbox_access_token') {
+      return { value: 'test-access-token' }
+    }
+    if (name === 'dropbox_refresh_token') {
+      return { value: 'test-refresh-token' }
+    }
+    return { value: null }
+  })
+}

package/dist/adapters/__tests__/angular.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/adapters/__tests__/angular.spec.js

@@ -0,0 +1,237 @@
+// Mock Angular modules before importing the code under test
+jest.mock('@angular/core', () => ({
+    Injectable: () => jest.fn(),
+}));
+jest.mock('@angular/common/http', () => ({
+    HttpClient: jest.fn(),
+    HttpHeaders: jest.fn(),
+}));
+// Now import the code that uses Angular modules
+import { DropboxSyncService, getCredentialsFromEnvironment } from '../angular';
+import { createDropboxSyncClient } from '../../core/client';
+import { of } from 'rxjs';
+import { Observable } from 'rxjs';
+// Mock the core client
+jest.mock('../../core/client');
+describe('Angular adapter', () => {
+    let service;
+    const mockHttpClient = {
+        get: jest.fn(),
+        post: jest.fn(),
+    };
+    beforeEach(() => {
+        jest.clearAllMocks();
+        service = new DropboxSyncService(mockHttpClient);
+    });
+    describe('DropboxSyncService', () => {
+        it('should be created', () => {
+            expect(service).toBeTruthy();
+        });
+        it('should initialize with credentials', () => {
+            const mockCredentials = {
+                clientId: 'test-client-id',
+                clientSecret: 'test-client-secret',
+                accessToken: 'test-access-token',
+                refreshToken: 'test-refresh-token',
+            };
+            const mockClient = { mock: 'client' };
+            createDropboxSyncClient.mockReturnValue(mockClient);
+            const result = service.initialize(mockCredentials);
+            expect(createDropboxSyncClient).toHaveBeenCalledWith(mockCredentials);
+            expect(result).toEqual(mockClient);
+        });
+        it('should get client after initialization', () => {
+            const mockCredentials = { clientId: 'test-id' };
+            const mockClient = { mock: 'client' };
+            createDropboxSyncClient.mockReturnValue(mockClient);
+            service.initialize(mockCredentials);
+            const client = service.getClient();
+            expect(client).toEqual(mockClient);
+        });
+        it('should throw error if getClient called before initialization', () => {
+            expect(() => service.getClient()).toThrow('DropboxSyncService not initialized. Call initialize() first.');
+        });
+        it('should check connection status via HTTP', () => {
+            mockHttpClient.get.mockReturnValue(of({ connected: true }));
+            service.checkConnection().subscribe((result) => {
+                expect(result).toBe(true);
+            });
+            expect(mockHttpClient.get).toHaveBeenCalledWith('/api/dropbox/status');
+        });
+        it('should handle connection error', () => {
+            mockHttpClient.get.mockReturnValue(of(null)); // Simulate error
+            service.checkConnection().subscribe((result) => {
+                expect(result).toBe(false);
+            });
+        });
+        it('should disconnect via HTTP', () => {
+            mockHttpClient.post.mockReturnValue(of({ success: true }));
+            service.disconnectDropbox().subscribe((result) => {
+                expect(result).toBe(true);
+            });
+            expect(mockHttpClient.post).toHaveBeenCalledWith('/api/dropbox/logout', {});
+        });
+        it('should start sync process', () => {
+            const mockOptions = { localDir: '/test-dir' };
+            const mockResult = { uploaded: [], downloaded: [] };
+            const mockClient = {
+                sync: {
+                    syncFiles: jest.fn().mockResolvedValue(mockResult),
+                },
+                socket: {
+                    connect: jest.fn(),
+                },
+            };
+            createDropboxSyncClient.mockReturnValue(mockClient);
+            service.initialize({ clientId: 'test-id' });
+            // Mock setupSocketListeners to return an observable
+            service.setupSocketListeners = jest.fn().mockReturnValue(of({}));
+            service.startSync(mockOptions).subscribe((result) => {
+                expect(result).toEqual(mockResult);
+            });
+            expect(mockClient.socket.connect).toHaveBeenCalled();
+            expect(mockClient.sync.syncFiles).toHaveBeenCalledWith(mockOptions);
+            expect(service.setupSocketListeners).toHaveBeenCalled();
+        });
+        it('should cancel sync', () => {
+            const mockClient = {
+                sync: {
+                    cancelSync: jest.fn(),
+                },
+            };
+            createDropboxSyncClient.mockReturnValue(mockClient);
+            service.initialize({ clientId: 'test-id' });
+            service.cancelSync();
+            expect(mockClient.sync.cancelSync).toHaveBeenCalled();
+        });
+        // Mock the implementation of setupSocketListeners for testing
+        it('should setup socket listeners', () => {
+            const mockSocket = {
+                on: jest.fn(),
+                off: jest.fn(),
+            };
+            const mockClient = {
+                socket: mockSocket,
+            };
+            createDropboxSyncClient.mockReturnValue(mockClient);
+            service.initialize({ clientId: 'test-id' });
+            const observable = service.setupSocketListeners();
+            // Should return an Observable
+            expect(observable).toBeInstanceOf(Observable);
+            // Get the subscriber function that was used to create the Observable
+            const observer = {
+                next: jest.fn(),
+                error: jest.fn(),
+                complete: jest.fn(),
+            };
+            const subscription = observable.subscribe(observer);
+            // Since we have direct access to the socket mock, we can verify its behavior
+            expect(mockSocket.on).toHaveBeenCalledWith('sync:progress', expect.any(Function));
+            expect(mockSocket.on).toHaveBeenCalledWith('sync:queue', expect.any(Function));
+            expect(mockSocket.on).toHaveBeenCalledWith('sync:complete', expect.any(Function));
+            expect(mockSocket.on).toHaveBeenCalledWith('sync:error', expect.any(Function));
+            // Clean up the subscription
+            subscription.unsubscribe();
+        });
+        it('should handle OAuth callback', () => {
+            const mockCode = 'test-auth-code';
+            const mockTokens = {
+                accessToken: 'new-access-token',
+                refreshToken: 'new-refresh-token',
+            };
+            const mockClient = {
+                auth: {
+                    exchangeCodeForToken: jest
+                        .fn()
+                        .mockResolvedValue(mockTokens),
+                },
+            };
+            createDropboxSyncClient.mockReturnValue(mockClient);
+            service.initialize({ clientId: 'test-id' });
+            // Create a proper localStorage mock
+            const mockLocalStorage = {
+                setItem: jest.fn(),
+                getItem: jest.fn(),
+                removeItem: jest.fn(),
+            };
+            Object.defineProperty(global, 'localStorage', {
+                value: mockLocalStorage,
+                writable: true,
+            });
+            // Mock window.location.origin
+            Object.defineProperty(window, 'location', {
+                value: {
+                    origin: 'http://localhost',
+                },
+                writable: true,
+            });
+            // Subscribe to the observable to trigger the code
+            let receivedResult;
+            service.handleOAuthCallback(mockCode).subscribe((result) => {
+                receivedResult = result;
+            });
+            // Verify the exchangeCodeForToken was called with the expected args
+            expect(mockClient.auth.exchangeCodeForToken).toHaveBeenCalledWith(mockCode, 'http://localhost/api/dropbox/auth/callback');
+            // Create and resolve the promise to trigger the localStorage set calls
+            const resolvePromise = Promise.resolve(mockTokens);
+            // Return a promise that will resolve after our mocked promise
+            return resolvePromise.then(() => {
+                // Now we can check localStorage was called
+                expect(mockLocalStorage.setItem).toHaveBeenCalledWith('dropbox_access_token', mockTokens.accessToken);
+                expect(mockLocalStorage.setItem).toHaveBeenCalledWith('dropbox_refresh_token', mockTokens.refreshToken);
+                expect(mockLocalStorage.setItem).toHaveBeenCalledWith('dropbox_connected', 'true');
+                // Verify we received the tokens
+                expect(receivedResult).toEqual(mockTokens);
+            });
+        });
+    });
+    describe('getCredentialsFromEnvironment', () => {
+        it('should extract credentials from environment', () => {
+            const mockEnvironment = {
+                dropboxAppKey: 'env-app-key',
+                dropboxAppSecret: 'env-app-secret',
+            };
+            // Mock localStorage
+            const mockLocalStorage = {
+                getItem: jest.fn().mockImplementation((key) => {
+                    if (key === 'dropbox_access_token')
+                        return 'storage-access-token';
+                    if (key === 'dropbox_refresh_token')
+                        return 'storage-refresh-token';
+                    return null;
+                }),
+            };
+            Object.defineProperty(global, 'localStorage', {
+                value: mockLocalStorage,
+                writable: true,
+            });
+            const credentials = getCredentialsFromEnvironment(mockEnvironment);
+            expect(credentials).toEqual({
+                clientId: 'env-app-key',
+                clientSecret: 'env-app-secret',
+                accessToken: 'storage-access-token',
+                refreshToken: 'storage-refresh-token',
+            });
+            expect(mockLocalStorage.getItem).toHaveBeenCalledWith('dropbox_access_token');
+            expect(mockLocalStorage.getItem).toHaveBeenCalledWith('dropbox_refresh_token');
+        });
+        it('should handle missing environment values', () => {
+            const mockEnvironment = {};
+            // Mock localStorage with no tokens
+            const mockLocalStorage = {
+                getItem: jest.fn().mockReturnValue(null),
+            };
+            Object.defineProperty(global, 'localStorage', {
+                value: mockLocalStorage,
+                writable: true,
+            });
+            const credentials = getCredentialsFromEnvironment(mockEnvironment);
+            expect(credentials).toEqual({
+                clientId: '',
+                clientSecret: undefined,
+                accessToken: undefined,
+                refreshToken: undefined,
+            });
+        });
+    });
+});

package/dist/adapters/__tests__/next.spec.d.ts

@@ -0,0 +1 @@
+export {};