health-sync 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Filipe Almeida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,30 +1,161 @@
-# health-sync Node Port
+# health-sync
 
-This directory contains a Node.js implementation of `health-sync` with parity-oriented features:
+`health-sync` is an open-source CLI that pulls health and fitness data from multiple providers and stores it in a local SQLite database.
 
-- CLI commands: `init`, `init-db`, `auth`, `sync`, `providers`, `status`
-- SQLite storage (`records`, `sync_state`, `oauth_tokens`, `sync_runs`)
-- Built-in providers: Oura, Withings, Hevy, Strava, Eight Sleep
-- Plugin loading from package metadata (`healthSyncProviders`) and `[plugins.<id>] module=...`
+It is designed as a personal data cache: first sync backfills history, then future syncs fetch incremental updates.
 
-## Install
+## Purpose
+
+- Keep your health data in one local database you control.
+- Build your own dashboards, analysis scripts, or exports on top of raw provider data.
+- Avoid building one-off sync scripts for each provider.
+
+## Supported Providers
+
+- Oura (Cloud API v2, OAuth2)
+- Withings (Advanced Health Data API, OAuth2)
+- Hevy (public API, API key, Pro account required)
+- Strava (OAuth2 or static access token)
+- Eight Sleep (unofficial API)
+
+## Requirements
+
+- Node.js 20+
+- SQLite (bundled through `better-sqlite3`)
+- Provider credentials (API key and/or OAuth client settings depending on provider)
+
+## Installation
+
+Install globally from npm:
+
+```bash
+npm install -g health-sync
+```
+
+Or run from this repository:
 
 ```bash
-cd node
 npm install
+npm link
+```
+
+## Quick Start
+
+1. Initialize config and DB:
+
+```bash
+health-sync init
+```
+
+2. Edit `health-sync.toml`:
+- Set `[app].db` if you do not want `./health.sqlite`
+
+3. Run provider auth one provider at a time:
+
+```bash
+health-sync auth oura
+health-sync auth withings
+health-sync auth strava
+health-sync auth eightsleep
 ```
 
-## Run
+4. Sync data:
 
 ```bash
-npm start -- --config ../health-sync.toml providers --verbose
-npm start -- --config ../health-sync.toml status
+health-sync sync
 ```
 
-## CLI
+5. Inspect sync state and counts:
 
 ```bash
-health-sync [--config path] [--db path] <command> [options]
+health-sync status
 ```
 
