@rsweeten/dropbox-sync 0.1.0 → 0.1.2

package/README.md

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