@glance-apps/sync 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.2] - 2026-05-22
+
+### Added
+
+- `getSessionKey()` export — returns the cached non-extractable `CryptoKey` for reuse by sibling packages (e.g., `@glance-apps/intents` encryption helpers).
+
+## [1.0.1] - 2026-05-18
+
+### Fixed
+
+- **412 retry jitter**: add a random 1–3 s delay before the single re-try
+  `doCycle` call that follows a `PRECONDITION_FAILED` response. Two clients
+  polling on similar 60 s schedules previously collided on every cycle; the
+  jitter breaks the lock-step pattern.
+- **412 retry backoff**: when the one-shot retry itself fails, apply the same
+  exponential backoff (`downloadErrorCount` / `downloadBackoffUntil`) used for
+  all other transient errors, emit an `'error'` status, and call `onError`.
+  Previously the engine silently returned, which caused it to hammer the server
+  again on the very next 60 s poll.
+
+## [1.0.0] - 2026-05-17
+
+Initial stable release. Extracted from dayGLANCE and made app-agnostic so the
+entire sync infrastructure can be shared across the GLANCE app family.
+
+### Added
+
+- `createSyncEngine(config)` — orchestrates the download → validate → merge →
+  apply → upload cycle. Supports WebDAV, Nextcloud, and Koofr providers.
+  Backoff on auth failures, 423 Locked, and network errors. Hard-stop on
+  `APP_ID_MISMATCH` and `SCHEMA_FORWARD_INCOMPATIBLE`. Fires status events
+  (`uploading`, `downloading`, `success`, `error`, `idle`) with auto-revert
+  timers.
+- `mergeArrayById`, `mergeDailyNotes`, `mergeHabits`, `mergeHabitLogs`,
+  `mergeRoutineDefinitions`, `mergeSyncData`, `pruneTombstones` — ID-based
+  merge engine with tombstone propagation and sync-horizon zombie suppression.
+- `encryptData`, `decryptData`, `setupEncryptionKey`, `clearEncryptionKey`,
+  `initSessionKey`, `setSyncPassphrase`, `getSyncPassphrase`,
+  `hasEncryptionReady`, `isEncryptedEnvelope` — client-side AES-256-GCM
+  encryption via Web Crypto API. Key derived with PBKDF2 and persisted in
+  IndexedDB or via native Android Keystore bridge.
+- `webdavFetch(config)` — transport-selecting WebDAV fetcher (Android HTTP
+  bridge → Electron net.fetch → server-side CORS proxy).
+- `createProviders(config)` — cloud sync provider objects for Nextcloud, Koofr,
+  and generic WebDAV.
+- `createAutoBackupDB(config)` and `createAutoBackupProviders(config)` —
+  periodic snapshot backups to local IndexedDB and remote WebDAV folders.
+- `AUTO_BACKUP_RETENTION` and `AUTO_BACKUP_INTERVALS` constants.
+- TypeScript declarations in `types/index.d.ts`.
+- WebDAV CORS proxy handler in `api/webdav-proxy.js`.
+
+[Unreleased]: https://github.com/glance-apps/glance-sync/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/glance-apps/glance-sync/releases/tag/v1.0.0

package/README.md

@@ -1,2 +1,176 @@
-# glance-sync
+# @glance-apps/sync
+
 Shared sync engine for the GLANCE app family (dayGLANCE, lifeGLANCE, lastGLANCE). WebDAV transport, AES-256-GCM encryption, conflict-free merge.
