@conversionpros/aiva 1.0.0

package/router-v2/db.js

@@ -0,0 +1,457 @@
+// ── Database Setup, Migrations, Prepared Statements ──────
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const DB_DIR = path.join(__dirname, 'data');
+const DB_PATH = path.join(DB_DIR, 'router-v2.db');
+
+let db = null;
+let stmts = {};
+
+/**
+ * Initialize the database. Creates tables if they don't exist.
+ * Must be called once at startup before any other db operations.
+ * @returns {{ db: import('better-sqlite3').Database, stmts: Object }}
+ */
+function initDatabase() {
+  const Database = require('better-sqlite3');
+  if (!fs.existsSync(DB_DIR)) fs.mkdirSync(DB_DIR, { recursive: true });
+
+  db = new Database(DB_PATH);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+
+  createTables();
+  prepareStatements();
+
+  console.log(`[db] Initialized at ${DB_PATH}`);
+  return { db, stmts };
+}
+
+function createTables() {
+  // ── Contacts ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS contacts (
+      phone TEXT PRIMARY KEY,
+      name TEXT NOT NULL DEFAULT 'Unknown',
+      category TEXT NOT NULL DEFAULT 'unknown',
+      response_mode TEXT NOT NULL DEFAULT 'auto',
+      style TEXT NOT NULL DEFAULT 'casual',
+      instructions TEXT DEFAULT '',
+      source TEXT DEFAULT 'unknown',
+      introduced INTEGER DEFAULT 0,
+      qualification_score INTEGER DEFAULT 0,
+      pipeline_stage TEXT DEFAULT 'none',
+      created_at DATETIME DEFAULT (datetime('now')),
+      updated_at DATETIME DEFAULT (datetime('now'))
+    )
+  `);
+
+  // ── Contact Context ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS contact_context (
+      phone TEXT PRIMARY KEY,
+      relationship TEXT DEFAULT '',
+      last_topic TEXT DEFAULT '',
+      pending_items TEXT DEFAULT '[]',
+      conversation_summary TEXT DEFAULT '',
+      preferences TEXT DEFAULT '{}',
+      last_interaction DATETIME,
+      FOREIGN KEY (phone) REFERENCES contacts(phone) ON DELETE CASCADE
+    )
+  `);
+
+  // ── Contact Scopes ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS contact_scopes (
+      phone TEXT NOT NULL,
+      scope TEXT NOT NULL,
+      granted INTEGER DEFAULT 0,
+      granted_by TEXT DEFAULT 'manual',
+      granted_at DATETIME,
+      PRIMARY KEY (phone, scope)
+    )
+  `);
+
+  // ── Conversation State ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS conversation_state (
+      phone TEXT PRIMARY KEY,
+      state TEXT NOT NULL DEFAULT 'idle',
+      state_data TEXT DEFAULT '{}',
+      entered_at DATETIME DEFAULT (datetime('now')),
+      expires_at DATETIME
+    )
+  `);
+
+  // ── Message Log ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      phone TEXT NOT NULL,
+      channel TEXT DEFAULT 'imessage',
+      direction TEXT NOT NULL DEFAULT 'inbound',
+      text TEXT DEFAULT '',
+      attachments TEXT DEFAULT '[]',
+      sent_by TEXT DEFAULT 'contact',
+      state_at_time TEXT DEFAULT '',
+      created_at DATETIME DEFAULT (datetime('now'))
+    )
+  `);
+
+  // ── FAQ Entries ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS faq_entries (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      device_id TEXT,
+      question TEXT NOT NULL,
+      answer TEXT NOT NULL,
+      category TEXT DEFAULT 'general',
+      keywords TEXT DEFAULT '',
+      enabled INTEGER DEFAULT 1,
+      created_at DATETIME DEFAULT (datetime('now'))
+    )
+  `);
+
+  // ── Playbook Sections ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS playbook_sections (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      device_id TEXT,
+      section_type TEXT NOT NULL,
+      title TEXT DEFAULT '',
+      content TEXT NOT NULL,
+      priority INTEGER DEFAULT 10,
+      enabled INTEGER DEFAULT 1,
+      version INTEGER DEFAULT 1,
+      created_at DATETIME DEFAULT (datetime('now')),
+      updated_at DATETIME DEFAULT (datetime('now'))
+    )
+  `);
+
+  // ── Preferences (Learning Loop) ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS preferences (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      scope TEXT DEFAULT 'global',
+      question_pattern TEXT NOT NULL,
+      answer TEXT NOT NULL,
+      source TEXT DEFAULT 'router',
+      confidence REAL DEFAULT 0.7,
+      hit_count INTEGER DEFAULT 0,
+      last_used_at DATETIME,
+      created_at DATETIME DEFAULT (datetime('now')),
+      updated_at DATETIME DEFAULT (datetime('now'))
+    )
+  `);
+
+  // ── Preference Log (audit trail) ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS preference_log (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      preference_id INTEGER,
+      escalation_id TEXT,
+      phone TEXT,
+      original_question TEXT,
+      tier_resolved TEXT,
+      created_at DATETIME DEFAULT (datetime('now')),
+      FOREIGN KEY (preference_id) REFERENCES preferences(id)
+    )
+  `);
+
+  // ── Escalations ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS escalations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      escalation_id TEXT UNIQUE NOT NULL,
+      phone TEXT NOT NULL,
+      trigger_message TEXT DEFAULT '',
+      context_sent TEXT DEFAULT '{}',
+      response_received TEXT DEFAULT '',
+      status TEXT DEFAULT 'pending',
+      strike_count INTEGER DEFAULT 0,
+      is_client_support INTEGER DEFAULT 0,
+      created_at DATETIME DEFAULT (datetime('now')),
+      responded_at DATETIME,
+      timeout_at DATETIME
+    )
+  `);
+
+  // ── Follow-Up Tracker ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS follow_up_tracker (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      phone TEXT NOT NULL UNIQUE,
+      channel TEXT DEFAULT 'imessage',
+      contact_name TEXT DEFAULT 'Unknown',
+      last_our_message TEXT DEFAULT '',
+      last_our_message_at DATETIME,
+      context_summary TEXT DEFAULT '',
+      follow_up_count INTEGER DEFAULT 0,
+      max_follow_ups INTEGER DEFAULT 3,
+      next_follow_up_at DATETIME,
+      status TEXT DEFAULT 'active',
+      last_follow_up_at DATETIME,
+      last_follow_up_topic TEXT DEFAULT '',
+      opted_out INTEGER DEFAULT 0,
+      created_at DATETIME DEFAULT (datetime('now')),
+      updated_at DATETIME DEFAULT (datetime('now'))
+    )
+  `);
+
+  // ── Scheduling Rules ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS scheduling_rules (
+      category TEXT PRIMARY KEY,
+      rule_preset TEXT DEFAULT 'flexible',
+      custom_instructions TEXT DEFAULT '',
+      structured_overrides TEXT DEFAULT '{}',
+      updated_at DATETIME DEFAULT (datetime('now'))
+    )
+  `);
+
+  // ── Settings ──
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS settings (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    )
+  `);
+
+  // ── Indexes ──
+  const indexes = [
+    'CREATE INDEX IF NOT EXISTS idx_msg_phone ON message_log(phone)',
+    'CREATE INDEX IF NOT EXISTS idx_msg_created ON message_log(created_at)',
+    'CREATE INDEX IF NOT EXISTS idx_msg_direction ON message_log(phone, direction)',
+    'CREATE INDEX IF NOT EXISTS idx_scopes_phone ON contact_scopes(phone)',
+    'CREATE INDEX IF NOT EXISTS idx_escalation_id ON escalations(escalation_id)',
+    'CREATE INDEX IF NOT EXISTS idx_escalation_status ON escalations(status)',
+    'CREATE INDEX IF NOT EXISTS idx_escalation_phone ON escalations(phone)',
+    'CREATE INDEX IF NOT EXISTS idx_followup_status ON follow_up_tracker(status)',
+    'CREATE INDEX IF NOT EXISTS idx_followup_next ON follow_up_tracker(next_follow_up_at)',
+    'CREATE INDEX IF NOT EXISTS idx_faq_device ON faq_entries(device_id)',
+    'CREATE INDEX IF NOT EXISTS idx_playbook_device ON playbook_sections(device_id)',
+    'CREATE INDEX IF NOT EXISTS idx_playbook_type ON playbook_sections(section_type)',
+    'CREATE INDEX IF NOT EXISTS idx_prefs_scope ON preferences(scope)',
+    'CREATE INDEX IF NOT EXISTS idx_prefs_pattern ON preferences(question_pattern)',
+    'CREATE INDEX IF NOT EXISTS idx_conv_state ON conversation_state(state)',
+  ];
+  for (const idx of indexes) {
+    try { db.exec(idx); } catch (e) { /* index may already exist */ }
+  }
+
+  // ── Default Settings ──
+  const defaults = {
+    followUpEnabled: 'true',
+    followUpStartHour: '8',
+    followUpEndHour: '18',
+    maxDailyAutoResponses: '50',
+    maxDailyFollowUps: '10',
+    debounceMs: '3000',
+    escalationNotifyPhone: '+15099794110',
+    sonnetModel: 'claude-sonnet-4-20250514',
+    awayMessage: '',
+    masterPhone: '+15099794110',
+    defaultResponseMode: 'block',
+    imessageDefaultMode: '',
+    whatsappDefaultMode: '',
+    v2DryRun: 'false',
+    calendarAccountId: '',
+  };
+  const setSetting = db.prepare('INSERT OR IGNORE INTO settings (key, value) VALUES (?, ?)');
+  for (const [key, value] of Object.entries(defaults)) {
+    setSetting.run(key, value);
+  }
+
+  // ── Default Scheduling Rules ──
+  const setRule = db.prepare('INSERT OR IGNORE INTO scheduling_rules (category, rule_preset) VALUES (?, ?)');
+  setRule.run('family', 'flexible');
+  setRule.run('friend', 'flexible');
+  setRule.run('team', 'work-hours');
+  setRule.run('client', 'professional');
+  setRule.run('lead', 'professional');
+  setRule.run('unknown', 'gatekeeper');
+}
+
+function prepareStatements() {
+  stmts = {
+    // ── Contacts ──
+    getContact: db.prepare('SELECT * FROM contacts WHERE phone = ?'),
+    getAllContacts: db.prepare('SELECT * FROM contacts ORDER BY name'),
+    searchContacts: db.prepare("SELECT * FROM contacts WHERE name LIKE ? OR phone LIKE ? ORDER BY name"),
+    filterByCategory: db.prepare('SELECT * FROM contacts WHERE category = ? ORDER BY name'),
+    upsertContact: db.prepare(`
+      INSERT INTO contacts (phone, name, category, response_mode, style, instructions, source, introduced, qualification_score, pipeline_stage, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'))
+      ON CONFLICT(phone) DO UPDATE SET
+        name=excluded.name, category=excluded.category, response_mode=excluded.response_mode,
+        style=excluded.style, instructions=excluded.instructions, source=excluded.source,
+        introduced=excluded.introduced, qualification_score=excluded.qualification_score,
+        pipeline_stage=excluded.pipeline_stage, updated_at=datetime('now')
+    `),
+    updateContactField: db.prepare("UPDATE contacts SET updated_at = datetime('now') WHERE phone = ?"),
+    deleteContact: db.prepare('DELETE FROM contacts WHERE phone = ?'),
+    markIntroduced: db.prepare("UPDATE contacts SET introduced = 1, updated_at = datetime('now') WHERE phone = ?"),
+    updateQualification: db.prepare("UPDATE contacts SET qualification_score = ?, pipeline_stage = ?, updated_at = datetime('now') WHERE phone = ?"),
+    updateCategory: db.prepare("UPDATE contacts SET category = ?, updated_at = datetime('now') WHERE phone = ?"),
+
+    // ── Contact Context ──
+    getContext: db.prepare('SELECT * FROM contact_context WHERE phone = ?'),
+    upsertContext: db.prepare(`
+      INSERT INTO contact_context (phone, relationship, last_topic, pending_items, conversation_summary, preferences, last_interaction)
+      VALUES (?, ?, ?, ?, ?, ?, datetime('now'))
+      ON CONFLICT(phone) DO UPDATE SET
+        relationship=excluded.relationship, last_topic=excluded.last_topic,
+        pending_items=excluded.pending_items, conversation_summary=excluded.conversation_summary,
+        preferences=excluded.preferences, last_interaction=datetime('now')
+    `),
+    deleteContext: db.prepare('DELETE FROM contact_context WHERE phone = ?'),
+
+    // ── Contact Scopes ──
+    getScope: db.prepare('SELECT * FROM contact_scopes WHERE phone = ? AND scope = ?'),
+    getAllScopes: db.prepare('SELECT * FROM contact_scopes WHERE phone = ?'),
+    upsertScope: db.prepare(`
+      INSERT INTO contact_scopes (phone, scope, granted, granted_by, granted_at)
+      VALUES (?, ?, ?, ?, datetime('now'))
+      ON CONFLICT(phone, scope) DO UPDATE SET granted=excluded.granted, granted_by=excluded.granted_by, granted_at=datetime('now')
+    `),
+    deleteScope: db.prepare('DELETE FROM contact_scopes WHERE phone = ? AND scope = ?'),
+    deleteScopesByPhone: db.prepare('DELETE FROM contact_scopes WHERE phone = ?'),
+
+    // ── Conversation State ──
+    getState: db.prepare('SELECT * FROM conversation_state WHERE phone = ?'),
+    upsertState: db.prepare(`
+      INSERT INTO conversation_state (phone, state, state_data, entered_at, expires_at)
+      VALUES (?, ?, ?, datetime('now'), ?)
+      ON CONFLICT(phone) DO UPDATE SET state=excluded.state, state_data=excluded.state_data,
+        entered_at=datetime('now'), expires_at=excluded.expires_at
+    `),
+    clearExpiredStates: db.prepare("UPDATE conversation_state SET state = 'idle', state_data = '{}' WHERE expires_at IS NOT NULL AND expires_at < datetime('now')"),
+
+    // ── Message Log ──
+    insertMessage: db.prepare(`
+      INSERT INTO message_log (phone, channel, direction, text, attachments, sent_by, state_at_time)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `),
+    getRecentMessages: db.prepare('SELECT * FROM message_log WHERE phone = ? ORDER BY created_at DESC LIMIT ?'),
+    getRecentMessagesAll: db.prepare(`
+      SELECT m.*, COALESCE(c.name, m.phone) as contact_name
+      FROM message_log m LEFT JOIN contacts c ON c.phone = m.phone
+      ORDER BY m.created_at DESC LIMIT ?
+    `),
+    getLastOutbound: db.prepare("SELECT * FROM message_log WHERE phone = ? AND direction = 'outbound' ORDER BY created_at DESC LIMIT 1"),
+    getLastInbound: db.prepare("SELECT * FROM message_log WHERE phone = ? AND direction = 'inbound' ORDER BY created_at DESC LIMIT 1"),
+    getLastSentBy: db.prepare("SELECT sent_by FROM message_log WHERE phone = ? AND direction = 'outbound' AND sent_by != '' ORDER BY created_at DESC LIMIT 1"),
+    countRecentOutbound: db.prepare("SELECT COUNT(*) as count FROM message_log WHERE phone = ? AND direction = 'outbound' AND sent_by = 'aiva' AND created_at >= datetime('now', '-' || ? || ' hours')"),
+    countRecentFollowUps: db.prepare("SELECT COUNT(*) as count FROM message_log WHERE phone = ? AND direction = 'outbound' AND state_at_time = 'follow-up' AND created_at >= datetime('now', '-24 hours')"),
+
+    // ── FAQ ──
+    getAllFaq: db.prepare('SELECT * FROM faq_entries WHERE enabled = 1 ORDER BY category, id'),
+    getFaqByDevice: db.prepare('SELECT * FROM faq_entries WHERE (device_id = ? OR device_id IS NULL) AND enabled = 1 ORDER BY category, id'),
+    insertFaq: db.prepare('INSERT INTO faq_entries (device_id, question, answer, category, keywords) VALUES (?, ?, ?, ?, ?)'),
+    updateFaq: db.prepare('UPDATE faq_entries SET question=?, answer=?, category=?, keywords=?, enabled=? WHERE id=?'),
+    deleteFaq: db.prepare('DELETE FROM faq_entries WHERE id = ?'),
+    getFaqById: db.prepare('SELECT * FROM faq_entries WHERE id = ?'),
+
+    // ── Playbook ──
+    getPlaybookSections: db.prepare('SELECT * FROM playbook_sections WHERE (device_id = ? OR device_id IS NULL) AND enabled = 1 ORDER BY priority, id'),
+    getPlaybookByType: db.prepare('SELECT * FROM playbook_sections WHERE section_type = ? AND (device_id = ? OR device_id IS NULL) AND enabled = 1 ORDER BY priority'),
+    insertPlaybook: db.prepare("INSERT INTO playbook_sections (device_id, section_type, title, content, priority) VALUES (?, ?, ?, ?, ?)"),
+    updatePlaybook: db.prepare("UPDATE playbook_sections SET section_type=?, title=?, content=?, priority=?, enabled=?, version=version+1, updated_at=datetime('now') WHERE id=?"),
+    deletePlaybook: db.prepare('DELETE FROM playbook_sections WHERE id = ?'),
+    getPlaybookById: db.prepare('SELECT * FROM playbook_sections WHERE id = ?'),
+
+    // ── Preferences ──
+    getAllPreferences: db.prepare('SELECT * FROM preferences ORDER BY hit_count DESC, confidence DESC'),
+    getPreferencesByScope: db.prepare('SELECT * FROM preferences WHERE (scope = ? OR scope = ?) AND confidence >= 0.5 ORDER BY confidence DESC, hit_count DESC LIMIT ?'),
+    insertPreference: db.prepare(`
+      INSERT INTO preferences (scope, question_pattern, answer, source, confidence)
+      VALUES (?, ?, ?, ?, ?)
+    `),
+    updatePreference: db.prepare("UPDATE preferences SET answer=?, source=?, confidence=?, hit_count=hit_count+1, last_used_at=datetime('now'), updated_at=datetime('now') WHERE id=?"),
+    bumpPreferenceHit: db.prepare("UPDATE preferences SET hit_count=hit_count+1, last_used_at=datetime('now') WHERE id=?"),
+    deletePreference: db.prepare('DELETE FROM preferences WHERE id = ?'),
+    decayPreferences: db.prepare("UPDATE preferences SET confidence = MAX(0.0, confidence - ?) WHERE source = ? AND updated_at < datetime('now', '-30 days')"),
+
+    // ── Preference Log ──
+    insertPreferenceLog: db.prepare('INSERT INTO preference_log (preference_id, escalation_id, phone, original_question, tier_resolved) VALUES (?, ?, ?, ?, ?)'),
+
+    // ── Escalations ──
+    insertEscalation: db.prepare(`
+      INSERT INTO escalations (escalation_id, phone, trigger_message, context_sent, status, is_client_support, timeout_at)
+      VALUES (?, ?, ?, ?, 'pending', ?, ?)
+    `),
+    getEscalation: db.prepare('SELECT * FROM escalations WHERE escalation_id = ?'),
+    getActiveEscalation: db.prepare("SELECT * FROM escalations WHERE phone = ? AND status = 'pending' ORDER BY created_at DESC LIMIT 1"),
+    resolveEscalation: db.prepare("UPDATE escalations SET status = 'responded', response_received = ?, responded_at = datetime('now') WHERE escalation_id = ?"),
+    timeoutEscalation: db.prepare("UPDATE escalations SET status = 'timeout' WHERE escalation_id = ?"),
+    failEscalation: db.prepare("UPDATE escalations SET status = 'failed' WHERE escalation_id = ?"),
+    incrementStrike: db.prepare('UPDATE escalations SET strike_count = strike_count + 1 WHERE escalation_id = ?'),
+    getTimedOutEscalations: db.prepare("SELECT * FROM escalations WHERE status = 'pending' AND timeout_at < datetime('now')"),
+
+    // ── Follow-Up Tracker ──
+    getActiveFollowUps: db.prepare("SELECT * FROM follow_up_tracker WHERE status = 'active' AND next_follow_up_at <= datetime('now') AND opted_out = 0"),
+    getAllFollowUps: db.prepare("SELECT * FROM follow_up_tracker ORDER BY CASE status WHEN 'active' THEN 0 WHEN 'cold' THEN 1 WHEN 'paused' THEN 2 ELSE 3 END, next_follow_up_at ASC"),
+    getFollowUpByPhone: db.prepare('SELECT * FROM follow_up_tracker WHERE phone = ?'),
+    upsertFollowUp: db.prepare(`
+      INSERT INTO follow_up_tracker (phone, channel, contact_name, last_our_message, last_our_message_at, status, follow_up_count, next_follow_up_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, 0, ?, datetime('now'))
+      ON CONFLICT(phone) DO UPDATE SET
+        channel=excluded.channel, contact_name=excluded.contact_name,
+        last_our_message=excluded.last_our_message, last_our_message_at=excluded.last_our_message_at,
+        status=excluded.status, follow_up_count=0, next_follow_up_at=excluded.next_follow_up_at,
+        updated_at=datetime('now')
+    `),
+    updateFollowUpStatus: db.prepare("UPDATE follow_up_tracker SET status = ?, updated_at = datetime('now') WHERE phone = ?"),
+    incrementFollowUp: db.prepare("UPDATE follow_up_tracker SET follow_up_count = follow_up_count + 1, last_follow_up_at = datetime('now'), next_follow_up_at = ?, updated_at = datetime('now') WHERE phone = ?"),
+    markFollowUpCold: db.prepare("UPDATE follow_up_tracker SET status = 'cold', updated_at = datetime('now') WHERE phone = ?"),
+    updateFollowUpOptOut: db.prepare("UPDATE follow_up_tracker SET opted_out = ?, updated_at = datetime('now') WHERE phone = ?"),
+    updateFollowUpTopic: db.prepare("UPDATE follow_up_tracker SET last_follow_up_topic = ?, updated_at = datetime('now') WHERE phone = ?"),
+    deleteFollowUp: db.prepare('DELETE FROM follow_up_tracker WHERE phone = ?'),
+
+    // ── Scheduling Rules ──
+    getSchedulingRule: db.prepare('SELECT * FROM scheduling_rules WHERE category = ?'),
+    upsertSchedulingRule: db.prepare("INSERT OR REPLACE INTO scheduling_rules (category, rule_preset, custom_instructions, structured_overrides, updated_at) VALUES (?, ?, ?, ?, datetime('now'))"),
+    getAllSchedulingRules: db.prepare('SELECT * FROM scheduling_rules'),
+
+    // ── Settings ──
+    getSetting: db.prepare('SELECT value FROM settings WHERE key = ?'),
+    setSetting: db.prepare('INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)'),
+    getAllSettings: db.prepare('SELECT * FROM settings'),
+  };
+}
+
+/**
+ * Get a setting value by key.
+ * @param {string} key
+ * @returns {string}
+ */
+function getSetting(key) {
+  const row = stmts.getSetting.get(key);
+  return row ? row.value : '';
+}
+
+/**
+ * Set a setting value.
+ * @param {string} key
+ * @param {string} value
+ */
+function setSetting(key, value) {
+  stmts.setSetting.run(key, String(value));
+}
+
+/**
+ * Get the raw database instance (for advanced queries).
+ * @returns {import('better-sqlite3').Database}
+ */
+function getDb() { return db; }
+
+/**
+ * Get all prepared statements.
+ * @returns {Object}
+ */
+function getStmts() { return stmts; }
+
+module.exports = { initDatabase, getSetting, setSetting, getDb, getStmts };