@rsweeten/dropbox-sync 0.1.0

package/README.md

@@ -0,0 +1,315 @@
+# Dropbox Sync Module
+
+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
+
+## Features
+
+-   **File Synchronization**: Upload local files to Dropbox and download Dropbox files to your local filesystem
+-   **Real-time Progress**: Integrated Socket.IO support for real-time sync progress updates
+-   **Path Normalization**: Robust path handling to ensure consistent comparison between local and remote paths
+-   **OAuth Authentication**: Built-in OAuth flow handling for Dropbox API authentication
+-   **Framework Adapters**: Ready-to-use integrations for Next.js, SvelteKit, and Angular
+-   **TypeScript Support**: Fully typed API for improved developer experience
+
+## Installation
+
+```bash
+npm install dropbox-sync socket.io socket.io-client
+```
+
+## Quick Start
+
+### Core Usage
+
+```typescript
+import createDropboxSyncClient from 'dropbox-sync'
+
+// Create a Dropbox sync client
+const dropboxSync = createDropboxSyncClient({
+    clientId: 'YOUR_DROPBOX_APP_KEY',
+    clientSecret: 'YOUR_DROPBOX_APP_SECRET',
+    accessToken: 'OPTIONAL_EXISTING_TOKEN',
+    refreshToken: 'OPTIONAL_REFRESH_TOKEN',
+})
+
+// Start OAuth flow
+const authUrl = await dropboxSync.auth.getAuthUrl(
+    'http://localhost:3000/callback'
+)
+// Redirect the user to authUrl
+
+// Exchange authorization code for tokens
+const tokens = await dropboxSync.auth.exchangeCodeForToken(code, redirectUri)
+// Save tokens.accessToken and tokens.refreshToken
+
+// Sync files
+const syncResult = await dropboxSync.sync.syncFiles({
+    localDir: './public/img',
+    dropboxDir: '/app-images',
+})
+
+console.log(`Uploaded ${syncResult.uploaded.length} files`)
+console.log(`Downloaded ${syncResult.downloaded.length} files`)
+```
+
+## Framework-Specific Usage
+
+### Next.js
+
+```typescript
+// In your component
+import { useNextDropboxSync } from 'dropbox-sync'
+
+export function DropboxComponent() {
+    // Initialize client
+    const dropboxSync = useNextDropboxSync({
+        clientId: process.env.NEXT_PUBLIC_DROPBOX_APP_KEY,
+    })
+
+    // Connect to socket for real-time updates
+    useEffect(() => {
+        dropboxSync.socket.connect()
+        dropboxSync.socket.on('sync:progress', handleProgress)
+
+        return () => {
+            dropboxSync.socket.disconnect()
+        }
+    }, [])
+
+    // Start sync
+    const handleSync = () => {
+        // This will trigger the server-side sync through Socket.IO
+        dropboxSync.socket.emit('dropbox:sync')
+    }
+
+    return <button onClick={handleSync}>Sync with Dropbox</button>
+}
+
+// In your API route
+import { createNextDropboxApiHandlers } from 'dropbox-sync'
+
+const handlers = createNextDropboxApiHandlers()
+
+export async function GET(request) {
+    return handlers.status()
+}
+```
+
+### Nuxt.js
+
+The Nuxt adapter leverages Nuxt's runtime config system for app settings and uses H3 (Nitro's HTTP server) utilities for handling requests and cookies. It's designed to work seamlessly with Nuxt 3's composition API and server routes.
+
+To use this adapter in a Nuxt project, developers would:
+
+1. Add runtime config in their nuxt.config.ts:
+
+```typescript
+export default defineNuxtConfig({
+    runtimeConfig: {
+        // Private keys
+        dropboxAppSecret: process.env.DROPBOX_APP_SECRET,
+        dropboxRedirectUri: process.env.DROPBOX_REDIRECT_URI,
+
+        // Public keys
+        public: {
+            dropboxAppKey: process.env.DROPBOX_APP_KEY,
+            appUrl: process.env.APP_URL || 'http://localhost:3000',
+        },
+    },
+})
+```
+
+2. Create a plugin using the example provided
+3. Set up API routes using the handlers from `createNuxtApiHandlers()`
+
+```typescript
+// In your plugins/dropbox.ts
+import { useNuxtDropboxSync } from 'dropbox-sync'
+import { defineNuxtPlugin } from 'nuxt/app'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  // Create the Dropbox client
+  const dropboxSync = useNuxtDropboxSync()
+
+  // Provide the client to the app
+  return {
+    provide: {
+      dropbox: dropboxSync
+    }
+  }
+})
+
+// In your Vue component
+<script setup>
+import { ref, onMounted, onBeforeUnmount } from 'vue'
+
+const { $dropbox } = useNuxtApp()
+const syncProgress = ref(0)
+
+// Handle progress updates
+const handleProgress = (data) => {
+  syncProgress.value = data.progress
+}
+
+// Connect to socket
+onMounted(() => {
+  $dropbox.socket.connect()
+  $dropbox.socket.on('sync:progress', handleProgress)
+})
+
+// Clean up on unmount
+onBeforeUnmount(() => {
+  $dropbox.socket.disconnect()
+})
+
+// Start sync
+const startSync = () => {
+  $dropbox.socket.emit('dropbox:sync')
+}
+</script>
+
+<template>
+  <div>
+    <button @click="startSync">Sync with Dropbox</button>
+    <progress :value="syncProgress" max="100"></progress>
+  </div>
+</template>
+
+// In your server/api/dropbox/[...].ts
+import { createNuxtApiHandlers } from 'dropbox-sync'
+import { defineEventHandler } from 'h3'
+
+// Create handlers
+const handlers = createNuxtApiHandlers()
+
+export default defineEventHandler(async (event) => {
+  // Handle different endpoints
+  const path = event.path || ''
+
+  if (path.endsWith('/status')) {
+    return await handlers.status(event)
+  }
+
+  if (path.endsWith('/auth')) {
+    return await handlers.oauthStart(event)
+  }
+
+  if (path.endsWith('/auth/callback')) {
+    return await handlers.oauthCallback(event)
+  }
+
+  if (path.endsWith('/logout')) {
+    return await handlers.logout(event)
+  }
+
+  return { error: 'Not found' }
+})
+```
+
+### SvelteKit
+
+```typescript
+// In your store
+import { useSvelteDropboxSync } from 'dropbox-sync'
+import { writable } from 'svelte/store'
+
+// Create store
+export function createDropboxStore() {
+    const dropboxSync = useSvelteDropboxSync({
+        clientId: import.meta.env.VITE_DROPBOX_APP_KEY,
+    })
+
+    const progress = writable(0)
+
+    // Set up socket listeners
+    dropboxSync.socket.connect()
+    dropboxSync.socket.on('sync:progress', (data) => {
+        progress.set(data.progress)
+    })
+
+    return {
+        progress: { subscribe: progress.subscribe },
+        startSync: () => {
+            dropboxSync.socket.emit('dropbox:sync')
+        },
+    }
+}
+```
+
+### Angular
+
+```typescript
+// In your service
+import { DropboxSyncService, getCredentialsFromEnvironment } from 'dropbox-sync'
+import { environment } from '../environments/environment'
+
+@Injectable({ providedIn: 'root' })
+export class DropboxService {
+    constructor(private dropboxSyncService: DropboxSyncService) {
+        // Initialize the service
+        this.dropboxSyncService.initialize(
+            getCredentialsFromEnvironment(environment)
+        )
+
+        // Listen for socket events
+        const socketEvents = this.dropboxSyncService.setupSocketListeners()
+        socketEvents.subscribe((event) => console.log(event))
+    }
+
+    startSync() {
+        return this.dropboxSyncService.startSync()
+    }
+}
+```
+
+## API Reference
+
+### Core Client
+
+-   `createDropboxSyncClient(credentials)` - Creates a new client instance
+
+### Auth Methods
+
+-   `getAuthUrl(redirectUri, state?)` - Generate an OAuth authentication URL
+-   `exchangeCodeForToken(code, redirectUri)` - Exchange authorization code for access token
+-   `refreshAccessToken()` - Refresh an expired access token
+
+### Sync Methods
+
+-   `scanLocalFiles(dir?)` - Scan local directory for files
+-   `scanDropboxFiles(dir?)` - Scan Dropbox folder for files
+-   `createSyncQueue(options?)` - Create upload/download queues
+-   `syncFiles(options?)` - Synchronize files between local and Dropbox
+-   `cancelSync()` - Cancel an ongoing synchronization
+
+### Socket Methods
+
+-   `connect()` - Connect to Socket.IO
+-   `disconnect()` - Disconnect from Socket.IO
+-   `on(event, handler)` - Listen for an event
+-   `off(event)` - Remove event listener
+-   `emit(event, ...args)` - Emit an event
+
+## Socket Events
+
+-   `sync:progress` - Emitted during sync with progress information
+-   `sync:queue` - Emitted at the start of sync with queue information
+-   `sync:complete` - Emitted when sync is complete
+-   `sync:error` - Emitted when an error occurs during sync
+
+## Configuration Options
+
+```typescript
+interface SyncOptions {
+    localDir: string // Local directory path
+    dropboxDir?: string // Dropbox folder path
+    fileTypes?: RegExp // File types to sync (default: images and JSON)
+    progressCallback?: (progress: SyncProgress) => void
+}
+```
+
+## License
+
+MIT