-Use the same `health-sync.toml` format as the Python implementation.
+## Basic Configuration
+
+By default, `health-sync` reads `./health-sync.toml`.
+
+Use a custom config file with:
+
+```bash
+health-sync --config /path/to/health-sync.toml sync
+```
+
+Minimal example:
+
+```toml
+[app]
+db = "./health.sqlite"
+
+[hevy]
+enabled = true
+api_key = "YOUR_HEVY_API_KEY"
+
+[strava]
+enabled = true
+client_id = "YOUR_CLIENT_ID"
+client_secret = "YOUR_CLIENT_SECRET"
+redirect_uri = "http://127.0.0.1:8486/callback"
+```
+
+See `health-sync.example.toml` for all provider options.
+
+## CLI Commands
+
+- `health-sync init`: create a scaffolded config (from `health-sync.example.toml`) and create DB tables
+- `health-sync init-db`: create DB tables only (legacy)
+- `health-sync auth <provider>`: run auth flow for one provider/plugin
+- `health-sync sync`: run sync for all enabled providers
+- `health-sync sync --providers oura strava`: sync only selected providers
+- `health-sync providers`: list discovered providers and whether they are enabled
+- `health-sync status`: print watermarks, record counts, and recent runs
+
+`auth` notes:
+
+- Oura, Withings, and Strava: OAuth flow (CLI prints auth URL and waits for callback URL/code).
+- Eight Sleep: username/password grant (or static token).
+- Hevy: no `auth` command; configure `[hevy].api_key` directly.
+
+`auth` also scaffolds the provider section in `health-sync.toml` (enables it and, for Eight Sleep, writes default client id/secret if missing).
+
+Global flags:
+
+- `--config`: config file path
+- `--db`: override SQLite DB path
+
+## Data Storage
+
+The database keeps raw JSON payloads and sync metadata in generic tables:
+
+- `records`: provider/resource records
+- `sync_state`: per-resource watermarks/cursors
+- `.health-sync.creds`: stored provider credentials and OAuth tokens
+- `sync_runs`: run history and per-sync counters
+
+This schema is intentionally generic so upstream API changes are less likely to require migrations.
+
+## Optional Plugin System
+
+You can add external providers as in-process plugins.
+
+- Discover installed plugins with `health-sync providers`
+- Configure plugin blocks under `[plugins.<id>]`
+- Enable them with `[plugins.<id>].enabled = true`
+
+## Notes
+
+- Eight Sleep integration uses unofficial endpoints and may break if the upstream API changes.
+- Some providers use overlap windows to ensure incremental sync correctness.
+
+## Development
+
+Run checks and tests:
+
+```bash
+npm run check
+npm test
+```
+
+## License
+
+MIT. See `LICENSE`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "health-sync",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Node.js port of health-sync",
   "files": [

package/src/cli.js

@@ -7,6 +7,7 @@ import {
 import { openDb } from './db.js';
 import { PluginHelpers, providerEnabled } from './plugins/base.js';
 import { loadProviders } from './plugins/loader.js';
+import { setRequestJsonVerbose } from './util.js';
 
 const DEFAULT_CONFIG_PATH = 'health-sync.toml';
 
@@ -84,6 +85,12 @@ function parseAuthArgs(args) {
       throw new Error(`Unknown auth option: ${arg}`);
     }
     if (!out.provider) {
+      if (arg === '-h' || arg === '--help') {
+        throw new Error('auth requires PROVIDER argument (e.g. health-sync auth oura)');
+      }
+      if (arg.startsWith('-')) {
+        throw new Error(`Invalid provider id: ${arg}`);
+      }
       out.provider = arg;
       continue;
     }
@@ -98,17 +105,24 @@ function parseAuthArgs(args) {
 }
 
 function parseSyncArgs(args) {
-  const providers = [];
+  const out = {
+    providers: [],
+    verbose: false,
+  };
 
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
+    if (arg === '-v' || arg === '--verbose') {
+      out.verbose = true;
+      continue;
+    }
     if (arg === '--providers') {
       let consumed = false;
       while (i + 1 < args.length && !args[i + 1].startsWith('-')) {
         consumed = true;
         const raw = args[i + 1];
         for (const piece of String(raw).split(',').map((v) => v.trim()).filter(Boolean)) {
-          providers.push(piece);
+          out.providers.push(piece);
         }
         i += 1;
       }
@@ -120,16 +134,14 @@ function parseSyncArgs(args) {
     if (arg.startsWith('--providers=')) {
       const raw = arg.slice('--providers='.length);
       for (const piece of raw.split(',').map((v) => v.trim()).filter(Boolean)) {
-        providers.push(piece);
+        out.providers.push(piece);
       }
       continue;
     }
     throw new Error(`Unknown sync option: ${arg}`);
   }
 
-  return {
-    providers,
-  };
+  return out;
 }
 
 function parseProvidersArgs(args) {
@@ -196,6 +208,10 @@ function resolveDbPath(overrideDbPath, loadedConfig) {
   return './health.sqlite';
 }
 
+function resolveCredsPath(configPath) {
+  return path.join(path.dirname(path.resolve(configPath)), '.health-sync.creds');
+}
+
 function enableHint(providerId) {
   const builtin = new Set(['oura', 'withings', 'hevy', 'strava', 'eightsleep']);
   if (builtin.has(providerId)) {
@@ -214,7 +230,7 @@ function usage() {
     '  auth <provider>               Run provider authentication flow',
     '    --listen-host <host>        OAuth callback listen host (default 127.0.0.1)',
     '    --listen-port <port>        OAuth callback listen port (default 0 -> config redirect port)',
-    '  sync [--providers a,b,c]      Sync enabled providers',
+    '  sync [--providers a,b,c] [-v|--verbose]  Sync enabled providers',
     '  providers [--verbose]         List discovered providers',
     '  status                        Show sync state, counts, and recent runs',
   ].join('\n');
@@ -236,11 +252,13 @@ async function loadContext(configPath) {
 
 async function cmdInit(parsed) {
   const configPath = path.resolve(parsed.configPath);
+  const explicitDbPath = parsed.dbPath ? String(parsed.dbPath) : null;
+
+  initConfigFile(configPath, explicitDbPath);
+
   const loaded = loadConfig(configPath);
   const dbPath = resolveDbPath(parsed.dbPath, loaded);
-
-  initConfigFile(configPath, dbPath);
-  const db = openDb(dbPath);
+  const db = openDb(dbPath, { credsPath: resolveCredsPath(configPath) });
   db.close();
 
   console.log(`Initialized config: ${configPath}`);
@@ -253,7 +271,7 @@ async function cmdInitDb(parsed) {
   const loaded = loadConfig(configPath);
   const dbPath = resolveDbPath(parsed.dbPath, loaded);
 
-  const db = openDb(dbPath);
+  const db = openDb(dbPath, { credsPath: resolveCredsPath(configPath) });
   db.close();
   console.log(`Initialized database: ${path.resolve(dbPath)}`);
   return 0;
@@ -261,14 +279,17 @@ async function cmdInitDb(parsed) {
 
 async function cmdAuth(parsed) {
   const configPath = path.resolve(parsed.configPath);
+  const explicitDbPath = parsed.dbPath ? String(parsed.dbPath) : null;
+
+  initConfigFile(configPath, explicitDbPath);
+
   const loaded = loadConfig(configPath);
   const dbPath = resolveDbPath(parsed.dbPath, loaded);
-  initConfigFile(configPath, dbPath);
 
   scaffoldProviderConfig(configPath, parsed.options.provider);
 
   const context = await loadContext(configPath);
-  const db = openDb(dbPath);
+  const db = openDb(dbPath, { credsPath: resolveCredsPath(configPath) });
 
   try {
     const plugin = context.providers.get(parsed.options.provider);
@@ -304,7 +325,8 @@ async function cmdSync(parsed) {
   const configPath = path.resolve(parsed.configPath);
   const context = await loadContext(configPath);
   const dbPath = resolveDbPath(parsed.dbPath, context.loadedConfig);
-  const db = openDb(dbPath);
+  const db = openDb(dbPath, { credsPath: resolveCredsPath(configPath) });
+  const previousVerboseLogging = setRequestJsonVerbose(parsed.options.verbose);
 
   try {
     const discoveredIds = Array.from(context.providers.keys()).sort();
@@ -353,6 +375,7 @@ async function cmdSync(parsed) {
     let successes = 0;
     const failures = [];
     for (const providerId of toSync) {
+      console.log(`Syncing provider: ${providerId}`);
       try {
         await context.providers.get(providerId).sync(db, context.loadedConfig.data, context.helpers, {
           configPath,
@@ -378,6 +401,7 @@ async function cmdSync(parsed) {
 
     return 0;
   } finally {
+    setRequestJsonVerbose(previousVerboseLogging);
     db.close();
   }
 }
@@ -409,7 +433,7 @@ async function cmdStatus(parsed) {
   const configPath = path.resolve(parsed.configPath);
   const loadedConfig = loadConfig(configPath);
   const dbPath = resolveDbPath(parsed.dbPath, loadedConfig);
-  const db = openDb(dbPath);
+  const db = openDb(dbPath, { credsPath: resolveCredsPath(configPath) });
 
   try {
     const syncState = db.listSyncState();

package/src/config.js

@@ -1,7 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import TOML from '@iarna/toml';
 
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const EXAMPLE_CONFIG_PATH = path.resolve(MODULE_DIR, '../health-sync.example.toml');
+
 const BUILTIN_DEFAULTS = {
   app: {
     db: './health.sqlite',
@@ -268,10 +272,43 @@ function writeToml(filePath, rawDoc) {
   fs.writeFileSync(filePath, rendered, 'utf8');
 }
 
-export function initConfigFile(configPath, dbPath) {
+function readExampleConfigTemplate() {
+  if (fs.existsSync(EXAMPLE_CONFIG_PATH)) {
+    return fs.readFileSync(EXAMPLE_CONFIG_PATH, 'utf8');
+  }
+  return TOML.stringify(defaultConfig());
+}
+
+function renderScaffoldConfig(dbPath = null) {
+  const template = readExampleConfigTemplate();
+  if (!dbPath) {
+    return template;
+  }
+
+  const dbLine = `db = ${JSON.stringify(String(dbPath))}`;
+  if (template.includes('# db = "./health.sqlite"')) {
+    return template.replace('# db = "./health.sqlite"', dbLine);
+  }
+  if (template.includes('[app]')) {
+    return template.replace('[app]', `[app]\n${dbLine}`);
+  }
+  return `[app]\n${dbLine}\n\n${template}`;
+}
+
+export function initConfigFile(configPath, dbPath = null) {
   const resolved = path.resolve(configPath);
-  const raw = fs.existsSync(resolved) ? TOML.parse(fs.readFileSync(resolved, 'utf8')) : {};
-  upsertSectionValues(raw, ['app'], { db: dbPath || BUILTIN_DEFAULTS.app.db });
+
+  if (!fs.existsSync(resolved)) {
+    fs.writeFileSync(resolved, renderScaffoldConfig(dbPath), 'utf8');
+    return;
+  }
+
+  if (!dbPath) {
+    return;
+  }
+
+  const raw = TOML.parse(fs.readFileSync(resolved, 'utf8'));
+  upsertSectionValues(raw, ['app'], { db: dbPath });
   writeToml(resolved, raw);
 }
 
@@ -286,23 +323,34 @@ function scaffoldBuiltinDefaults(providerId) {
   };
 }
 
+const PROVIDER_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+function assertValidProviderId(providerId) {
+  const normalized = String(providerId || '').trim();
+  if (!normalized || !PROVIDER_ID_RE.test(normalized)) {
+    throw new Error(`Invalid provider id: ${providerId}`);
+  }
+  return normalized;
+}
+
 export function scaffoldProviderConfig(configPath, providerId) {
+  const normalizedProviderId = assertValidProviderId(providerId);
   const resolved = path.resolve(configPath);
   const raw = fs.existsSync(resolved) ? TOML.parse(fs.readFileSync(resolved, 'utf8')) : {};
 
-  const builtinDefaults = scaffoldBuiltinDefaults(providerId);
+  const builtinDefaults = scaffoldBuiltinDefaults(normalizedProviderId);
   if (builtinDefaults) {
-    const sectionRaw = section(raw, providerId);
+    const sectionRaw = section(raw, normalizedProviderId);
     const merged = { ...builtinDefaults, ...sectionRaw, enabled: true };
-    upsertSectionValues(raw, [providerId], merged);
+    upsertSectionValues(raw, [normalizedProviderId], merged);
   } else {
     const pluginsRaw = section(raw, 'plugins');
-    const pluginRaw = section(pluginsRaw, providerId);
+    const pluginRaw = section(pluginsRaw, normalizedProviderId);
     const merged = { ...pluginRaw, enabled: true };
     if (!pluginRaw.module) {
       merged.module = pluginRaw.module ?? null;
     }
-    upsertSectionValues(raw, ['plugins', providerId], merged);
+    upsertSectionValues(raw, ['plugins', normalizedProviderId], merged);
   }
 
   writeToml(resolved, raw);

package/src/db.js

@@ -1,3 +1,4 @@
+import fs from 'node:fs';
 import path from 'node:path';
 import Database from 'better-sqlite3';
 import {
@@ -70,13 +71,18 @@ function normalizeWatermark(value) {
 }
 
 export class HealthSyncDb {
-  constructor(dbPath) {
+  constructor(dbPath, options = {}) {
     this.path = path.resolve(dbPath);
+    this.credsPath = path.resolve(
+      options.credsPath || path.join(path.dirname(this.path), '.health-sync.creds'),
+    );
     this.conn = new Database(this.path);
     this.conn.pragma('journal_mode = WAL');
     this.conn.pragma('foreign_keys = ON');
     this._runStatsStack = [];
     this._transactionDepth = 0;
+    this._oauthMigrated = false;
+    this._credsParseWarned = false;
   }
 
   close() {
@@ -148,6 +154,7 @@ export class HealthSyncDb {
     `);
 
     this._normalizeLegacyTimestamps();
+    this._migrateOAuthTokensToCredsFile();
   }
 
   _normalizeLegacyTimestamps() {
@@ -178,6 +185,176 @@ export class HealthSyncDb {
     }
   }
 
+  _readCredsDoc() {
+    if (!fs.existsSync(this.credsPath)) {
+      return { version: 1, tokens: {} };
+    }
+
+    try {
+      const parsed = JSON.parse(fs.readFileSync(this.credsPath, 'utf8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return { version: 1, tokens: {} };
+      }
+
+      const tokens = (parsed.tokens && typeof parsed.tokens === 'object' && !Array.isArray(parsed.tokens))
+        ? parsed.tokens
+        : {};
+
+      return {
+        version: 1,
+        updatedAt: normalizeTimestamp(parsed.updatedAt || parsed.updated_at) || null,
+        tokens,
+      };
+    } catch {
+      if (!this._credsParseWarned) {
+        console.warn(`Ignoring invalid JSON in ${this.credsPath}`);
+        this._credsParseWarned = true;
+      }
+      return { version: 1, tokens: {} };
+    }
+  }
+
+  _writeCredsDoc(doc) {
+    const normalized = {
+      version: 1,
+      updatedAt: utcNowIso(),
+      tokens: doc?.tokens && typeof doc.tokens === 'object' && !Array.isArray(doc.tokens)
+        ? doc.tokens
+        : {},
+    };
+
+    fs.mkdirSync(path.dirname(this.credsPath), { recursive: true });
+    const tempPath = `${this.credsPath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tempPath, `${stableJsonStringify(normalized)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+    });
+    fs.renameSync(tempPath, this.credsPath);
+    try {
+      fs.chmodSync(this.credsPath, 0o600);
+    } catch {
+      // Ignore chmod failures on filesystems that do not support POSIX modes.
+    }
+  }
+
+  _normalizeStoredToken(provider, rawToken, contextLabel = `.health-sync.creds.${provider}`) {
+    if (!rawToken || typeof rawToken !== 'object' || Array.isArray(rawToken)) {
+      return null;
+    }
+
+    const accessTokenValue = rawToken.accessToken ?? rawToken.access_token;
+    if (accessTokenValue === null || accessTokenValue === undefined || String(accessTokenValue).trim() === '') {
+      return null;
+    }
+
+    let extra = rawToken.extra ?? null;
+    if (extra === null && typeof rawToken.extra_json === 'string') {
+      extra = jsonLoadsOrNull(rawToken.extra_json, `${contextLabel}.extra_json`);
+    }
+
+    return {
+      provider,
+      accessToken: String(accessTokenValue),
+      refreshToken: rawToken.refreshToken ?? rawToken.refresh_token ?? null,
+      tokenType: rawToken.tokenType ?? rawToken.token_type ?? null,
+      scope: rawToken.scope ?? null,
+      expiresAt: normalizeTimestamp(rawToken.expiresAt ?? rawToken.expires_at),
+      obtainedAt: normalizeTimestamp(rawToken.obtainedAt ?? rawToken.obtained_at),
+      extra,
+    };
+  }
+
+  _listLegacyOAuthTokens() {
+    let rows = [];
+    try {
+      rows = this.conn.prepare('SELECT * FROM oauth_tokens ORDER BY provider ASC').all();
+    } catch {
+      rows = [];
+    }
+
+    const out = {};
+    for (const row of rows) {
+      const normalized = this._normalizeStoredToken(
+        row.provider,
+        {
+          access_token: row.access_token,
+          refresh_token: row.refresh_token,
+          token_type: row.token_type,
+          scope: row.scope,
+          expires_at: row.expires_at,
+          obtained_at: row.obtained_at,
+          extra_json: row.extra_json,
+        },
+        `oauth_tokens.${row.provider}`,
+      );
+      if (normalized) {
+        out[row.provider] = normalized;
+      }
+    }
+
+    return out;
+  }
+
+  _upsertCredsToken(provider, token) {
+    const doc = this._readCredsDoc();
+    const tokens = {
+      ...(doc.tokens || {}),
+      [provider]: {
+        accessToken: token.accessToken,
+        refreshToken: token.refreshToken,
+        tokenType: token.tokenType,
+        scope: token.scope,
+        expiresAt: token.expiresAt,
+        obtainedAt: token.obtainedAt,
+        extra: token.extra,
+      },
+    };
+    this._writeCredsDoc({ ...doc, tokens });
+  }
+
+  _migrateOAuthTokensToCredsFile() {
+    if (this._oauthMigrated) {
+      return;
+    }
+    this._oauthMigrated = true;
+
+    const legacyTokens = this._listLegacyOAuthTokens();
+    if (!Object.keys(legacyTokens).length) {
+      return;
+    }
+
+    const doc = this._readCredsDoc();
+    const tokens = { ...(doc.tokens || {}) };
+    let changed = false;
+
+    for (const [provider, token] of Object.entries(legacyTokens)) {
+      const existing = this._normalizeStoredToken(provider, tokens[provider]);
+      if (existing) {
+        continue;
+      }
+      tokens[provider] = {
+        accessToken: token.accessToken,
+        refreshToken: token.refreshToken,
+        tokenType: token.tokenType,
+        scope: token.scope,
+        expiresAt: token.expiresAt,
+        obtainedAt: token.obtainedAt,
+        extra: token.extra,
+      };
+      changed = true;
+    }
+
+    const nextDoc = changed ? { ...doc, tokens } : doc;
+    if (changed) {
+      this._writeCredsDoc(nextDoc);
+    }
+
+    const migratedProviders = Object.keys(legacyTokens)
+      .filter((provider) => this._normalizeStoredToken(provider, nextDoc.tokens?.[provider]));
+    for (const provider of migratedProviders) {
+      this.conn.prepare('DELETE FROM oauth_tokens WHERE provider = ?').run(provider);
+    }
+  }
   _incrementRunStats(stats, op) {
     if (!stats) {
       return;
@@ -356,22 +533,43 @@ export class HealthSyncDb {
   }
 
   getOAuthToken(provider) {
+    this._migrateOAuthTokensToCredsFile();
+
+    const fromCreds = this._normalizeStoredToken(
+      provider,
+      this._readCredsDoc().tokens?.[provider],
+    );
+    if (fromCreds) {
+      return fromCreds;
+    }
+
     const row = this.conn
       .prepare('SELECT * FROM oauth_tokens WHERE provider = ?')
       .get(provider);
     if (!row) {
       return null;
     }
-    return {
-      provider: row.provider,
-      accessToken: row.access_token,
-      refreshToken: row.refresh_token,
-      tokenType: row.token_type,
-      scope: row.scope,
-      expiresAt: normalizeTimestamp(row.expires_at),
-      obtainedAt: normalizeTimestamp(row.obtained_at),
-      extra: jsonLoadsOrNull(row.extra_json, `oauth_tokens.${provider}.extra_json`),
-    };
+
+    const legacy = this._normalizeStoredToken(
+      provider,
+      {
+        access_token: row.access_token,
+        refresh_token: row.refresh_token,
+        token_type: row.token_type,
+        scope: row.scope,
+        expires_at: row.expires_at,
+        obtained_at: row.obtained_at,
+        extra_json: row.extra_json,
+      },
+      `oauth_tokens.${provider}`,
+    );
+    if (!legacy) {
+      return null;
+    }
+
+    this._upsertCredsToken(provider, legacy);
+    this.conn.prepare('DELETE FROM oauth_tokens WHERE provider = ?').run(provider);
+    return legacy;
   }
 
   setOAuthToken(provider, {
@@ -382,36 +580,24 @@ export class HealthSyncDb {
     expiresAt = null,
     extra = null,
   }) {
-    const obtainedAt = utcNowIso();
-    const normalizedExpiresAt = normalizeTimestamp(expiresAt);
-    const extraJson = extra === null || extra === undefined ? null : stableJsonStringify(extra);
-    this.conn.prepare(`
-      INSERT INTO oauth_tokens (
-        provider, access_token, refresh_token, token_type, scope,
-        expires_at, obtained_at, extra_json
-      ) VALUES (
-        @provider, @access_token, @refresh_token, @token_type, @scope,
-        @expires_at, @obtained_at, @extra_json
-      )
-      ON CONFLICT(provider)
-      DO UPDATE SET
-        access_token = excluded.access_token,
-        refresh_token = excluded.refresh_token,
-        token_type = excluded.token_type,
-        scope = excluded.scope,
-        expires_at = excluded.expires_at,
-        obtained_at = excluded.obtained_at,
-        extra_json = excluded.extra_json
-    `).run({
+    if (accessToken === null || accessToken === undefined || String(accessToken).trim() === '') {
+      throw new Error('accessToken is required');
+    }
+
+    this._migrateOAuthTokensToCredsFile();
+
+    const token = {
       provider,
-      access_token: accessToken,
-      refresh_token: refreshToken,
-      token_type: tokenType,
-      scope,
-      expires_at: normalizedExpiresAt,
-      obtained_at: obtainedAt,
-      extra_json: extraJson,
-    });
+      accessToken: String(accessToken),
+      refreshToken: refreshToken === undefined ? null : refreshToken,
+      tokenType: tokenType === undefined ? null : tokenType,
+      scope: scope === undefined ? null : scope,
+      expiresAt: normalizeTimestamp(expiresAt),
+      obtainedAt: utcNowIso(),
+      extra: extra === undefined ? null : extra,
+    };
+
+    this._upsertCredsToken(provider, token);
   }
 
   startSyncRun(provider, resource, watermarkBefore = null) {
@@ -596,8 +782,8 @@ export class HealthSyncDb {
   }
 }
 
-export function openDb(dbPath) {
-  const db = new HealthSyncDb(dbPath);
+export function openDb(dbPath, options = {}) {
+  const db = new HealthSyncDb(dbPath, options);
   db.init();
   return db;
 }

package/src/util.js

@@ -157,6 +157,19 @@ export function parseRetryAfterSeconds(retryAfter) {
   return Math.max(1, Math.ceil((retryAt - Date.now()) / 1000));
 }
 
+let requestJsonVerbose = false;
+
+export function setRequestJsonVerbose(enabled) {
+  const previous = requestJsonVerbose;
+  requestJsonVerbose = Boolean(enabled);
+  return previous;
+}
+
+function logRequestJson(message) {
+  if (requestJsonVerbose) {
+    console.log(message);
+  }
+}
 function buildHttpError(method, url, response, parsedBody, rawText) {
   const detailCandidates = [];
   if (parsedBody && typeof parsedBody === 'object') {
@@ -233,6 +246,7 @@ export async function requestJson(url, options = {}) {
 
   let lastError = null;
   const maxAttempts = Math.max(1, retries);
+  const requestLabel = `${method.toUpperCase()} ${target.toString()}`;
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
     const controller = new AbortController();
     const timeout = setTimeout(() => {
@@ -240,6 +254,7 @@ export async function requestJson(url, options = {}) {
     }, timeoutMs);
 
     try {
+      logRequestJson(`[http] -> ${requestLabel} (attempt ${attempt}/${maxAttempts})`);
       const response = await fetch(target, {
         method,
         headers: requestHeaders,
@@ -248,6 +263,7 @@ export async function requestJson(url, options = {}) {
       });
 
       clearTimeout(timeout);
+      logRequestJson(`[http] <- ${response.status} ${response.statusText} ${requestLabel}`);
 
       const rawText = await response.text();
       let parsedBody = null;
@@ -266,6 +282,7 @@ export async function requestJson(url, options = {}) {
         const delayMs = retryAfterSeconds !== null
           ? Math.min(60000, Math.max(1000, retryAfterSeconds * 1000))
           : Math.min(60000, retryBackoffMs * (2 ** (attempt - 1)));
+        logRequestJson(`[http] retry in ${delayMs}ms (${requestLabel})`);
         await sleep(delayMs);
         continue;
       }
@@ -296,6 +313,7 @@ export async function requestJson(url, options = {}) {
         || error?.cause?.code === 'ETIMEDOUT';
       if (attempt < maxAttempts && retryable) {
         const delayMs = Math.min(60000, retryBackoffMs * (2 ** (attempt - 1)));
+        logRequestJson(`[http] error ${error?.message || String(error)}; retry in ${delayMs}ms (${requestLabel})`);
         await sleep(delayMs);
         continue;
       }