+
+## Installation
+
+```bash
+npm install @glance-apps/sync
+```
+
+## Usage
+
+### Initialize the sync engine
+
+```js
+import { createSyncEngine } from '@glance-apps/sync';
+
+const engine = createSyncEngine({
+  // Identity
+  appId: 'com.example.myapp',
+  appName: 'MyApp',
+  storageKeyPrefix: 'myapp',
+  syncFilename: 'myapp-sync.json',
+  appFolderName: 'myapp',
+  cryptoDBName: 'myapp-crypto',
+  autoBackupDBName: 'myapp-auto-backups',
+  backupFilenamePrefix: 'myapp-backup-',
+
+  // Transport (browser web app — routes through server-side CORS proxy)
+  nativeHttpRequest: null,
+  electronProxyFetch: null,
+  proxyUrl: 'https://your-app.example.com',
+
+  // Data lifecycle
+  buildPayload: () => ({ tasks: store.getTasks(), notes: store.getNotes() }),
+  applyPayload: (data) => store.replaceAll(data),
+  mergePayloads: (local, remote) => mergeSyncData(local, remote),
+
+  // Status callbacks
+  onStatusChange: (status) => ui.setSyncStatus(status),
+  onError: (message, code, isHardStop) => ui.showError(message),
+  onLastSyncedChange: (iso) => ui.setLastSynced(iso),
+  onConflict: (remoteData, remoteModified, etag) => ui.showConflictDialog(remoteData),
+  onPassphraseRequired: () => ui.promptPassphrase(),
+});
+```
+
+### Perform a sync cycle
+
+The engine distinguishes between upload (local → remote) and download (download → merge → apply → upload if changed). Call `engine.sync()` for the full cycle:
+
+```js
+// Wire to local data changes (typically with a debounce)
+store.on('change', debounce(() => engine.upload(), 5000));
+
+// Wire to a periodic poll or visibility event
+setInterval(() => engine.sync(), 60_000);
+document.addEventListener('visibilitychange', () => {
+  if (document.visibilityState === 'visible') engine.sync();
+});
+```
+
+### Handle first-sync conflicts
+
+On the first sync, if the remote file already exists, the engine surfaces the conflict rather than auto-merging:
+
+```js
+const engine = createSyncEngine({
+  // ...
+  onConflict: async (remoteData, remoteModified, etag) => {
+    const choice = await ui.askUser('Remote data exists. Keep local or remote?');
+    if (choice === 'remote') {
+      store.replaceAll(remoteData);
+      engine.setConfig({ ...engine.getConfig(), lastSynced: remoteModified });
+    }
+    // Either way, proceed with an upload to stamp the chosen data
+    engine.upload();
+  },
+});
+```
+
+### Set up encryption
+
+```js
+import { initSessionKey, setupEncryptionKey, setSyncPassphrase } from '@glance-apps/sync';
+
+const cryptoConfig = { cryptoDBName: 'myapp-crypto' };
+
+// On app start: try to restore key from device storage
+const restored = await initSessionKey(cryptoConfig);
+if (!restored) {
+  // Prompt user for passphrase
+  const passphrase = await ui.promptPassphrase();
+  setSyncPassphrase(passphrase);
+  await setupEncryptionKey(passphrase, cryptoConfig);
+}
+```
+
+Pass `encryptionEnabled: true` in the sync config object stored via `engine.setConfig()` to enable encryption for uploads.
+
+## Public API
+
+### Sync engine
+
+| Export | Description |
+|--------|-------------|
+| `createSyncEngine(config)` | Creates a sync engine instance bound to the given app/transport/data config. Returns a `SyncEngine` object. |
+| `SCHEMA_VERSION` | Current envelope schema version written into every upload. |
+| `SUPPORTED_MAX_SCHEMA_VERSION` | Highest schema version this build can read; downloads with a higher version trigger `SCHEMA_FORWARD_INCOMPATIBLE`. |
+
+**`SyncEngine` methods:**
+
+| Method | Description |
+|--------|-------------|
+| `sync()` / `download()` | Full cycle: download → validate → merge → apply → upload if changed. |
+| `upload(opts?)` | Upload local state to the remote provider. |
+| `runBackup(frequency)` | Save a snapshot to IDB and upload it to the remote backup folder. |
+| `test(config)` | Test the connection to the configured provider. |
+| `getConfig()` / `setConfig(cfg)` | Read/write the persisted sync config (credentials, provider, flags). |
+| `getLastSynced()` | ISO 8601 timestamp of the last successful sync. |
+| `isSyncing()` | Returns `true` while a sync cycle is in progress. |
+| `isHardStopped()` / `clearHardStop()` | Query or clear the hard-stop flag (set on `APP_ID_MISMATCH` or `SCHEMA_FORWARD_INCOMPATIBLE`). |
+| `hasEncryptionReady()` | Returns `true` if a session key is loaded and encryption is available. |
+| `getUploadBackoffUntil()` / `getDownloadBackoffUntil()` | Epoch ms timestamp before which the next upload/download should not be attempted. |
+
+### Merge functions
+
+| Export | Description |
+|--------|-------------|
+| `mergeArrayById(local, remote, deletedIds, syncHorizon?, opts?)` | Generic array merge by item ID with tombstone support. |
+| `mergeDailyNotes(local, remote)` | Merge date-keyed note maps; newer `lastModified` wins per key. |
+| `mergeHabits(local, remote, localDeleted?, remoteDeleted?)` | Merge habit arrays with unified tombstones. |
+| `mergeHabitLogs(local, remote, localTs?, remoteTs?)` | Merge date-keyed habit log maps; last-writer-wins per entry when timestamps are available. |
+| `mergeRoutineDefinitions(local, remote, deletedChipIds?)` | Merge routine definitions (bucket → chip array) with tombstone support. |
+| `mergeSyncData(local, remote, retentionDays?)` | Full data-level merge for the dayGLANCE payload shape. |
+| `pruneTombstones(tombstones, cutoff)` | Remove tombstone entries older than the cutoff date. |
+
+### Crypto
+
+| Export | Description |
+|--------|-------------|
+| `initSessionKey(config)` | Restore session key from device storage (IDB or native bridge). Returns `true` if key was restored. |
+| `setupEncryptionKey(passphrase, config)` | First-time setup: derive a key from the passphrase and persist it. |
+| `clearEncryptionKey(config)` | Erase the cached key from device storage and session memory. |
+| `encryptData(data, config?)` | Encrypt a plain JS object and return an `EncryptedEnvelope`. |
+| `decryptData(envelope, config?)` | Decrypt an `EncryptedEnvelope` back to a plain JS object. |
+| `isEncryptedEnvelope(value)` | Type guard — returns `true` if the value looks like an `EncryptedEnvelope`. |
+| `setSyncPassphrase(p)` / `getSyncPassphrase()` | Store/retrieve the passphrase in session memory (not persisted). |
+| `hasEncryptionReady()` | Returns `true` if the session key is loaded. |
+| `getSessionKey()` | Returns the cached non-extractable `CryptoKey`, or `null` if no key is loaded — intended for sibling packages (e.g., `@glance-apps/intents`) that need to reuse the same key. |
+
+### Transport & providers
+
+| Export | Description |
+|--------|-------------|
+| `webdavFetch(config)` | Creates a transport-selecting WebDAV fetcher. Prefers Android HTTP bridge → Electron proxy → CORS proxy, in that order. |
+| `createProviders(config)` | Creates cloud sync provider objects (`nextcloud`, `koofr`, `webdav`). |
+
+### Auto-backup
+
+| Export | Description |
+|--------|-------------|
+| `createAutoBackupDB(config)` | Creates an IndexedDB-backed local backup store. |
+| `createAutoBackupProviders(config)` | Creates remote backup provider objects for Nextcloud and generic WebDAV. |
+| `AUTO_BACKUP_RETENTION` | Default retention limits: `{ hourly: 24, daily: 30, weekly: 12 }`. |
+| `AUTO_BACKUP_INTERVALS` | Interval seconds: `{ hourly: 3600, daily: 86400, weekly: 604800 }`. |
+
+TypeScript declarations for all of the above are in `types/index.d.ts`.
+
+## Versioning
+
+This package is at **v1.0.0** and follows [Semantic Versioning](https://semver.org/). Breaking changes to the public API or the sync envelope schema will result in a major version bump.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glance-apps/sync",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "license": "MIT",
   "type": "module",
   "main": "src/index.js",
@@ -10,10 +10,12 @@
     "api",
     "types",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "prepublishOnly": "npm test"
   },
   "repository": {
     "type": "git",

package/src/crypto.js

@@ -17,6 +17,7 @@ let _sessionSalt = null;       // Uint8Array | null — the salt used to derive
 export function setSyncPassphrase(p) { _sessionPassphrase = p; }
 export function getSyncPassphrase()  { return _sessionPassphrase; }
 export function hasEncryptionReady() { return _sessionKey !== null; }
+export function getSessionKey()      { return _sessionKey; }
 
 // ---------------------------------------------------------------------------
 // IndexedDB key store

package/src/engine.js

@@ -411,7 +411,10 @@ export const createSyncEngine = (config) => {
       }
 
       if (cls.code === 'PRECONDITION_FAILED') {
-        // Another device wrote between our download and upload — retry once.
+        // Another device wrote between our download and upload — wait a random
+        // jitter (1–3 s) to reduce collision probability, then retry once.
+        const jitterMs = 1000 + Math.random() * 2000;
+        await new Promise(r => setTimeout(r, jitterMs));
         try {
           await doCycle(null);
           downloadErrorCount = 0;
@@ -419,6 +422,14 @@ export const createSyncEngine = (config) => {
         } catch (retryErr) {
           // eslint-disable-next-line no-console
           console.error(`[${appId}] cloud sync retry after 412 failed:`, retryErr);
+          // Apply the same exponential backoff used for other transient errors so
+          // the engine backs off rather than hammering the server every poll cycle.
+          downloadErrorCount += 1;
+          const ms = Math.min(30 * Math.pow(2, downloadErrorCount - 1), MAX_DOWNLOAD_BACKOFF_S) * 1000;
+          downloadBackoffUntil = Date.now() + ms;
+          onError?.(formatErrorMessage(classifyError(retryErr)), classifyError(retryErr).code, false);
+          onStatusChange?.('error');
+          scheduleAutoRevert('error', ERROR_HOLD_MS);
         }
         return;
       }

package/src/index.js

@@ -16,6 +16,7 @@ export {
   getSyncPassphrase,
   clearEncryptionKey,
   hasEncryptionReady,
+  getSessionKey,
   isEncryptedEnvelope,
   initSessionKey,
 } from './crypto.js';

package/types/index.d.ts

@@ -155,6 +155,7 @@ export function clearEncryptionKey(config: CryptoConfig): Promise<void>;
 export function setSyncPassphrase(passphrase: string | null): void;
 export function getSyncPassphrase(): string | null;
 export function hasEncryptionReady(): boolean;
+export function getSessionKey(): CryptoKey | null;
 export function encryptData<T>(data: T, config?: CryptoConfig): Promise<EncryptedEnvelope>;
 export function decryptData<T = unknown>(envelope: EncryptedEnvelope, config?: CryptoConfig): Promise<T>;
 export function isEncryptedEnvelope(value: unknown): value is EncryptedEnvelope;