package/dist/adapters/angular.d.ts

@@ -0,0 +1,56 @@
+import { HttpClient } from '@angular/common/http';
+import { Observable } from 'rxjs';
+import type { DropboxCredentials, DropboxSyncClient, SyncOptions, SyncResult, TokenResponse } from '../core/types';
+export declare class DropboxSyncService {
+    private http;
+    private client;
+    constructor(http: HttpClient);
+    /**
+     * Initialize the Dropbox sync client with credentials
+     */
+    initialize(credentials: DropboxCredentials): DropboxSyncClient;
+    /**
+     * Get the current Dropbox sync client instance, or initialize with credentials if not exists
+     */
+    getClient(credentials?: DropboxCredentials): DropboxSyncClient;
+    /**
+     * Check the connection status with Dropbox
+     */
+    checkConnection(): Observable<boolean>;
+    /**
+     * Start the OAuth flow to connect to Dropbox
+     */
+    connectDropbox(): void;
+    /**
+     * Disconnect from Dropbox
+     */
+    disconnectDropbox(): Observable<boolean>;
+    /**
+     * Start the sync process
+     */
+    startSync(options?: Partial<SyncOptions>): Observable<SyncResult>;
+    /**
+     * Cancel an ongoing sync process
+     */
+    cancelSync(): void;
+    /**
+     * Set up socket listeners for sync events
+     * Returns an RxJS Observable that emits sync progress events
+     */
+    setupSocketListeners(): Observable<any>;
+    /**
+     * Handle OAuth callback on the client side
+     */
+    handleOAuthCallback(code: string): Observable<TokenResponse>;
+    /**
+     * Create a sync queue to determine which files need to be uploaded/downloaded
+     */
+    createSyncQueue(options?: Partial<SyncOptions>): Observable<{
+        uploadQueue: string[];
+        downloadQueue: string[];
+    }>;
+}
+/**
+ * Function to extract credentials from Angular environment
+ */
+export declare function getCredentialsFromEnvironment(environment: any): DropboxCredentials;

