@docstack/pouchdb-adapter-googledrive 0.0.6 → 0.0.9

package/docs/DEBUG_BIDIRECTIONAL_REPLICATION.ipynb

@@ -0,0 +1,481 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "60e24526",
+   "metadata": {},
+   "source": [
+    "# Debug: Replica Bidirezionale Google Drive PouchDB Adapter\n",
+    "\n",
+    "## Problema\n",
+    "La replica `localDB.replicate.to(googleDriveDB)` funziona ✅  \n",
+    "Ma `localDB.replicate.from(googleDriveDB)` non sincronizza i dati ❌\n",
+    "\n",
+    "Questo notebook diagnostica il flusso di replicazione per identificare dove il blocco si verifica."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "3796436e",
+   "metadata": {},
+   "source": [
+    "## 1️⃣ Section: Setup e Configurazione Replica\n",
+    "\n",
+    "### Aggiungi questo codice al tuo componente per diagnosticare il problema:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5a4749c9",
+   "metadata": {
+    "vscode": {
+     "languageId": "javascript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "// Setup Google Drive Adapter con debug logging\n",
+    "const plugin = GoogleDriveAdapter({\n",
+    "    accessToken: async () => driveConfig.accessToken,\n",
+    "    folderName: 'my-db',\n",
+    "    pollingIntervalMs: 5000,\n",
+    "    debug: true  // 🔍 Abilita logging dettagliato\n",
+    "});\n",
+    "\n",
+    "PouchDB.plugin(plugin);\n",
+    "\n",
+    "const googleDriveDB = new PouchDB('paper-drive-db', {\n",
+    "    adapter: 'googledrive'\n",
+    "});\n",
+    "\n",
+    "const localDB = stack?.db;\n",
+    "\n",
+    "// 🔍 Aggiungi listener per monitorare gli eventi di replicazione\n",
+    "console.log('=== SETUP REPLICA BIDIREZIONALE ===');\n",
+    "\n",
+    "// Replica TO (localDB → googleDriveDB) - Funzionante ✅\n",
+    "const repTo = localDB.replicate.to(googleDriveDB, { live: true, retry: true });\n",
+    "repTo.on('change', (info) => {\n",
+    "    console.log('📤 TO: change event', { \n",
+    "        direction: 'local→gdrive',\n",
+    "        docs: info.docs?.length,\n",
+    "        ok: info.ok\n",
+    "    });\n",
+    "});\n",
+    "repTo.on('complete', (info) => {\n",
+    "    console.log('✅ TO: replication complete', info);\n",
+    "});\n",
+    "repTo.on('error', (err) => {\n",
+    "    console.error('❌ TO: replication error', err);\n",
+    "});\n",
+    "\n",
+    "// Replica FROM (googleDriveDB → localDB) - Problema ❌\n",
+    "const repFrom = localDB.replicate.from(googleDriveDB, { live: true, retry: true });\n",
+    "repFrom.on('change', (info) => {\n",
+    "    console.log('📥 FROM: change event', { \n",
+    "        direction: 'gdrive→local',\n",
+    "        docs: info.docs?.length,\n",
+    "        ok: info.ok\n",
+    "    });\n",
+    "});\n",
+    "repFrom.on('complete', (info) => {\n",
+    "    console.log('✅ FROM: replication complete', info);\n",
+    "});\n",
+    "repFrom.on('error', (err) => {\n",
+    "    console.error('❌ FROM: replication error', err);\n",
+    "});"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "56686c46",
+   "metadata": {},
+   "source": [
+    "## 2️⃣ Section: Diagnosi - Verifica Flusso di Replicazione\n",
+    "\n",
+    "### Controlla le sequenze e i metadati del database"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "fb620ba8",
+   "metadata": {
+    "vscode": {
+     "languageId": "javascript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "// Confronta lo stato dei due database\n",
+    "async function compareDatabases() {\n",
+    "    const localInfo = await localDB.info();\n",
+    "    const googleDriveInfo = await googleDriveDB.info();\n",
+    "    \n",
+    "    console.log('📊 DATABASE INFO COMPARISON:');\n",
+    "    console.log('Local DB:', {\n",
+    "        doc_count: localInfo.doc_count,\n",
+    "        update_seq: localInfo.update_seq,\n",
+    "        db_name: localInfo.db_name\n",
+    "    });\n",
+    "    console.log('Google Drive DB:', {\n",
+    "        doc_count: googleDriveInfo.doc_count,\n",
+    "        update_seq: googleDriveInfo.update_seq,\n",
+    "        db_name: googleDriveInfo.db_name\n",
+    "    });\n",
+    "    \n",
+    "    return { localInfo, googleDriveInfo };\n",
+    "}\n",
+    "\n",
+    "// Esegui la diagnosi dopo 25 secondi (dopo che il polling ha avuto tempo di rilevare)\n",
+    "setTimeout(async () => {\n",
+    "    console.log('\\n=== DIAGNOSI DOPO 25 SEC ===\\n');\n",
+    "    \n",
+    "    const { localInfo, googleDriveInfo } = await compareDatabases();\n",
+    "    \n",
+    "    // 🔍 Verifica se le sequenze sono sincronizzate\n",
+    "    if (localInfo.update_seq === googleDriveInfo.update_seq) {\n",
+    "        console.log('✅ Sequenze sincronizzate');\n",
+    "    } else {\n",
+    "        console.warn('⚠️  Sequenze NON sincronizzate:', {\n",
+    "            local: localInfo.update_seq,\n",
+    "            googleDrive: googleDriveInfo.update_seq,\n",
+    "            diff: googleDriveInfo.update_seq - localInfo.update_seq\n",
+    "        });\n",
+    "    }\n",
+    "    \n",
+    "    // 🔍 Verifica il documento specifico su Google Drive\n",
+    "    try {\n",
+    "        const docOnDrive = await googleDriveDB.get('Notebook-0');\n",
+    "        console.log('✅ Notebook-0 trovato su Google Drive:', {\n",
+    "            _id: docOnDrive._id,\n",
+    "            _rev: docOnDrive._rev\n",
+    "        });\n",
+    "    } catch (err) {\n",
+    "        console.error('❌ Notebook-0 NON trovato su Google Drive:', err.message);\n",
+    "    }\n",
+    "    \n",
+    "    // 🔍 Verifica il documento su Local DB\n",
+    "    try {\n",
+    "        const docLocal = await localDB.get('Notebook-0');\n",
+    "        console.log('✅ Notebook-0 trovato su Local DB:', {\n",
+    "            _id: docLocal._id,\n",
+    "            _rev: docLocal._rev\n",
+    "        });\n",
+    "    } catch (err) {\n",
+    "        console.error('❌ Notebook-0 NON trovato su Local DB:', err.message);\n",
+    "    }\n",
+    "    \n",
+    "}, 25000);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5015299b",
+   "metadata": {},
+   "source": [
+    "## 3️⃣ Section: Debug - Polling e Change Detection\n",
+    "\n",
+    "### Il problema probabilmente è nel meccanismo di Polling\n",
+    "\n",
+    "Verifica se il polling sta effettivamente rilevando i cambiamenti da Google Drive:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5d57b557",
+   "metadata": {
+    "vscode": {
+     "languageId": "javascript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "// 🔍 Monitora i cambiamenti rilevati tramite _changes API\n",
+    "async function debugChangesAPI() {\n",
+    "    console.log('\\n=== TESTING _CHANGES API ===\\n');\n",
+    "    \n",
+    "    // Ottieni gli ultimi 10 cambiamenti dal Google Drive DB\n",
+    "    try {\n",
+    "        const changes = await googleDriveDB.changes({\n",
+    "            include_docs: true,\n",
+    "            descending: true,\n",
+    "            limit: 10\n",
+    "        });\n",
+    "        \n",
+    "        console.log('Recent changes from Google Drive DB:', {\n",
+    "            results: changes.results.length,\n",
+    "            last_seq: changes.last_seq,\n",
+    "            results: changes.results.map(r => ({\n",
+    "                id: r.id,\n",
+    "                seq: r.seq,\n",
+    "                changes: r.changes,\n",
+    "                deleted: r.deleted,\n",
+    "                hasDoc: !!r.doc\n",
+    "            }))\n",
+    "        });\n",
+    "        \n",
+    "        return changes;\n",
+    "    } catch (err) {\n",
+    "        console.error('❌ Error fetching changes from Google Drive DB:', err);\n",
+    "    }\n",
+    "}\n",
+    "\n",
+    "// Testa la _changes API subito\n",
+    "await debugChangesAPI();\n",
+    "\n",
+    "// Testa di nuovo dopo 10 secondi per vedere se il polling ha rilevato nuovi cambiamenti\n",
+    "setTimeout(async () => {\n",
+    "    console.log('\\n=== TESTING _CHANGES API AFTER POLLING ===\\n');\n",
+    "    await debugChangesAPI();\n",
+    "}, 10000);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "39d29701",
+   "metadata": {},
+   "source": [
+    "## 🚨 POSSIBILI CULPRIT IDENTIFICATI\n",
+    "\n",
+    "### Problema 1: _changes feed con `include_docs` potrebbe essere lento\n",
+    "\n",
+    "Nel tuo `adapter.ts`, quando `opts.include_docs` è vero, il metodo `_changes` deve:\n",
+    "- Scaricare il CORPO di ogni documento (lento)\n",
+    "- Questo blocca la replica\n",
+    "\n",
+    "**Diagnosi:**  \n",
+    "Controlla la console del browser. Se vedi molti `fetchFile` calls per ogni change, questo è il collo di bottiglia.\n",
+    "\n",
+    "### Problema 2: Change detection non rispetta il `since` parameter\n",
+    "\n",
+    "La replica PouchDB invia `since: lastSeq` per ricevere solo i cambiamenti NUOVI.  \n",
+    "Se `_changes` non filtra correttamente, la replica non rileva i nuovi documenti.\n",
+    "\n",
+    "### Problema 3: Live listener potrebbe non essere chiamato\n",
+    "\n",
+    "Nel `DriveHandler`, il polling rileva modifiche a `_meta.json`, ma:\n",
+    "- Il polling ha un delay di 5 secondi\n",
+    "- La replicazione potrebbe timeout prima di ricevere notifiche"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "de439ea3",
+   "metadata": {},
+   "source": [
+    "## 4️⃣ Section: Troubleshooting - Conflitti di Revisione\n",
+    "\n",
+    "### Verifica validazione revisioni"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "08da678c",
+   "metadata": {
+    "vscode": {
+     "languageId": "javascript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "// Verifica i conflitti di revisione durante la replica\n",
+    "async function checkReplicationConflicts() {\n",
+    "    console.log('\\n=== CHECKING REPLICATION CONFLICTS ===\\n');\n",
+    "    \n",
+    "    // Leggi lo stesso documento da entrambi i database\n",
+    "    const docId = 'Notebook-0';\n",
+    "    \n",
+    "    try {\n",
+    "        const localDoc = await localDB.get(docId);\n",
+    "        console.log('Local Doc:', { _id: localDoc._id, _rev: localDoc._rev });\n",
+    "    } catch (e) {\n",
+    "        console.warn('Local doc not found');\n",
+    "    }\n",
+    "    \n",
+    "    try {\n",
+    "        const remoteDoc = await googleDriveDB.get(docId);\n",
+    "        console.log('Remote Doc:', { _id: remoteDoc._id, _rev: remoteDoc._rev });\n",
+    "    } catch (e) {\n",
+    "        console.warn('Remote doc not found');\n",
+    "    }\n",
+    "    \n",
+    "    // 🔍 Verifica _conflicts (documenti con conflitti di merge)\n",
+    "    try {\n",
+    "        const allDocs = await localDB.allDocs({ conflicts: true });\n",
+    "        const conflictedDocs = allDocs.rows.filter(r => r.value.conflicts && r.value.conflicts.length > 0);\n",
+    "        if (conflictedDocs.length > 0) {\n",
+    "            console.warn('⚠️  Found documents with conflicts:', conflictedDocs);\n",
+    "        } else {\n",
+    "            console.log('✅ No conflicts found in local DB');\n",
+    "        }\n",
+    "    } catch (e) {\n",
+    "        console.error('Error checking conflicts:', e);\n",
+    "    }\n",
+    "}\n",
+    "\n",
+    "// Esegui il check dopo 30 secondi\n",
+    "setTimeout(async () => {\n",
+    "    await checkReplicationConflicts();\n",
+    "}, 30000);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "52a770f6",
+   "metadata": {},
+   "source": [
+    "## 5️⃣ Section: Validazione - Test della Replica Bidirezionale\n",
+    "\n",
+    "### Test Manuale: Crea un documento su Google Drive e verifica la sincronizzazione"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0f47da2f",
+   "metadata": {
+    "vscode": {
+     "languageId": "javascript"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "// 🧪 Test Completo della Replica Bidirezionale\n",
+    "\n",
+    "async function runFullReplicationTest() {\n",
+    "    console.log('\\n=== FULL REPLICATION TEST ===\\n');\n",
+    "    \n",
+    "    // Step 1: Leggi lo stato iniziale\n",
+    "    const localInfoBefore = await localDB.info();\n",
+    "    const googleDriveInfoBefore = await googleDriveDB.info();\n",
+    "    \n",
+    "    console.log('Initial State:');\n",
+    "    console.log('  Local:', { doc_count: localInfoBefore.doc_count, seq: localInfoBefore.update_seq });\n",
+    "    console.log('  Google Drive:', { doc_count: googleDriveInfoBefore.doc_count, seq: googleDriveInfoBefore.update_seq });\n",
+    "    \n",
+    "    // Step 2: Crea un nuovo documento SU GOOGLE DRIVE\n",
+    "    const testDocId = `test-sync-${Date.now()}`;\n",
+    "    const testDoc = {\n",
+    "        _id: testDocId,\n",
+    "        title: 'Test Document for Replication',\n",
+    "        createdAt: new Date().toISOString(),\n",
+    "        source: 'google-drive-db'\n",
+    "    };\n",
+    "    \n",
+    "    try {\n",
+    "        const saveResult = await googleDriveDB.put(testDoc);\n",
+    "        console.log('\\n✅ Created document on Google Drive:', { id: saveResult.id, rev: saveResult.rev });\n",
+    "    } catch (err) {\n",
+    "        console.error('❌ Failed to create document on Google Drive:', err);\n",
+    "        return;\n",
+    "    }\n",
+    "    \n",
+    "    // Step 3: Attendi il polling + replicazione (20 secondi dovrebbe essere sufficiente)\n",
+    "    console.log('\\n⏳ Waiting for polling and replication (20 seconds)...');\n",
+    "    \n",
+    "    await new Promise(resolve => setTimeout(resolve, 20000));\n",
+    "    \n",
+    "    // Step 4: Verifica se il documento è arrivato al Local DB\n",
+    "    try {\n",
+    "        const docOnLocal = await localDB.get(testDocId);\n",
+    "        console.log('\\n✅✅✅ SUCCESS! Document replicated to local DB:', {\n",
+    "            id: docOnLocal._id,\n",
+    "            rev: docOnLocal._rev,\n",
+    "            title: docOnLocal.title\n",
+    "        });\n",
+    "    } catch (err) {\n",
+    "        console.error('\\n❌ FAILED! Document NOT found on local DB:', err.message);\n",
+    "        \n",
+    "        // Diagnosi aggiuntiva\n",
+    "        console.log('\\n🔍 DIAGNOSTIC INFO:');\n",
+    "        const localInfoAfter = await localDB.info();\n",
+    "        const googleDriveInfoAfter = await googleDriveDB.info();\n",
+    "        \n",
+    "        console.log('After Test:');\n",
+    "        console.log('  Local:', { doc_count: localInfoAfter.doc_count, seq: localInfoAfter.update_seq });\n",
+    "        console.log('  Google Drive:', { doc_count: googleDriveInfoAfter.doc_count, seq: googleDriveInfoAfter.update_seq });\n",
+    "        \n",
+    "        // Verifica che il doc sia effettivamente su Google Drive\n",
+    "        try {\n",
+    "            const verifyDoc = await googleDriveDB.get(testDocId);\n",
+    "            console.log('✅ Document IS on Google Drive:', {\n",
+    "                id: verifyDoc._id,\n",
+    "                rev: verifyDoc._rev\n",
+    "            });\n",
+    "            console.log('❌ BUT NOT replicated to local. Issue: REPLICATION FROM REMOTE NOT WORKING');\n",
+    "        } catch (e) {\n",
+    "            console.error('❌ Document not even on Google Drive. Save failed?');\n",
+    "        }\n",
+    "    }\n",
+    "}\n",
+    "\n",
+    "// Esegui il test\n",
+    "await runFullReplicationTest();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "051a4d4b",
+   "metadata": {},
+   "source": [
+    "---\n",
+    "\n",
+    "## 🔧 SOLUZIONI CONSIGLIATE\n",
+    "\n",
+    "Basandoti sui risultati del test sopra, ecco i passaggi per risolvere il problema:\n",
+    "\n",
+    "### Se il test fallisce (documento non replica from remote):\n",
+    "\n",
+    "**Soluzione 1: Aumenta il pollingIntervalMs**\n",
+    "```javascript\n",
+    "pollingIntervalMs: 2000  // Invece di 5000 - controlla più frequentemente\n",
+    "```\n",
+    "\n",
+    "**Soluzione 2: Riduci il timeout di replicazione**\n",
+    "```javascript\n",
+    "const repFrom = localDB.replicate.from(googleDriveDB, { \n",
+    "    live: true, \n",
+    "    retry: true,\n",
+    "    timeout: 15000  // Aumenta timeout da default 30s\n",
+    "});\n",
+    "```\n",
+    "\n",
+    "**Soluzione 3: Aggiungi log nel adapter._changes in adapter.ts**\n",
+    "\n",
+    "Modifica `src/adapter.ts` linea ~428 per aggiungere debug:\n",
+    "```typescript\n",
+    "api._changes = function (opts: any): { cancel: () => void } {\n",
+    "    console.log('[_changes] Called with opts:', {\n",
+    "        since: opts.since,\n",
+    "        limit: opts.limit,\n",
+    "        live: opts.live,\n",
+    "        include_docs: !!opts.include_docs\n",
+    "    });\n",
+    "    // ...\n",
+    "```\n",
+    "\n",
+    "**Soluzione 4: Verifica che il live listener sia correttamente configurato**\n",
+    "\n",
+    "Nel `DriveHandler.load()`, assicurati che il polling chiami `notifyListeners()` ogni volta che rileva cambiamenti:\n",
+    "```typescript\n",
+    "if (metaFile.modifiedTime !== this.metaModifiedTime) {\n",
+    "    this.log('Polling detected change!', metaFile.modifiedTime);\n",
+    "    await this.load();\n",
+    "    this.notifyListeners();  // <-- DEVE ESSERE CHIAMATO\n",
+    "}\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

package/{DOCUMENTATION.md → docs/DOCUMENTATION.md}

@@ -52,3 +52,64 @@ Compaction is a critical maintenance task that merges the `snapshot-data` with r
 ### Conflict Handling
 - **PouchDB Level**: Standard CouchDB revision conflicts (409) are preserved. A "winner" is chosen deterministically, but conflicting revisions are kept in the tree (requires `snapshot-index` to store the full revision tree, not just the winner).
 - **Adapter Level**: Drive API 409s handling (retry logic) ensures the transport layer is reliable.
+
+## 3. Testing with Local Express Server
+
+The adapter includes a built-in test mode that emulates the Google Drive API using a local Express server. This allows for full integration testing without needing real Google Cloud credentials or network calls.
+
+### Configuration
+To enable the test emulator:
+
+```typescript
+const db = new PouchDB('testdb', {
+  adapter: 'googledrive',
+  testMode: true,
+  // testServerUrl: 'http://localhost:3000' // Optional, defaults to localhost:3000
+});
+```
+
+### Test Server
+The `TestServer` class (exported in `test-src/server.ts`) provides:
+- In-memory metadata storage
+- Local file system storage for content (defaults to `.test-drive-root` directory)
+- Emulation of `files.list`, `files.get`, `files.create` (multipart), `files.update`, and `files.delete`.
+
+### Example Usage
+```typescript
+import { TestServer } from './tests-src/server';
+
+const server = new TestServer(3000);
+await server.start();
+
+// Run PouchDB operations...
+
+
+## 4. Production Testing (Real Google Drive API)
+
+To verify the adapter against the actual Google Drive service, you can run the production test suite. This requires a valid Google OAuth2 Access Token.
+
+### A. Environment Setup
+Create a `.env` file in the project root (see `.env.example`):
+```env
+GOOGLE_ACCESS_TOKEN=your_temporary_access_token_here
+```
+
+### B. Obtaining a Token via OAuth1/2 Playground
+The easiest way to get a temporary token for manual testing:
+1.  Go to the [Google OAuth2 Playground](https://developers.google.com/oauthplayground/).
+2.  **Step 1 (Select & authorize APIs)**: 
+    *   Find "Drive API v3" in the list.
+    *   Select the scope: `https://www.googleapis.com/auth/drive.file` (this is the recommended scope as it only allows the app to see files it creates).
+    *   Click **Authorize APIs** and sign in with your Google account.
+3.  **Step 2 (Exchange authorization code for tokens)**:
+    *   Click **Exchange authorization code for tokens**.
+4.  **Step 3 (Configure request to API)**:
+    *   Copy the **Access Token** string.
+    *   Paste it into your `.env` file as `GOOGLE_ACCESS_TOKEN`.
+
+### C. Running the Tests
+Execute the following command to run the tests in production mode:
+```bash
+npm run test:prod
+```
+This command sets `TEST_ENV=production`, which tells the test runner to skip the local Express emulator and use the real Google Drive endpoints with your provided token.

package/docs/PROMISE_SUPPORT.md

@@ -0,0 +1,75 @@
+# Promise Support Documentation
+
+The adapter now fully supports all three PouchDB call patterns:
+
+## 1. Callback Pattern
+```javascript
+db.get('mydoc', function(err, doc) {
+  if (err) { return console.log(err); }
+  // handle doc
+});
+```
+
+## 2. Promise Pattern
+```javascript
+db.get('mydoc').then(function (doc) {
+  // handle doc
+}).catch(function (err) {
+  console.log(err);
+});
+```
+
+## 3. Async/Await Pattern
+```javascript
+try {
+  const doc = await db.get('mydoc');
+  // handle doc
+} catch (err) {
+  console.log(err);
+}
+```
+
+## Methods Updated
+
+The following adapter methods now support all three patterns:
+
+### Query Methods
+- `_get()` / `get()` - Get a single document
+- `_allDocs()` / `allDocs()` - Get all documents
+- `_getLocal()` - Get a local document
+- `_getRevisionTree()` - Get revision tree (internal)
+
+### Mutation Methods
+- `_bulkDocs()` / `bulkDocs()` - Bulk document operations
+- `_bulkGet()` / `bulkGet()` - Bulk get operation
+- `_putLocal()` - Put a local document
+- `_removeLocal()` - Remove a local document
+
+### Maintenance Methods
+- `_compact()` - Compact the database
+
+## Implementation Details
+
+Each method now:
+1. **Always returns a Promise** (even when a callback is provided)
+2. **Calls the callback if provided** for backward compatibility
+3. **Properly propagates errors** through both callbacks and rejections
+4. **Handles callback overloading** (when `opts` is actually the callback)
+
+This allows PouchDB and its replication engine to use the adapter with promises and async/await, fixing the error:
+```
+TypeError: can't access property "then", db.get(...) is undefined
+```
+
+## Migration Path
+
+Your existing callback-based code continues to work:
+```javascript
+// Old callback pattern - still works!
+db.get('doc1', (err, doc) => {
+  if (err) console.error(err);
+  else console.log(doc);
+});
+```
+
+You can gradually migrate to promises/async-await as needed.

package/docs/REPLICATION_ISSUE.md

@@ -0,0 +1,63 @@
+# Root Cause Analysis: Replication FROM Google Drive Issues
+
+After extensive debugging with a live emulation test suite, multiple critical issues were identified in the `_changes` and `notifyListeners` implementations.
+
+## 1. Missing `seq` Property in Notifications (CRITICAL)
+**Location**: `src/drive.ts` -> `notifyListeners()`
+
+**Problem**: 
+The `notifyListeners` method was emitting change objects that included `id`, `rev`, and `deleted`, but omitted the `seq` (sequence number). 
+
+**Consequence**: 
+PouchDB's replication engine uses the `seq` to track checkpoints. If a change arrives without a `seq`, PouchDB silently ignores it or fails to update its "since" pointer, meaning the replication appears to "detect" a change but never actually processes the document.
+
+**Fix**: 
+Updated the notification object to include the correct sequence number from the index.
+
+---
+
+## 2. Infinite Reconnect Loop in Live Changes
+**Location**: `src/adapter.ts` -> `_changes()`
+
+**Problem**: 
+An initial "fix" (based on standard CouchDB behavior) suggested calling `opts.complete()` at the end of the initial changes batch, even for live feeds. 
+
+**Consequence**: 
+In PouchDB, calling `complete()` on a **live** stream signals that the stream has ended gracefully. Because the replication is set to `live: true`, PouchDB interprets this as a connection drop and immediately restarts the changes feed. This created an infinite loop of:
+`Connect -> Fetch Batch -> Call Complete -> Disconnect -> Reconnect`
+This loop caused high CPU usage and eventually a "JavaScript heap out of memory" crash.
+
+**Fix**: 
+Restricted `opts.complete()` to only be called if `!opts.live`.
+
+---
+
+## 3. System Document Leakage (`_local/`)
+**Location**: `src/adapter.ts` -> `_changes()`
+
+**Problem**: 
+PouchDB uses local documents (IDs starting with `_local/`) to store replication checkpoints. Our adapter was incorrectly including these internal documents in the `_changes` feed results.
+
+**Consequence**: 
+When the remote side (Google Drive) reported a change to a `_local/` document, the local PouchDB tried to fetch it to replicate it. However, local documents are non-replicable and often missing from the full document fetch logic, leading to `not_found: missing` errors that crashed the replication process.
+
+**Fix**: 
+Added a filter to both the initial batch and the live listener to ignore any document ID starting with `_local/`.
+
+---
+
+## 4. Inefficient Polling & Redundant `load()` Calls
+**Location**: `src/drive.ts` -> `startPolling()` / `load()`
+
+**Problem**: 
+The polling mechanism was frequently triggering `load()`, which cleared the entire `processedLogIds` cache and re-downloaded all change logs from Google Drive. Additionally, `load()` was being called on every conflict retry without checking if the metadata had actually changed.
+
+**Fix**: 
+1. Implemented **ETag-based change detection** in polling.
+2. Added an **ETag check at the start of `load()`** to skip processing if the metadata on the server haven't changed since the last load.
+3. Updated `tryAppendChanges` to proactively call `notifyListeners()` for local writes, reducing reliance on the next polling tick for local UI updates.
+
+---
+
+## Summary of Results
+With these fixes applied, bidirectional replication is now stable and efficient. The "Out of Memory" crashes have been resolved, and changes from Google Drive are correctly detected and propagated to the local database within the specified polling interval.