@zhangferry-dev/tokendash 1.5.0 → 1.6.0

package/dist/server/claudeBlocksParser.js

@@ -142,7 +142,7 @@ export function getClaudeBlocksByProject(project) {
                 const outputTokens = usage.output_tokens;
                 const cacheCreationTokens = usage.cache_creation_input_tokens;
                 const cacheReadTokens = usage.cache_read_input_tokens;
-                const totalTokens = inputTokens + outputTokens + cacheReadTokens;
+                const totalTokens = inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens;
                 if (totalTokens === 0)
                     continue;
                 const hourKey = getHourKey(event.timestamp);
@@ -167,7 +167,7 @@ export function getClaudeBlocksByProject(project) {
     const blocks = [];
     let idx = 0;
     for (const [hourKey, bucket] of hourMap) {
-        const totalTokens = bucket.inputTokens + bucket.outputTokens + bucket.cacheReadTokens;
+        const totalTokens = bucket.inputTokens + bucket.outputTokens + bucket.cacheCreationTokens + bucket.cacheReadTokens;
         blocks.push({
             id: `claude-project-${idx}`,
             startTime: `${hourKey}:00:00.000Z`,

package/dist/server/claudeJsonlParser.d.ts

@@ -1,5 +1,5 @@
 import type { DailyResponse, ProjectsResponse, BlockEntry } from '../shared/types.js';
-export declare function calculateCost(inputTokens: number, cacheReadTokens: number, outputTokens: number, model: string): number;
+export declare function calculateCost(inputTokens: number, cacheReadTokens: number, outputTokens: number, model: string, cacheCreationTokens?: number): number;
 /** Decode Claude's encoded project directory name.
  *  Claude encodes paths: /Users/foo/bar → -Users-foo-bar
  *  Since '-' replaces '/' and project names can contain '-',

package/dist/server/claudeJsonlParser.js

@@ -3,18 +3,18 @@ import { join } from 'node:path';
 import { homedir } from 'node:os';
 const MODEL_PRICING = {
     // Claude 4.6
-    'claude-opus-4-6': { inputPer1M: 15, cacheReadPer1M: 1.50, outputPer1M: 75 },
-    'claude-sonnet-4-6': { inputPer1M: 3, cacheReadPer1M: 0.30, outputPer1M: 15 },
+    'claude-opus-4-6': { inputPer1M: 15, cacheCreationPer1M: 18.75, cacheReadPer1M: 1.50, outputPer1M: 75 },
+    'claude-sonnet-4-6': { inputPer1M: 3, cacheCreationPer1M: 3.75, cacheReadPer1M: 0.30, outputPer1M: 15 },
     // Claude 4.5
-    'claude-sonnet-4-5-20250514': { inputPer1M: 3, cacheReadPer1M: 0.30, outputPer1M: 15 },
-    'claude-haiku-4-5-20251001': { inputPer1M: 0.80, cacheReadPer1M: 0.08, outputPer1M: 4 },
+    'claude-sonnet-4-5-20250514': { inputPer1M: 3, cacheCreationPer1M: 3.75, cacheReadPer1M: 0.30, outputPer1M: 15 },
+    'claude-haiku-4-5-20251001': { inputPer1M: 0.80, cacheCreationPer1M: 1, cacheReadPer1M: 0.08, outputPer1M: 4 },
     // Older Claude models
-    'claude-3-5-sonnet-20241022': { inputPer1M: 3, cacheReadPer1M: 0.30, outputPer1M: 15 },
-    'claude-3-5-haiku-20241022': { inputPer1M: 0.80, cacheReadPer1M: 0.08, outputPer1M: 4 },
-    'claude-3-opus-20240229': { inputPer1M: 15, cacheReadPer1M: 1.50, outputPer1M: 75 },
-    'claude-3-haiku-20240307': { inputPer1M: 0.25, cacheReadPer1M: 0.03, outputPer1M: 1.25 },
+    'claude-3-5-sonnet-20241022': { inputPer1M: 3, cacheCreationPer1M: 3.75, cacheReadPer1M: 0.30, outputPer1M: 15 },
+    'claude-3-5-haiku-20241022': { inputPer1M: 0.80, cacheCreationPer1M: 1, cacheReadPer1M: 0.08, outputPer1M: 4 },
+    'claude-3-opus-20240229': { inputPer1M: 15, cacheCreationPer1M: 18.75, cacheReadPer1M: 1.50, outputPer1M: 75 },
+    'claude-3-haiku-20240307': { inputPer1M: 0.25, cacheCreationPer1M: 0.30, cacheReadPer1M: 0.03, outputPer1M: 1.25 },
 };
-const DEFAULT_PRICING = { inputPer1M: 3, cacheReadPer1M: 0.30, outputPer1M: 15 };
+const DEFAULT_PRICING = { inputPer1M: 3, cacheCreationPer1M: 3.75, cacheReadPer1M: 0.30, outputPer1M: 15 };
 function getPricing(model) {
     // Try exact match first, then prefix match
     if (MODEL_PRICING[model])
@@ -26,13 +26,16 @@ function getPricing(model) {
     }
     return DEFAULT_PRICING;
 }
-export function calculateCost(inputTokens, cacheReadTokens, outputTokens, model) {
+export function calculateCost(inputTokens, cacheReadTokens, outputTokens, model, cacheCreationTokens = 0) {
     const p = getPricing(model);
-    const nonCachedInput = Math.max(inputTokens - cacheReadTokens, 0);
-    return (nonCachedInput / 1_000_000) * p.inputPer1M
+    return (inputTokens / 1_000_000) * p.inputPer1M
+        + (cacheCreationTokens / 1_000_000) * p.cacheCreationPer1M
         + (cacheReadTokens / 1_000_000) * p.cacheReadPer1M
         + (outputTokens / 1_000_000) * p.outputPer1M;
 }
+function totalClaudeTokens(inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens) {
+    return inputTokens + outputTokens + cacheCreationTokens + cacheReadTokens;
+}
 // ---------------------------------------------------------------------------
 // JSONL parsing with mtime cache
 // ---------------------------------------------------------------------------
@@ -160,7 +163,7 @@ function parseAllSessions(project) {
                 const outputTokens = usage.output_tokens || 0;
                 const cacheCreationTokens = usage.cache_creation_input_tokens || 0;
                 const cacheReadTokens = usage.cache_read_input_tokens || 0;
-                const totalTokens = inputTokens + outputTokens + cacheReadTokens;
+                const totalTokens = totalClaudeTokens(inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens);
                 if (totalTokens === 0)
                     continue;
                 entries.push({
@@ -248,8 +251,8 @@ export function getDailyResponse(project, tz = DEFAULT_TZ) {
         agg.outputTokens += e.outputTokens;
         agg.cacheCreationTokens += e.cacheCreationTokens;
         agg.cacheReadTokens += e.cacheReadTokens;
-        agg.totalTokens += e.inputTokens + e.outputTokens + e.cacheReadTokens;
-        const cost = calculateCost(e.inputTokens, e.cacheReadTokens, e.outputTokens, e.model);
+        agg.totalTokens += totalClaudeTokens(e.inputTokens, e.outputTokens, e.cacheCreationTokens, e.cacheReadTokens);
+        const cost = calculateCost(e.inputTokens, e.cacheReadTokens, e.outputTokens, e.model, e.cacheCreationTokens);
         agg.totalCost += cost;
         if (!agg.models.has(e.model)) {
             agg.models.set(e.model, { input: 0, output: 0, cacheCreation: 0, cacheRead: 0, cost: 0 });
@@ -294,8 +297,8 @@ export function getProjectsResponse(tz = DEFAULT_TZ) {
         agg.outputTokens += e.outputTokens;
         agg.cacheCreationTokens += e.cacheCreationTokens;
         agg.cacheReadTokens += e.cacheReadTokens;
-        agg.totalTokens += e.inputTokens + e.outputTokens + e.cacheReadTokens;
-        const cost = calculateCost(e.inputTokens, e.cacheReadTokens, e.outputTokens, e.model);
+        agg.totalTokens += totalClaudeTokens(e.inputTokens, e.outputTokens, e.cacheCreationTokens, e.cacheReadTokens);
+        const cost = calculateCost(e.inputTokens, e.cacheReadTokens, e.outputTokens, e.model, e.cacheCreationTokens);
         agg.totalCost += cost;
         if (!agg.models.has(e.model)) {
             agg.models.set(e.model, { input: 0, output: 0, cacheCreation: 0, cacheRead: 0, cost: 0 });
@@ -331,13 +334,13 @@ export function getBlocksResponse(project, tz = DEFAULT_TZ) {
         bucket.outputTokens += e.outputTokens;
         bucket.cacheCreationTokens += e.cacheCreationTokens;
         bucket.cacheReadTokens += e.cacheReadTokens;
-        bucket.costUSD += calculateCost(e.inputTokens, e.cacheReadTokens, e.outputTokens, e.model);
+        bucket.costUSD += calculateCost(e.inputTokens, e.cacheReadTokens, e.outputTokens, e.model, e.cacheCreationTokens);
         bucket.models.add(e.model);
     }
     const blocks = [];
     let idx = 0;
     for (const [hourKey, bucket] of hourMap) {
-        const totalTokens = bucket.inputTokens + bucket.outputTokens + bucket.cacheReadTokens;
+        const totalTokens = totalClaudeTokens(bucket.inputTokens, bucket.outputTokens, bucket.cacheCreationTokens, bucket.cacheReadTokens);
         blocks.push({
             id: `claude-${idx}`,
             startTime: `${hourKey}:00:00`,

package/dist/server/codexParser.js

@@ -15,20 +15,24 @@ const TokenUsageSchema = z.object({
 }).default({ input_tokens: 0, cached_input_tokens: 0, output_tokens: 0, reasoning_output_tokens: 0, total_tokens: 0 });
 const TokenCountInfoSchema = z.object({
     total_token_usage: TokenUsageSchema,
-    last_token_usage: TokenUsageSchema,
+    last_token_usage: TokenUsageSchema.optional(),
 }).nullable().default(null);
 const TokenCountPayloadSchema = z.object({
     type: z.literal('token_count'),
     info: TokenCountInfoSchema,
 });
-function tokenUsageKey(usage) {
-    return [
-        usage.input_tokens,
-        usage.cached_input_tokens,
-        usage.output_tokens,
-        usage.reasoning_output_tokens,
-        usage.total_tokens,
-    ].join(':');
+function subtractTokenUsage(current, previous) {
+    return {
+        timestamp: '',
+        inputTokens: Math.max(0, current.input_tokens - (previous?.input_tokens ?? 0)),
+        cachedInputTokens: Math.max(0, current.cached_input_tokens - (previous?.cached_input_tokens ?? 0)),
+        outputTokens: Math.max(0, current.output_tokens - (previous?.output_tokens ?? 0)),
+        reasoningOutputTokens: Math.max(0, current.reasoning_output_tokens - (previous?.reasoning_output_tokens ?? 0)),
+        totalTokens: Math.max(0, current.total_tokens - (previous?.total_tokens ?? 0)),
+    };
+}
+function displayInputTokens(inputTokens, cachedInputTokens) {
+    return Math.max(0, inputTokens - cachedInputTokens);
 }
 // ---------------------------------------------------------------------------
 // Helpers
@@ -101,7 +105,9 @@ export function parseCodexSession(filepath) {
     let model = '';
     let createdAt = '';
     const tokenEvents = [];
+    let previousTotalUsage = null;
     const seenTotalUsageSnapshots = new Set();
+    const seenUsageEvents = new Set();
     for (const line of lines) {
         const trimmed = line.trim();
         if (!trimmed)
@@ -139,19 +145,43 @@ export function parseCodexSession(filepath) {
                 const info = parseResult.data.info;
                 if (!info)
                     continue;
-                const totalUsageKey = tokenUsageKey(info.total_token_usage);
+                const totalUsageKey = [
+                    info.total_token_usage.input_tokens,
+                    info.total_token_usage.cached_input_tokens,
+                    info.total_token_usage.output_tokens,
+                    info.total_token_usage.reasoning_output_tokens,
+                    info.total_token_usage.total_tokens,
+                ].join(':');
                 if (seenTotalUsageSnapshots.has(totalUsageKey))
                     continue;
                 seenTotalUsageSnapshots.add(totalUsageKey);
-                const last = info.last_token_usage;
-                tokenEvents.push({
+                const last = info.last_token_usage ?? info.total_token_usage;
+                const rawEvent = info.last_token_usage
+                    ? subtractTokenUsage(last, null)
+                    : subtractTokenUsage(last, previousTotalUsage);
+                previousTotalUsage = info.total_token_usage;
+                if (rawEvent.inputTokens === 0 && rawEvent.cachedInputTokens === 0 && rawEvent.outputTokens === 0 && rawEvent.reasoningOutputTokens === 0) {
+                    continue;
+                }
+                const event = {
+                    ...rawEvent,
+                    timestamp,
+                    cachedInputTokens: Math.min(rawEvent.cachedInputTokens, rawEvent.inputTokens),
+                };
+                const eventKey = [
                     timestamp,
-                    inputTokens: last.input_tokens,
-                    cachedInputTokens: last.cached_input_tokens,
-                    outputTokens: last.output_tokens,
-                    reasoningOutputTokens: last.reasoning_output_tokens,
-                    totalTokens: last.total_tokens,
-                });
+                    model,
+                    event.inputTokens,
+                    event.cachedInputTokens,
+                    event.outputTokens,
+                    event.reasoningOutputTokens,
+                    event.totalTokens,
+                ].join(':');
+                if (seenUsageEvents.has(eventKey)) {
+                    continue;
+                }
+                seenUsageEvents.add(eventKey);
+                tokenEvents.push(event);
             }
         }
     }
@@ -212,6 +242,12 @@ function addAcc(a, ev) {
     a.reasoningOutputTokens += ev.reasoningOutputTokens;
     a.totalTokens += ev.totalTokens;
 }
+function displayAcc(acc) {
+    return {
+        ...acc,
+        inputTokens: displayInputTokens(acc.inputTokens, acc.cachedInputTokens),
+    };
+}
 function mergeAcc(a, b) {
     a.inputTokens += b.inputTokens;
     a.cachedInputTokens += b.cachedInputTokens;
@@ -228,30 +264,34 @@ function addAccToBucket(bucket, ev, model) {
     addAcc(bucket.models.get(model), ev);
 }
 function accToEntry(date, acc, modelAccs) {
+    const display = displayAcc(acc);
     const modelNames = [...modelAccs.keys()];
     const modelBreakdowns = buildModelBreakdowns(modelAccs);
     const totalCost = modelBreakdowns.reduce((sum, model) => sum + model.cost, 0);
     return {
         date,
-        inputTokens: acc.inputTokens,
-        outputTokens: acc.outputTokens,
+        inputTokens: display.inputTokens,
+        outputTokens: display.outputTokens,
         cacheCreationTokens: 0,
-        cacheReadTokens: acc.cachedInputTokens,
-        totalTokens: acc.totalTokens,
+        cacheReadTokens: display.cachedInputTokens,
+        totalTokens: display.totalTokens,
         totalCost,
         modelsUsed: modelNames,
         modelBreakdowns,
     };
 }
 function buildModelBreakdowns(modelAccs) {
-    return [...modelAccs.entries()].map(([modelName, acc]) => ({
-        modelName,
-        inputTokens: acc.inputTokens,
-        outputTokens: acc.outputTokens,
-        cacheCreationTokens: 0,
-        cacheReadTokens: acc.cachedInputTokens,
-        cost: calculateCost(acc, new Set([modelName])),
-    }));
+    return [...modelAccs.entries()].map(([modelName, acc]) => {
+        const display = displayAcc(acc);
+        return {
+            modelName,
+            inputTokens: display.inputTokens,
+            outputTokens: display.outputTokens,
+            cacheCreationTokens: 0,
+            cacheReadTokens: display.cachedInputTokens,
+            cost: calculateCost(acc, new Set([modelName])),
+        };
+    });
 }
 function groupSessions(sessions, options) {
     const tz = options.timezone || 'Asia/Shanghai';
@@ -320,7 +360,7 @@ function buildDailyResponse(sessions, options) {
     return {
         daily,
         totals: {
-            inputTokens: totalsAcc.inputTokens,
+            inputTokens: displayInputTokens(totalsAcc.inputTokens, totalsAcc.cachedInputTokens),
             outputTokens: totalsAcc.outputTokens,
             cacheCreationTokens: 0,
             cacheReadTokens: totalsAcc.cachedInputTokens,
@@ -377,7 +417,7 @@ function buildBlocksResponse(sessions, options) {
             isGap: false,
             entries: acc.totalTokens > 0 ? 1 : 0,
             tokenCounts: {
-                inputTokens: acc.inputTokens,
+                inputTokens: displayInputTokens(acc.inputTokens, acc.cachedInputTokens),
                 outputTokens: acc.outputTokens,
                 cacheCreationInputTokens: 0,
                 cacheReadInputTokens: acc.cachedInputTokens,

package/electron/main.cjs

@@ -2,7 +2,6 @@ const { app, BrowserWindow, ipcMain, screen, shell } = require('electron');
 const path = require('node:path');
 const fs = require('node:fs');
 const http = require('node:http');
-const https = require('node:https');
 const { spawn } = require('node:child_process');
 
 // Global debug logger (writes to file since stdout is lost in packaged apps)
@@ -19,6 +18,7 @@ try {
 }
 
 const { formatTokens } = require('./trayBadge.cjs');
+const { checkForUpdates, downloadUpdateAsset } = require('./updateService.cjs');
 
 // Resolve trayHelper binary: extract from asar if needed
 function resolveTrayHelperPath() {
@@ -52,6 +52,8 @@ let server = null;
 let trayProcess = null;
 let selectedAgents = null; // null = use all available agents
 let serverPort = parseInt(process.env.TOKENDASH_PORT || '3456', 10);
+let lastUpdateInfo = null;
+let isDownloadingUpdate = false;
 const POPOVER_WIDTH = 380;
 const POPOVER_HEIGHT = 540;
 const PACKAGE_NAME = '@zhangferry-dev/tokendash';
@@ -97,41 +99,6 @@ function fetchJson(url) {
   });
 }
 
-function fetchHttpsJson(url) {
-  return new Promise((resolve, reject) => {
-    const opts = new URL(url);
-    const reqOpts = {
-      hostname: opts.hostname,
-      path: opts.pathname + opts.search,
-      method: 'GET',
-      headers: { 'User-Agent': 'TokenDash' },
-    };
-    https.get(reqOpts, (res) => {
-      let data = '';
-      res.on('data', (chunk) => { data += chunk; });
-      res.on('end', () => {
-        if (res.statusCode && res.statusCode >= 400) {
-          reject(new Error(`HTTP ${res.statusCode}`));
-          return;
-        }
-        try { resolve(JSON.parse(data)); }
-        catch (e) { reject(e); }
-      });
-    }).on('error', reject);
-  });
-}
-
-function compareVersions(a, b) {
-  const aParts = String(a).split('.').map((part) => parseInt(part, 10) || 0);
-  const bParts = String(b).split('.').map((part) => parseInt(part, 10) || 0);
-  const maxLen = Math.max(aParts.length, bParts.length);
-  for (let i = 0; i < maxLen; i++) {
-    const delta = (aParts[i] || 0) - (bParts[i] || 0);
-    if (delta !== 0) return delta;
-  }
-  return 0;
-}
-
 function getAppInfo() {
   // app.getVersion() returns Electron's version in dev mode (e.g. 41.5).
   // Always read from package.json to get the app's own version.
@@ -258,17 +225,19 @@ function getTrayAgentKey(agents) {
 
 function applyTraySnapshot(snapshot) {
   const totalTokens = Number(snapshot && snapshot.totalTokens) || 0;
+  const totalInput = Number(snapshot && snapshot.totalInput) || 0;
   const totalCost = Number(snapshot && snapshot.totalCost) || 0;
   const totalCacheRead = Number(snapshot && snapshot.totalCacheRead) || 0;
   const today = snapshot && snapshot.today;
   const agentKey = snapshot && snapshot.agentKey;
 
-  lastTraySnapshot = { today, agentKey, totalTokens, totalCost, totalCacheRead };
+  lastTraySnapshot = { today, agentKey, totalTokens, totalInput, totalCost, totalCacheRead };
 
   const tokenStr = formatTokens(totalTokens);
   sendTrayCommand('title:' + tokenStr);
 
-  const cacheRate = totalTokens > 0 ? ((totalCacheRead / totalTokens) * 100).toFixed(1) : '0.0';
+  const cacheInput = totalInput + totalCacheRead;
+  const cacheRate = cacheInput > 0 ? ((totalCacheRead / cacheInput) * 100).toFixed(1) : '0.0';
   sendTrayCommand('tooltip:TokenDash - ' + tokenStr + ' tokens today ($' + totalCost.toFixed(2) + ') | cache: ' + cacheRate + '%');
 }
 
@@ -337,7 +306,7 @@ function updateTrayBadge() {
         return;
       }
 
-      applyTraySnapshot({ today, agentKey, totalTokens, totalCost, totalCacheRead });
+      applyTraySnapshot({ today, agentKey, totalTokens, totalInput, totalCost, totalCacheRead });
     })
     .catch((err) => {
       if (err.code !== 'ECONNREFUSED') {
@@ -413,19 +382,10 @@ function registerIpcHandlers() {
 
   ipcMain.handle('tokendash:check-for-updates', async () => {
     const currentVersion = getAppInfo().version;
-    const releasesUrl = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
 
     try {
-      const latest = await fetchHttpsJson(releasesUrl);
-      // GitHub release tag may be "v1.3.0" or "1.3.0"
-      const tag = (latest.tag_name || '').replace(/^v/, '');
-      const latestVersion = tag || currentVersion;
-      return {
-        currentVersion,
-        latestVersion,
-        upToDate: compareVersions(currentVersion, latestVersion) >= 0,
-        releaseUrl: latest.html_url || null,
-      };
+      lastUpdateInfo = await checkForUpdates({ repo: GITHUB_REPO, currentVersion });
+      return lastUpdateInfo;
     } catch (error) {
       return {
         currentVersion,
@@ -436,6 +396,31 @@ function registerIpcHandlers() {
     }
   });
 
+  ipcMain.handle('tokendash:download-update', async (event) => {
+    if (isDownloadingUpdate) {
+      return { ok: false, error: 'An update download is already in progress.' };
+    }
+
+    const info = lastUpdateInfo;
+    if (!info || info.upToDate || !info.asset || !info.asset.url) {
+      return { ok: false, error: 'No downloadable update is available.' };
+    }
+
+    isDownloadingUpdate = true;
+    try {
+      const downloadsDir = path.join(app.getPath('downloads'), 'TokenDash Updates');
+      const filePath = await downloadUpdateAsset(info.asset, downloadsDir, (progress) => {
+        event.sender.send('tokendash:update-download-progress', progress);
+      });
+      await shell.openPath(filePath);
+      return { ok: true, filePath };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    } finally {
+      isDownloadingUpdate = false;
+    }
+  });
+
   ipcMain.handle('tokendash:quit', () => {
     app.isQuitting = true;
     stopBadgeUpdates();

package/electron/preload.cjs

@@ -13,6 +13,17 @@ contextBridge.exposeInMainWorld('electronAPI', {
   checkForUpdates() {
     return ipcRenderer.invoke('tokendash:check-for-updates');
   },
+  downloadUpdate(updateInfo) {
+    return ipcRenderer.invoke('tokendash:download-update', updateInfo);
+  },
+  onUpdateDownloadProgress(callback) {
+    if (typeof callback !== 'function') return function noop() {};
+    const listener = (_event, progress) => callback(progress);
+    ipcRenderer.on('tokendash:update-download-progress', listener);
+    return function unsubscribe() {
+      ipcRenderer.removeListener('tokendash:update-download-progress', listener);
+    };
+  },
   quitApp() {
     return ipcRenderer.invoke('tokendash:quit');
   },

package/electron/updateService.cjs

@@ -0,0 +1,148 @@
+const fs = require('node:fs');
+const https = require('node:https');
+const path = require('node:path');
+
+function fetchHttpsJson(url) {
+  return new Promise((resolve, reject) => {
+    const opts = new URL(url);
+    const reqOpts = {
+      hostname: opts.hostname,
+      path: opts.pathname + opts.search,
+      method: 'GET',
+      headers: {
+        Accept: 'application/vnd.github+json',
+        'User-Agent': 'TokenDash',
+      },
+    };
+
+    https.get(reqOpts, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => {
+        if (res.statusCode && res.statusCode >= 400) {
+          reject(new Error(`HTTP ${res.statusCode}`));
+          return;
+        }
+        try { resolve(JSON.parse(data)); }
+        catch (e) { reject(e); }
+      });
+    }).on('error', reject);
+  });
+}
+
+function compareVersions(a, b) {
+  const aParts = String(a).replace(/^v/, '').split(/[.-]/).map((part) => parseInt(part, 10) || 0);
+  const bParts = String(b).replace(/^v/, '').split(/[.-]/).map((part) => parseInt(part, 10) || 0);
+  const maxLen = Math.max(aParts.length, bParts.length);
+  for (let i = 0; i < maxLen; i++) {
+    const delta = (aParts[i] || 0) - (bParts[i] || 0);
+    if (delta !== 0) return delta;
+  }
+  return 0;
+}
+
+function isDmgAsset(asset) {
+  return Boolean(asset && typeof asset.name === 'string' && /\.dmg$/i.test(asset.name));
+}
+
+function selectMacDmgAsset(assets, arch = process.arch) {
+  const dmgAssets = (Array.isArray(assets) ? assets : []).filter(isDmgAsset);
+  if (dmgAssets.length === 0) return null;
+
+  const archNeedle = arch === 'arm64' ? 'arm64' : arch === 'x64' ? 'x64' : '';
+  if (archNeedle) {
+    const archMatch = dmgAssets.find((asset) => asset.name.toLowerCase().includes(archNeedle));
+    if (archMatch) return archMatch;
+  }
+
+  const universal = dmgAssets.find((asset) => /universal/i.test(asset.name));
+  return universal || dmgAssets[0];
+}
+
+function getReleaseUpdateInfo(release, currentVersion, arch = process.arch) {
+  const tag = String((release && release.tag_name) || '').replace(/^v/, '');
+  const latestVersion = tag || currentVersion;
+  const asset = selectMacDmgAsset(release && release.assets, arch);
+  const upToDate = compareVersions(currentVersion, latestVersion) >= 0;
+
+  return {
+    currentVersion,
+    latestVersion,
+    upToDate,
+    releaseUrl: (release && release.html_url) || null,
+    asset: asset ? {
+      name: asset.name,
+      size: Number(asset.size) || 0,
+      url: asset.browser_download_url,
+    } : null,
+  };
+}
+
+async function checkForUpdates({ repo, currentVersion, arch = process.arch }) {
+  const release = await fetchHttpsJson(`https://api.github.com/repos/${repo}/releases/latest`);
+  return getReleaseUpdateInfo(release, currentVersion, arch);
+}
+
+function safeDownloadName(name) {
+  return path.basename(String(name || 'TokenDash-update.dmg')).replace(/[^\w .()+@-]/g, '-');
+}
+
+function downloadFile(url, destination, onProgress) {
+  return new Promise((resolve, reject) => {
+    const file = fs.createWriteStream(destination);
+    let received = 0;
+
+    const request = https.get(url, { headers: { 'User-Agent': 'TokenDash' } }, (res) => {
+      if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location) {
+        file.close(() => fs.rm(destination, { force: true }, () => {}));
+        downloadFile(res.headers.location, destination, onProgress).then(resolve, reject);
+        return;
+      }
+
+      if (res.statusCode && res.statusCode >= 400) {
+        file.close(() => fs.rm(destination, { force: true }, () => {}));
+        reject(new Error(`HTTP ${res.statusCode}`));
+        return;
+      }
+
+      const total = Number(res.headers['content-length']) || 0;
+      res.on('data', (chunk) => {
+        received += chunk.length;
+        if (typeof onProgress === 'function') {
+          onProgress({ received, total, percent: total > 0 ? Math.round((received / total) * 100) : null });
+        }
+      });
+      res.pipe(file);
+    });
+
+    request.on('error', (error) => {
+      file.close(() => fs.rm(destination, { force: true }, () => {}));
+      reject(error);
+    });
+
+    file.on('finish', () => {
+      file.close(() => resolve(destination));
+    });
+
+    file.on('error', (error) => {
+      file.close(() => fs.rm(destination, { force: true }, () => {}));
+      reject(error);
+    });
+  });
+}
+
+async function downloadUpdateAsset(asset, downloadsDir, onProgress) {
+  if (!asset || !asset.url) throw new Error('No downloadable macOS update asset was found.');
+  fs.mkdirSync(downloadsDir, { recursive: true });
+  const destination = path.join(downloadsDir, safeDownloadName(asset.name));
+  await downloadFile(asset.url, destination, onProgress);
+  return destination;
+}
+
+module.exports = {
+  checkForUpdates,
+  compareVersions,
+  downloadUpdateAsset,
+  getReleaseUpdateInfo,
+  selectMacDmgAsset,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhangferry-dev/tokendash",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Token Usage Analytics Dashboard",
   "publishConfig": {