package/dist/adapters/angular.js

@@ -0,0 +1,207 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __setFunctionName = (this && this.__setFunctionName) || function (f, name, prefix) {
+    if (typeof name === "symbol") name = name.description ? "[".concat(name.description, "]") : "";
+    return Object.defineProperty(f, "name", { configurable: true, value: prefix ? "".concat(prefix, " ", name) : name });
+};
+import { Injectable } from '@angular/core';
+import { Observable, from, of } from 'rxjs';
+import { catchError, map, tap } from 'rxjs/operators';
+import { createDropboxSyncClient } from '../core/client';
+let DropboxSyncService = (() => {
+    let _classDecorators = [Injectable({
+            providedIn: 'root',
+        })];
+    let _classDescriptor;
+    let _classExtraInitializers = [];
+    let _classThis;
+    var DropboxSyncService = _classThis = class {
+        constructor(http) {
+            this.http = http;
+            this.client = null;
+        }
+        /**
+         * Initialize the Dropbox sync client with credentials
+         */
+        initialize(credentials) {
+            this.client = createDropboxSyncClient(credentials);
+            return this.client;
+        }
+        /**
+         * Get the current Dropbox sync client instance, or initialize with credentials if not exists
+         */
+        getClient(credentials) {
+            if (!this.client && credentials) {
+                return this.initialize(credentials);
+            }
+            if (!this.client) {
+                throw new Error('DropboxSyncService not initialized. Call initialize() first.');
+            }
+            return this.client;
+        }
+        /**
+         * Check the connection status with Dropbox
+         */
+        checkConnection() {
+            return this.http
+                .get('/api/dropbox/status')
+                .pipe(map((response) => response.connected), catchError(() => of(false)));
+        }
+        /**
+         * Start the OAuth flow to connect to Dropbox
+         */
+        connectDropbox() {
+            window.location.href = '/api/dropbox/auth/start';
+        }
+        /**
+         * Disconnect from Dropbox
+         */
+        disconnectDropbox() {
+            return this.http
+                .post('/api/dropbox/logout', {})
+                .pipe(map((response) => response.success), catchError(() => of(false)));
+        }
+        /**
+         * Start the sync process
+         */
+        startSync(options) {
+            if (!this.client) {
+                throw new Error('DropboxSyncService not initialized. Call initialize() first.');
+            }
+            // Connect to socket before starting sync
+            this.client.socket.connect();
+            // Setup socket listeners for sync events
+            this.setupSocketListeners();
+            return from(this.client.sync.syncFiles(options));
+        }
+        /**
+         * Cancel an ongoing sync process
+         */
+        cancelSync() {
+            if (!this.client) {
+                return;
+            }
+            this.client.sync.cancelSync();
+        }
+        /**
+         * Set up socket listeners for sync events
+         * Returns an RxJS Observable that emits sync progress events
+         */
+        setupSocketListeners() {
+            if (!this.client) {
+                throw new Error('DropboxSyncService not initialized. Call initialize() first.');
+            }
+            // Create observable for sync progress events
+            return new Observable((observer) => {
+                // Listen for progress updates
+                this.client.socket.on('sync:progress', (data) => {
+                    observer.next({ type: 'progress', data });
+                });
+                // Listen for queue information
+                this.client.socket.on('sync:queue', (data) => {
+                    observer.next({ type: 'queue', data });
+                });
+                // Listen for sync completion
+                this.client.socket.on('sync:complete', (data) => {
+                    observer.next({ type: 'complete', data });
+                    observer.complete();
+                });
+                // Listen for sync errors
+                this.client.socket.on('sync:error', (data) => {
+                    if (!data.continue) {
+                        observer.error(data.message);
+                    }
+                    else {
+                        observer.next({ type: 'error', data });
+                    }
+                });
+                // Cleanup function - remove event listeners when subscription is disposed
+                return () => {
+                    this.client.socket.off('sync:progress');
+                    this.client.socket.off('sync:queue');
+                    this.client.socket.off('sync:complete');
+                    this.client.socket.off('sync:error');
+                };
+            });
+        }
+        /**
+         * Handle OAuth callback on the client side
+         */
+        handleOAuthCallback(code) {
+            if (!this.client) {
+                throw new Error('DropboxSyncService not initialized. Call initialize() first.');
+            }
+            const redirectUri = window.location.origin + '/api/dropbox/auth/callback';
+            return from(this.client.auth.exchangeCodeForToken(code, redirectUri)).pipe(tap((tokens) => {
+                // Store tokens in local storage for client-side access
+                localStorage.setItem('dropbox_access_token', tokens.accessToken);
+                if (tokens.refreshToken) {
+                    localStorage.setItem('dropbox_refresh_token', tokens.refreshToken);
+                }
+                localStorage.setItem('dropbox_connected', 'true');
+            }));
+        }
+        /**
+         * Create a sync queue to determine which files need to be uploaded/downloaded
+         */
+        createSyncQueue(options) {
+            if (!this.client) {
+                throw new Error('DropboxSyncService not initialized. Call initialize() first.');
+            }
+            return from(this.client.sync.createSyncQueue(options));
+        }
+    };
+    __setFunctionName(_classThis, "DropboxSyncService");
+    (() => {
+        const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+        __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+        DropboxSyncService = _classThis = _classDescriptor.value;
+        if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        __runInitializers(_classThis, _classExtraInitializers);
+    })();
+    return DropboxSyncService = _classThis;
+})();
+export { DropboxSyncService };
+/**
+ * Function to extract credentials from Angular environment
+ */
+export function getCredentialsFromEnvironment(environment) {
+    return {
+        clientId: environment.dropboxAppKey || '',
+        clientSecret: environment.dropboxAppSecret,
+        accessToken: localStorage.getItem('dropbox_access_token') || undefined,
+        refreshToken: localStorage.getItem('dropbox_refresh_token') || undefined,
+    };
+}

package/dist/adapters/next.d.ts

@@ -0,0 +1,36 @@
+import type { DropboxCredentials, DropboxSyncClient } from '../core/types';
+import { NextRequest, NextResponse } from 'next/server';
+/**
+ * Next.js-specific helper to create a Dropbox sync client
+ * Can be used in both client and server components
+ */
+export declare function useNextDropboxSync(credentials: DropboxCredentials): DropboxSyncClient;
+/**
+ * Server-side helper to get credentials from Next.js cookies
+ */
+export declare function getCredentialsFromCookies(): Promise<DropboxCredentials>;
+/**
+ * Server action to handle Dropbox OAuth callback
+ */
+export declare function handleOAuthCallback(request: NextRequest): Promise<NextResponse>;
+/**
+ * Create API route handlers for a Next.js app
+ */
+export declare function createNextDropboxApiHandlers(): {
+    /**
+     * Handler for status check route
+     */
+    status(): Promise<NextResponse<{
+        connected: boolean;
+    }>>;
+    /**
+     * Handler for OAuth start route
+     */
+    oauthStart(): Promise<NextResponse<unknown>>;
+    /**
+     * Handler for logout route
+     */
+    logout(): Promise<NextResponse<{
+        success: boolean;
+    }>>;
+};