wacrawl-dashboard 0.1.1 → 0.2.0

package/apps/api/dist/index.js

@@ -3,27 +3,103 @@ import 'dotenv/config';
 import express from 'express';
 import { ensurePrimaryDatabase } from './db.js';
 import { isMediaRootAccessible } from './lib/mediaFsPath.js';
+import { resolvePathsFromEnv } from './pathsResolve.js';
 import { dataRouter } from './routes/data.js';
 import { settingsRouter } from './routes/settings.js';
 import { statsRouter } from './routes/stats.js';
+import { syncRouter } from './routes/sync.js';
 import { getResolvedPaths, pathsMiddleware } from './runtimePaths.js';
 const PORT = Number(process.env.PORT ?? 3001);
 const HOST = '127.0.0.1';
-const ALLOWED_ORIGINS = new Set([
-    'http://localhost:5173',
-    'http://127.0.0.1:5173',
-    'http://localhost:4173',
-    'http://127.0.0.1:4173',
-    // Also allow same-origin requests when API serves the web frontend directly
-    `http://localhost:${PORT}`,
-    `http://127.0.0.1:${PORT}`,
-]);
 const ALLOWED_HOSTS = new Set([
     `localhost:${PORT}`,
     `127.0.0.1:${PORT}`,
 ]);
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/**
+ * Accept any origin served from this machine. Development only: see createApp.
+ *
+ * Pinning the allowlist to ports 5173/4173 was brittle: Vite silently moves to
+ * 5174 when 5173 is already taken, and from then on every request failed with an
+ * opaque 500 that surfaced in the UI as "Cannot connect to the WaCrawl API".
+ */
+export function isLoopbackOrigin(origin) {
+    try {
+        const { hostname, protocol } = new URL(origin);
+        if (protocol !== 'http:' && protocol !== 'https:')
+            return false;
+        return LOOPBACK_HOSTNAMES.has(hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** The dashboard this server is hosting, under either name for loopback. */
+function isOwnOrigin(origin) {
+    try {
+        const { host, protocol } = new URL(origin);
+        return protocol === 'http:' && ALLOWED_HOSTS.has(host);
+    }
+    catch {
+        return false;
+    }
+}
+export const errorHandler = (error, _req, res, next) => {
+    // Once the response is on the wire there is no way to replace it with a JSON
+    // error — writing anyway throws ERR_HTTP_HEADERS_SENT. Hand back to Express so
+    // its final handler destroys the socket instead.
+    if (res.headersSent) {
+        next(error);
+        return;
+    }
+    if (error?.code === 'FORBIDDEN_ORIGIN') {
+        // Was an opaque 500 before, which the UI reported as "Cannot connect to the
+        // WaCrawl API" with no hint that the origin was the problem.
+        res.status(403).json({
+            error: {
+                code: 'FORBIDDEN_ORIGIN',
+                message: `Blocked request from origin ${error.origin ?? 'unknown'}. Only the dashboard itself may call this API.`,
+            },
+        });
+        return;
+    }
+    if (error?.code === 'CHAT_NOT_FOUND') {
+        res.status(404).json({
+            error: { code: 'CHAT_NOT_FOUND', message: error.message ?? 'No such chat.' },
+        });
+        return;
+    }
+    if (error?.code === 'NOT_A_GROUP') {
+        res.status(400).json({
+            error: { code: 'NOT_A_GROUP', message: error.message ?? 'That chat is not a group.' },
+        });
+        return;
+    }
+    if (error?.code === 'VALIDATION_ERROR') {
+        res.status(400).json({
+            error: { code: 'VALIDATION_ERROR', message: error.message ?? 'Invalid request.' },
+        });
+        return;
+    }
+    const code = error?.code === 'SQLITE_CANTOPEN' ? 'DATABASE_UNAVAILABLE' : 'INTERNAL_ERROR';
+    const message = code === 'DATABASE_UNAVAILABLE'
+        ? 'Cannot open the WaCrawl database. Check Settings → Archive paths, WACRAWL_DB in .env, or run wacrawl sync.'
+        : 'Unexpected server error.';
+    res.status(code === 'DATABASE_UNAVAILABLE' ? 503 : 500).json({
+        error: {
+            code,
+            message,
+        },
+    });
+};
 export function createApp() {
     const app = express();
+    // Production static file serving — set WACRAWL_STATIC_DIR to the web dist folder
+    const staticDir = process.env.WACRAWL_STATIC_DIR;
+    // A site on another local port (MAMP, any dev server) runs code the archive
+    // owner did not write, so it must not read the archive. Only development needs
+    // the wider rule, because the UI then comes from Vite on a port that can move.
+    const isAllowedOrigin = staticDir ? isOwnOrigin : isLoopbackOrigin;
     app.disable('x-powered-by');
     app.use(express.json({ limit: '64kb' }));
     app.use((req, res, next) => {
@@ -41,11 +117,16 @@ export function createApp() {
     });
     app.use(cors({
         origin(origin, callback) {
-            if (!origin || ALLOWED_ORIGINS.has(origin)) {
+            // No Origin header: same-origin, or a non-browser client such as curl or
+            // an <img> tag pointing at /api/media/file.
+            if (!origin || isAllowedOrigin(origin)) {
                 callback(null, true);
                 return;
             }
-            callback(new Error('Origin is not allowed by CORS.'));
+            callback(Object.assign(new Error('Origin is not allowed by CORS.'), {
+                code: 'FORBIDDEN_ORIGIN',
+                origin,
+            }));
         },
     }));
     app.use(pathsMiddleware);
@@ -57,11 +138,14 @@ export function createApp() {
             primaryDbReadable = true;
         }
         catch {
-            primaryDbReadable = false;
+            // Left false — /api/health reports the archive as unreachable.
         }
         const mediaStatus = isMediaRootAccessible();
         res.json({
             ok: primaryDbReadable,
+            // Settings can repoint a running demo at another archive, and a badge
+            // calling real messages "demo data" would be worse than no badge.
+            demo: process.env.WACRAWL_DEMO === '1' && paths.primaryDb === resolvePathsFromEnv().primaryDb,
             dbPath: paths.primaryDb,
             paths,
             mediaAccessible: mediaStatus.accessible,
@@ -70,6 +154,7 @@ export function createApp() {
     });
     app.use('/api/settings', settingsRouter);
     app.use('/api/stats', statsRouter);
+    app.use('/api/sync', syncRouter);
     app.use('/api', dataRouter);
     // JSON 404 only for /api routes; non-API routes fall through to static serving below
     app.use('/api', (_req, res) => {
@@ -80,8 +165,6 @@ export function createApp() {
             },
         });
     });
-    // Production static file serving — set WACRAWL_STATIC_DIR to the web dist folder
-    const staticDir = process.env.WACRAWL_STATIC_DIR;
     if (staticDir) {
         app.use(express.static(staticDir));
         // SPA fallback: unmatched non-API GET requests return index.html
@@ -93,23 +176,20 @@ export function createApp() {
             res.sendFile('index.html', { root: staticDir });
         });
     }
-    const errorHandler = (error, _req, res, _next) => {
-        const code = error?.code === 'SQLITE_CANTOPEN' ? 'DATABASE_UNAVAILABLE' : 'INTERNAL_ERROR';
-        const message = code === 'DATABASE_UNAVAILABLE'
-            ? 'Cannot open the WaCrawl database. Check Settings → Archive paths, WACRAWL_DB in .env, or run wacrawl sync.'
-            : 'Unexpected server error.';
-        res.status(code === 'DATABASE_UNAVAILABLE' ? 503 : 500).json({
-            error: {
-                code,
-                message,
-            },
-        });
-    };
     app.use(errorHandler);
     return app;
 }
-if (process.env.NODE_ENV !== 'test') {
-    createApp().listen(PORT, HOST, () => {
+/** Express 5 passes listen errors, such as a taken port, to the listen callback. */
+export function reportListenResult(error) {
+    if (!error) {
         console.info(`WaCrawl API listening on http://${HOST}:${PORT}`);
-    });
+        return;
+    }
+    console.error(error.code === 'EADDRINUSE'
+        ? `Port ${PORT} is already in use. WaCrawl may already be running at http://${HOST}:${PORT}. Otherwise, choose another port with PORT=<port>.`
+        : `Could not start the WaCrawl API: ${error.message}`);
+    process.exitCode = 1;
+}
+if (process.env.NODE_ENV !== 'test') {
+    createApp().listen(PORT, HOST, reportListenResult);
 }

package/apps/api/dist/lib/archiveSchema.js

@@ -0,0 +1,57 @@
+/**
+ * The tables every wacrawl archive has, and all the dashboard requires.
+ *
+ * Shared by the test fixtures and the demo archive so they cannot drift apart.
+ * Newer wacrawl versions add to this (`chats.archived`, `sync_state`,
+ * `messages_fts`); the queries probe for those, so they stay out of the baseline.
+ */
+export const ARCHIVE_SCHEMA_SQL = `
+  CREATE TABLE chats (
+    jid TEXT PRIMARY KEY,
+    kind TEXT NOT NULL,
+    name TEXT,
+    last_message_at INTEGER
+  );
+  CREATE TABLE contacts (
+    jid TEXT PRIMARY KEY,
+    phone TEXT,
+    full_name TEXT,
+    first_name TEXT,
+    last_name TEXT,
+    business_name TEXT,
+    username TEXT,
+    lid TEXT
+  );
+  CREATE TABLE groups (
+    jid TEXT PRIMARY KEY,
+    name TEXT,
+    owner_jid TEXT,
+    created_at INTEGER
+  );
+  CREATE TABLE group_participants (
+    group_jid TEXT NOT NULL,
+    user_jid TEXT NOT NULL,
+    contact_name TEXT,
+    first_name TEXT,
+    is_admin INTEGER NOT NULL DEFAULT 0,
+    is_active INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (group_jid, user_jid)
+  );
+  CREATE TABLE messages (
+    rowid INTEGER PRIMARY KEY AUTOINCREMENT,
+    source_pk INTEGER NOT NULL UNIQUE,
+    chat_jid TEXT NOT NULL,
+    chat_name TEXT,
+    msg_id TEXT NOT NULL,
+    sender_jid TEXT,
+    sender_name TEXT,
+    ts INTEGER NOT NULL,
+    from_me INTEGER NOT NULL,
+    text TEXT,
+    raw_type INTEGER NOT NULL,
+    message_type TEXT,
+    media_type TEXT,
+    media_path TEXT,
+    media_size INTEGER
+  );
+`;

package/apps/api/dist/lib/archiveSync.js

@@ -0,0 +1,151 @@
+import { spawn } from 'node:child_process';
+import { closeDb, getDb } from '../db.js';
+import { clearStatsCache } from './statsCache.js';
+/** Import can be genuinely slow on a first run; give up rather than leak a process. */
+const SYNC_TIMEOUT_MS = 10 * 60 * 1000;
+/** Enough of the CLI's output to diagnose a failure, without unbounded buffering. */
+const MAX_OUTPUT_BYTES = 8 * 1024;
+const MULTI_IDENTITY_PATTERN = /multiple whatsapp account identities/i;
+const MULTI_IDENTITY_HINT = 'The WhatsApp source holds more than one account identity, so wacrawl refuses to import it automatically. '
+    + 'Run `wacrawl sync --adopt-source` in a terminal to bind this archive to one identity and merge. '
+    + 'The dashboard will not do that for you: it rewrites which account owns the archive.';
+const MISSING_BINARY_HINT = 'Install the wacrawl CLI and make sure it is on PATH, or point WACRAWL_BIN at the executable.';
+const idleJob = {
+    state: 'idle',
+    startedAt: null,
+    finishedAt: null,
+    error: null,
+    hint: null,
+};
+let job = idleJob;
+let inFlight = null;
+export function syncEnabled() {
+    return process.env.WACRAWL_DISABLE_SYNC !== '1';
+}
+export function syncJobStatus() {
+    return { ...job };
+}
+/** Test seam: drop job state between cases so each starts from idle. */
+export function resetSyncJob() {
+    job = idleJob;
+    inFlight = null;
+}
+/**
+ * Read the CLI's own bookkeeping table. Older archives predate `sync_state` and
+ * a misconfigured path means no archive at all, so every failure degrades to
+ * "unknown" rather than breaking the status endpoint.
+ */
+export function readArchiveSyncInfo() {
+    try {
+        const db = getDb();
+        const present = db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'sync_state'")
+            .get();
+        if (!present) {
+            return { lastImportAt: null, sourcePath: null };
+        }
+        const rows = db.prepare('SELECT key, value FROM sync_state').all();
+        const byKey = new Map(rows.map((row) => [row.key, row.value]));
+        return {
+            lastImportAt: byKey.get('last_import_at') ?? null,
+            sourcePath: byKey.get('source_path') ?? null,
+        };
+    }
+    catch {
+        return { lastImportAt: null, sourcePath: null };
+    }
+}
+/**
+ * Start an import unless one is already running.
+ *
+ * `started: false` means the caller lost the race and should poll the returned
+ * job rather than treating it as an error.
+ */
+export function startSync(dbPath) {
+    if (inFlight) {
+        return { started: false, job: syncJobStatus() };
+    }
+    job = { state: 'running', startedAt: new Date().toISOString(), finishedAt: null, error: null, hint: null };
+    inFlight = runWacrawlSync(dbPath).then((outcome) => {
+        if (outcome.ok) {
+            // The import rewrote the file underneath a readonly handle, and every
+            // cached stat was computed from the old contents.
+            closeDb();
+            clearStatsCache();
+        }
+        job = {
+            state: outcome.ok ? 'succeeded' : 'failed',
+            startedAt: job.startedAt,
+            finishedAt: new Date().toISOString(),
+            error: outcome.ok ? null : outcome.error,
+            hint: outcome.ok ? null : outcome.hint,
+        };
+    }).finally(() => {
+        inFlight = null;
+    });
+    return { started: true, job: syncJobStatus() };
+}
+/**
+ * Spawned without a shell and with a fixed argument list, so the configured
+ * archive path cannot turn into extra commands.
+ */
+function runWacrawlSync(dbPath) {
+    return new Promise((resolve) => {
+        const bin = process.env.WACRAWL_BIN ?? 'wacrawl';
+        let output = '';
+        let settled = false;
+        function settle(outcome) {
+            if (settled)
+                return;
+            settled = true;
+            resolve(outcome);
+        }
+        const child = spawn(bin, ['--db', dbPath, 'sync'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: SYNC_TIMEOUT_MS,
+        });
+        function collect(chunk) {
+            if (output.length >= MAX_OUTPUT_BYTES)
+                return;
+            output += chunk.toString('utf8');
+        }
+        child.stdout?.on('data', collect);
+        child.stderr?.on('data', collect);
+        child.on('error', (error) => {
+            settle(error.code === 'ENOENT'
+                ? { ok: false, error: `Cannot run "${bin}": the wacrawl CLI was not found.`, hint: MISSING_BINARY_HINT }
+                : { ok: false, error: `Cannot run "${bin}": ${error.message}`, hint: null });
+        });
+        child.on('close', (code, signal) => {
+            if (code === 0) {
+                settle({ ok: true, error: null, hint: null });
+                return;
+            }
+            // node's `timeout` option kills the child rather than emitting an error.
+            if (signal) {
+                settle({
+                    ok: false,
+                    error: `wacrawl sync was terminated by ${signal} after ${Math.round(SYNC_TIMEOUT_MS / 60_000)} minutes.`,
+                    hint: 'Run `wacrawl sync` in a terminal to see how far it gets.',
+                });
+                return;
+            }
+            settle({
+                ok: false,
+                error: summarize(output) || `wacrawl sync exited with code ${code}.`,
+                hint: MULTI_IDENTITY_PATTERN.test(output) ? MULTI_IDENTITY_HINT : null,
+            });
+        });
+    });
+}
+/**
+ * The CLI reports progress on the way to a failure, so the last few non-empty
+ * lines carry the reason while the earlier ones are noise.
+ */
+function summarize(output) {
+    const lines = output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+    return lines.slice(-3).join(' — ').slice(0, 500);
+}

package/apps/api/dist/lib/chatKind.js

@@ -0,0 +1,41 @@
+/**
+ * Real archives label one-to-one chats `dm`; the fixtures here — and older
+ * wacrawl versions — say `direct`. Filtering on a single literal silently
+ * matched nothing on real data, which is how the Chats page ended up listing
+ * groups only, and why the dormancy report came back empty for every account.
+ *
+ * `status` is WhatsApp's own broadcast pseudo-chat. It is neither a person nor
+ * a group, so it belongs in neither bucket.
+ */
+export const DIRECT_CHAT_KINDS = ['dm', 'direct'];
+export function parseChatKind(value, fallback = 'all') {
+    if (value === 'direct' || value === 'group' || value === 'all')
+        return value;
+    return fallback;
+}
+/**
+ * SQL predicate for a chat-kind filter, as a bare condition with no leading
+ * `AND`/`WHERE` so callers can place it wherever it fits.
+ *
+ * The literals are compile-time constants rather than bound parameters because
+ * this composes into larger statements that are prepared once and reused.
+ */
+export function chatKindSql(kind, column = 'chats.kind') {
+    if (kind === 'group')
+        return `${column} = 'group'`;
+    if (kind === 'direct')
+        return `${column} IN ('dm', 'direct')`;
+    return `${column} IN ('dm', 'direct', 'group')`;
+}
+/** Older archives predate a table; a missing one should degrade, not throw. */
+export function tableExists(db, name) {
+    const row = db
+        .prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = @name")
+        .get({ name });
+    return row !== undefined;
+}
+/** Newer wacrawl archives add columns (e.g. `chats.archived`); older ones lack them. */
+export function columnExists(db, table, column) {
+    const columns = db.prepare(`PRAGMA table_info(${JSON.stringify(table)})`).all();
+    return columns.some((row) => row.name === column);
+}

package/apps/api/dist/lib/displayName.js

@@ -11,7 +11,7 @@ export function cleanDisplayNameSql(expression) {
     END
   `;
 }
-export function contactDisplayNameSql(alias) {
+export function contactDisplayNameSingleSql(alias) {
     return `
     COALESCE(
       ${cleanDisplayNameSql(`${alias}.full_name`)},
@@ -23,6 +23,40 @@ export function contactDisplayNameSql(alias) {
     )
   `;
 }
-export function contactMatchSql(alias, jidExpression) {
-    return `(${alias}.jid = ${jidExpression} OR ${alias}.lid = ${jidExpression})`;
+export function contactDisplayNameSql(alias, isSplit = true) {
+    if (!isSplit) {
+        return contactDisplayNameSingleSql(alias);
+    }
+    return `
+    COALESCE(
+      ${contactDisplayNameSingleSql(`${alias}_jid`)},
+      ${contactDisplayNameSingleSql(`${alias}_lid`)}
+    )
+  `;
+}
+export function contactLeftJoins(alias, jidExpression) {
+    return `
+    LEFT JOIN contacts AS ${alias}_jid ON ${alias}_jid.jid = ${jidExpression}
+    LEFT JOIN contacts AS ${alias}_lid ON ${alias}_lid.lid = ${jidExpression}
+  `;
+}
+/**
+ * The archive identifies one person two ways: a phone JID and an opaque `@lid`.
+ * Both turn up as message senders in the same chat, so anything that groups by
+ * `sender_jid` reports one person as two — a group leaderboard listed the same
+ * contact twice, 865 messages and 77.
+ *
+ * The contacts table holds the pairing, so joining through it collapses both
+ * spellings onto the phone JID. Requires `contactLeftJoins(alias, expression)`
+ * on the same expression. Falls back to the raw value for people who are not in
+ * contacts at all, which is the best that can be done for them.
+ */
+export function canonicalJidSql(alias, expression) {
+    return `COALESCE(${alias}_lid.jid, ${alias}_jid.jid, ${expression})`;
+}
+/**
+ * True when a JID identifies a person rather than a group or broadcast pseudo-chat.
+ */
+export function isPersonJidSql(expression) {
+    return `${expression} IS NOT NULL AND ${expression} <> '' AND ${expression} NOT LIKE '%@g.us' AND ${expression} NOT LIKE '%@status' AND ${expression} NOT LIKE '%@broadcast'`;
 }

package/apps/api/dist/lib/mediaFsPath.js

@@ -59,6 +59,33 @@ export function resolveArchiveMediaPath(storedPath) {
         return fallback;
     return resolved;
 }
+/** Types a browser only displays. SVG is left out: opened directly, it can run script. */
+const INLINE_MEDIA_EXTENSIONS = new Set([
+    '.jpg', '.jpeg', '.png', '.gif', '.webp', '.heic', '.heif',
+    '.mp4', '.mov', '.webm', '.m4v', '.3gp',
+    '.ogg', '.oga', '.opus', '.mp3', '.m4a', '.aac', '.wav',
+    '.pdf',
+]);
+/**
+ * Attachments are written by whoever sent them but served from the same origin as
+ * the API, so an HTML file opened as a page could read the whole archive. Anything
+ * not on the list downloads instead. The sandbox gives a page an opaque origin as
+ * a second line of defence. <img> and <video> ignore both headers, so thumbnails
+ * of unlisted types still render.
+ */
+export function mediaResponseHeaders(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    const headers = { 'X-Content-Type-Options': 'nosniff' };
+    // Browser PDF viewers refuse to load in a sandboxed document, and script inside
+    // a PDF has no access to the origin.
+    if (extension !== '.pdf') {
+        headers['Content-Security-Policy'] = 'sandbox';
+    }
+    if (!INLINE_MEDIA_EXTENSIONS.has(extension)) {
+        headers['Content-Disposition'] = `attachment; filename*=UTF-8''${encodeURIComponent(path.basename(filePath))}`;
+    }
+    return headers;
+}
 /** Check whether the configured media root is readable. */
 export function isMediaRootAccessible() {
     const root = getArchiveMediaRoot();

package/apps/api/dist/lib/percentile.js

@@ -0,0 +1,23 @@
+/**
+ * Nearest-rank percentile over an ascending-sorted array.
+ *
+ * Reply latencies are heavily right-skewed — a single reply three weeks later
+ * drags a mean past anything the conversation actually felt like — so the
+ * report layer quotes p50/p90 instead of an average.
+ */
+export function percentile(sortedAscending, p) {
+    if (sortedAscending.length === 0)
+        return 0;
+    const rank = Math.ceil((p / 100) * sortedAscending.length);
+    const index = Math.min(sortedAscending.length - 1, Math.max(0, rank - 1));
+    return sortedAscending[index];
+}
+/** Arithmetic mean, 0 for an empty array. */
+export function mean(values) {
+    if (values.length === 0)
+        return 0;
+    let total = 0;
+    for (const value of values)
+        total += value;
+    return total / values.length;
+}

package/apps/api/dist/lib/query.js

@@ -1,4 +1,15 @@
 import { getUnixTime } from 'date-fns';
+import { timeZoneOffsetMinutes, tsModifierSql } from './timezone.js';
+/**
+ * Describe a capped scan so the UI can say the numbers are partial.
+ *
+ * `scanned === limit` cannot distinguish "hit the cap" from "happens to have
+ * exactly that many rows"; erring towards claiming truncation is the safe
+ * direction, since the alternative is silently overstating coverage.
+ */
+export function scanCoverage(scanned, limit) {
+    return { scanned, limit, truncated: scanned >= limit };
+}
 const PERIOD_SECONDS = {
     day: 86_400,
     week: 604_800,
@@ -11,6 +22,11 @@ export function parsePeriod(value) {
     }
     return 'all';
 }
+/** `%value%` for a LIKE … ESCAPE '\\' test, or undefined when there is nothing to filter on. */
+export function nameLikePattern(value) {
+    const text = typeof value === 'string' ? value.trim() : '';
+    return text ? `%${text.replace(/[\\%_]/g, (match) => `\\${match}`)}%` : undefined;
+}
 export function parseGranularity(value, fallback) {
     if (value === 'day' || value === 'week' || value === 'month') {
         return value;
@@ -51,18 +67,28 @@ export function unixSecondsToIso(seconds) {
     }
     return new Date(seconds * 1000).toISOString();
 }
-export function bucketDateSql(granularity) {
+export function bucketDateSql(granularity, timeZone = 'UTC') {
+    const ts = tsModifierSql(timeZone);
     if (granularity === 'month') {
-        return "strftime('%Y-%m-01', ts, 'unixepoch')";
+        return `strftime('%Y-%m-01', ${ts})`;
     }
     if (granularity === 'week') {
-        return "date(ts, 'unixepoch', 'weekday 1', '-7 days')";
+        return `date(${ts}, 'weekday 1', '-7 days')`;
     }
-    return "date(ts, 'unixepoch')";
+    return `date(${ts})`;
 }
-export function yearBounds(year) {
-    const start = getUnixTime(new Date(Date.UTC(year, 0, 1)));
-    const end = getUnixTime(new Date(Date.UTC(year + 1, 0, 1)));
+/**
+ * Unix bounds of a calendar year *as the viewer experiences it*.
+ *
+ * The offset is read at each boundary rather than once, so a year that starts
+ * and ends on opposite sides of a DST transition still lines up with the
+ * timezone-aware bucketing in `bucketDateSql`.
+ */
+export function yearBounds(year, timeZone = 'UTC') {
+    const utcStart = new Date(Date.UTC(year, 0, 1));
+    const utcEnd = new Date(Date.UTC(year + 1, 0, 1));
+    const start = getUnixTime(utcStart) - timeZoneOffsetMinutes(timeZone, utcStart) * 60;
+    const end = getUnixTime(utcEnd) - timeZoneOffsetMinutes(timeZone, utcEnd) * 60;
     return { start, end };
 }
 export function normalizeBucketDate(date, granularity) {