tacilytics 0.0.0-stage → 2.0.2

package/.env.example

@@ -0,0 +1,23 @@
+# ── Tacilytics configuration — copy to .env and fill in ──
+# Port (bound to 127.0.0.1; put a reverse proxy / TLS in front)
+PORT=3920
+
+# Dashboard passphrase (plaintext; keep .env at chmod 600)
+WEB_PASSWORD=change-me-to-a-strong-passphrase
+
+# Secret for signing session tokens — long random string
+#   node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"
+SESSION_SECRET=change-me
+
+# Salt for the daily one-way visitor hash (rotate to reset all visitor identities)
+#   node -e "console.log(require('crypto').randomBytes(24).toString('hex'))"
+INGEST_SALT=change-me
+
+# SQLite database path
+DB_PATH=./data/analytics.db
+
+# API key for agents / CLI (Bearer token) — generate a long random string
+API_KEY=change-me
+
+# Data minimisation: auto-purge raw events older than N days (0 = keep forever)
+DATA_RETENTION_DAYS=0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nyx & Fabian Budde
+
+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,3 +1,254 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="public/assets/tacilytics-mark.svg" width="96" alt="Tacilytics" />
+
+# Tacilytics
+
+**Privacy-first, cookieless analytics for websites and apps — self-hosted in minutes.**
+*Tacit* (adj.): understood without being said. Tacilytics counts what matters and keeps quiet about who did it — one tiny script, one Node process, one SQLite file. No cookies, no consent banner, no creepy tracking. (And in Italian, *taci* simply means "be quiet".)
+
+> Formerly **Nyx Analytics**. Existing installs keep working: `/nyx.js`, `window.nyx()` and the old Flutter class names are still supported as aliases.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-a855f7.svg)](LICENSE)
+![Cookieless](https://img.shields.io/badge/cookies-zero-e879a8)
+![No tracking](https://img.shields.io/badge/IPs%20stored-never-67e8f9)
+![Node](https://img.shields.io/badge/node-%3E%3D18-4ade80)
+
+<img src="docs/dashboard.png" width="820" alt="Tacilytics dashboard" />
+
+</div>
+
+---
+
+## Why Tacilytics
+
+- 🍪 **Cookieless & banner-free.** No cookies, no `localStorage`, no fingerprinting — nothing to consent to.
+- 🛡️ **IPs are never stored.** Unique visitors are counted with a *daily, salted, one-way hash* that’s irreversible and rotated every day.
+- 🌍 **Region from the browser timezone**, never from IP geolocation.
+- 🔍 **Segment everything.** Click any country, page, source, browser or campaign to filter the whole dashboard — stacked, with one-click chips.
+- 🚦 **Campaigns & funnels.** Full UTM (`source` / `medium` / `campaign`), entry & exit pages, **goal conversion rates** and **custom event properties**.
+- ⏱️ **Engagement time** — average time-on-page, measured privately (visible seconds only, no extra identifier).
+- 🤖 **Bots & crawlers dropped** automatically, so your numbers stay honest.
+- ⚡ **~2 KB tracker**, SPA-aware (tracks `pushState` / `popstate` route changes), optional **DNT / Global Privacy Control** honoring.
+- 🗓️ **Data minimisation built in** — optional auto-purge of raw events after a retention window you choose.
+- 🎯 **Custom events & goals**, **live visitors**, **trends**, **custom date ranges**, **CSV export**.
+- 🛰️ **Agent-ready:** a clean `/api/v1` REST API (with segmentation params) + a `tacilytics` CLI (with `--json`).
+- 🗄️ **Zero infra:** Express + SQLite. No Redis, no ClickHouse, no cloud.
+
+## Quick start
+
+**With npm** (fastest):
+
+```bash
+mkdir my-analytics && cd my-analytics
+npx tacilytics serve      # http://127.0.0.1:3920 — data/ and .env live in this folder
+```
+
+Or install it globally: `npm i -g tacilytics`, then `tacilytics serve`.
+Set your own `WEB_PASSWORD`, `SESSION_SECRET`, `INGEST_SALT` and `API_KEY` in a `.env` file in that folder (see [`.env.example`](.env.example)).
+
+**From source:**
+
+```bash
+git clone https://github.com/Open-Cosmic-Software/tacilytics.git
+cd tacilytics
+npm install
+cp .env.example .env     # set WEB_PASSWORD, SESSION_SECRET, INGEST_SALT, API_KEY
+npm start                # http://127.0.0.1:3920
+```
+
+The server binds to `127.0.0.1` — put TLS in front. Example **Caddy**:
+
+```
+analytics.example.com {
+    encode gzip
+    reverse_proxy 127.0.0.1:3920
+}
+```
+
+Open the dashboard, log in, click **+ Add site**, and drop the snippet into your `<head>`:
+
+```html
+<script defer data-domain="example.com" src="https://analytics.example.com/tacilytics.js"></script>
+```
+
+That’s it. Pageviews start flowing in — no cookie banner required.
+
+## Custom events, goals & properties
+
+Track conversions from anywhere in your code — optionally with **properties** to break them down:
+
+```js
+tacilytics('Signup');
+tacilytics('Upgrade', { plan: 'pro' });
+tacilytics('Purchase', { plan: 'pro', amount: '49' });
+```
+
+Goals show up in the **Goals & conversions** panel with a **conversion rate** (% of visitors). Click a goal to drill into it — the whole dashboard re-segments to converters, and each property’s top values appear as their own breakdown. Pageviews stay separate, so your view counts stay clean.
+
+## Segment everything
+
+Click any row — a country, page, source, browser, OS, device, language or campaign — to **filter the entire dashboard** to that segment. Filters stack and show as removable chips. The same segmentation is available over the API and CLI:
+
+```bash
+tacilytics stats example.com 30d --country=DE --source=twitter.com
+curl -H "Authorization: Bearer $TACILYTICS_API_KEY" \
+  "https://analytics.example.com/api/v1/stats?site=example.com&period=30d&country=DE&medium=email"
+```
+
+## Campaigns, entry/exit & engagement
+
+- **UTM campaigns** — `utm_source` / `utm_medium` / `utm_campaign` are captured automatically; switch the Sources panel between **Source / Medium / Campaign**.
+- **Entry & exit pages** — switch the Pages panel between **Top / Entry / Exit** to see where visits start and end.
+- **Engagement time** — the tracker reports how long each page was actually *visible* (a follow-up beacon, no new identifier), surfaced as **Avg. visit time**.
+- **Custom date range** — pick any `from`/`to` window in the toolbar, or pass `--from`/`--to` to the API/CLI.
+
+## Privacy controls on the tag
+
+Opt-in flags on the `<script>` tag:
+
+```html
+<script defer data-domain="example.com"
+        data-honor-dnt          <!-- skip tracking if DNT / Global Privacy Control is on -->
+        data-track-outbound     <!-- auto-record clicks to other domains as events -->
+        src="https://analytics.example.com/tacilytics.js"></script>
+```
+
+## Mobile & desktop apps
+
+Track your **native app in the same dashboard as your website**. Every row gets a platform
+(`web`, `android`, `ios`, `macos`, `windows`, `linux`), so you can see everything together or
+click a platform to filter. Once an app reports in, you get a **Platforms** panel (plus app
+versions) and **Revenue by platform**.
+
+**Flutter** — a ready-made package lives in [`sdk/flutter`](sdk/flutter):
+
+```dart
+Tacilytics.init(endpoint: 'https://analytics.example.com', domain: 'example.com', appVersion: '1.4.0');
+Tacilytics.instance.setEnabled(userConsented);       // off until you say so — wire it to your consent
+MaterialApp(navigatorObservers: [TacilyticsRouteObserver()]); // automatic screen views
+Tacilytics.instance.search('vinegar', 6);
+Tacilytics.instance.purchase(value: 49.90, currency: 'EUR', items: 2);
+```
+
+**Any other stack** (Swift, Kotlin, React Native, …) — it is one JSON `POST /api/collect`:
+
+| field | meaning |
+|---|---|
+| `d` | site domain (as registered) |
+| `p` | screen, written like a path (`/product/42`) |
+| `pf` | platform: `android` · `ios` · `macos` · `windows` · `linux` |
+| `sid` | random id drawn **per app launch**, kept in memory only (16–64 chars `A-Za-z0-9_-`) |
+| `av` | app version (optional) |
+| `dv` | `mobile` · `tablet` · `desktop` (optional) |
+| `l` / `cc` | language tag / 2-letter region of the device locale (optional) |
+| `n` / `pr` | event name + flat properties, same as the web `tacilytics()` call (optional) |
+| `s` / `um` / `uc` | utm source / medium / campaign, e.g. from a deep link (optional) |
+
+Send any non-empty, non-bot `User-Agent` (e.g. `MyApp/1.4 (android)`).
+
+Privacy stays the same as on the web: **no device or advertising id, no cookies, no IP stored.**
+The server hashes the launch id with a random daily salt that is deleted when the day ends, so a visitor is never followed across days.
+Without `sid`, the usual IP + user-agent daily hash is used. Region comes from the timezone or
+device locale, never from IP geolocation.
+
+## Live visitors
+
+Click **“● online now”** for a realtime view: a 30-minute pulse and a live feed of
+who’s on the site right now — page, goal, country, browser/device and source —
+auto-refreshing every few seconds.
+
+<div align="center"><img src="docs/live.png" width="560" alt="Live visitors" /></div>
+
+## Agent API
+
+Everything the dashboard shows is available over a stable REST API, authenticated with a Bearer key:
+
+```bash
+curl -H "Authorization: Bearer $TACILYTICS_API_KEY" \
+  "https://analytics.example.com/api/v1/stats?site=example.com&period=30d"
+```
+
+| Method & path | Description |
+|---|---|
+| `GET /api/v1` | API discovery |
+| `GET /api/v1/sites` | list tracked sites |
+| `POST /api/v1/sites` | add a site `{ domain }` |
+| `GET /api/v1/stats?site=&period=` | aggregated stats — `today \| 7d \| 30d \| 90d \| 12mo`, or `from=YYYY-MM-DD&to=YYYY-MM-DD` |
+| `GET /api/v1/realtime?site=` | online count, 30-min pulse + recent events |
+
+Add any of `country, source, page, browser, os, device, lang, medium, campaign, goal` to `/stats` to segment, e.g. `…/stats?site=example.com&period=30d&country=DE&medium=email`.
+
+## CLI
+
+```bash
+export TACILYTICS_URL=https://analytics.example.com
+export TACILYTICS_API_KEY=xxx
+
+tacilytics sites
+tacilytics stats example.com 30d
+tacilytics live example.com --watch
+tacilytics add example.com
+```
+
+Add `--json` to any command for machine-readable output — perfect for agents and scripts.
+
+## How it works
+
+`tacilytics.js` sends a tiny beacon (`navigator.sendBeacon`, `text/plain` so the cross-origin
+request stays preflight-free) with the path, referrer, timezone and language — no
+personal data, no cookies. The server parses the User-Agent (browser/OS/device),
+drops bots, maps timezone → country, derives the **daily visitor hash**, and stores one
+row per pageview. The dashboard aggregates it with plain SQL.
+
+**The cookieless trade-off, honestly:** because there’s no persistent identifier, Tacilytics
+counts unique visitors *per day* and can’t follow the same person across days or
+devices. You get the 95 % that matters (how many, which pages, from where) with 0 %
+cookie banner — the same approach as Plausible/Fathom.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `PORT` | `3920` | Port (bound to 127.0.0.1) |
+| `WEB_PASSWORD` | `tacilytics` | Dashboard passphrase |
+| `SESSION_SECRET` | random | Session-token secret |
+| `INGEST_SALT` | fixed | Extra server-side secret mixed into the visitor hash (on top of the random daily salt) |
+| `API_KEY` | — | Bearer key for the API / CLI |
+| `DB_PATH` | `./data/analytics.db` | SQLite path |
+| `DATA_RETENTION_DAYS` | `0` | `0` = keep forever; `>0` purges raw events older than N days, daily (data minimisation) |
+
+## Privacy & security
+
+- No cookies, no cross-site tracking, **IPs never persisted**.
+- Daily one-way visitor hash with a **random salt per day**. It lives in its own small file (`data/.day-salt`, mode 600), never in the database, and is overwritten in place when the next day starts. Past days can't be re-linked afterwards, not even with the database, a known IP or user agent, or the server's own secrets. Only the server clock picks the day; late or out-of-day events get an unlinkable one-off hash.
+  - **Honest limits of "overwritten":** on ext4 an in-place overwrite really replaces the bytes. On copy-on-write filesystems (btrfs, ZFS), in filesystem or VM snapshots, and on SSDs (wear levelling) the old block can physically survive. **Backups of `data/` contain the salt of the day they were taken**, so treat them like the live server or exclude `data/.day-salt` from them.
+  - **One process only.** The salt is drawn by the single Node process. Running several processes against the same `data/` would let each draw its own salt at midnight.
+- **Data minimisation:** set `DATA_RETENTION_DAYS` to auto-purge raw events after your chosen window.
+- **Respects DNT / Global Privacy Control** when you add `data-honor-dnt` to the tag.
+- Engagement time adds **no new identifier** — it’s matched to the visitor’s own daily hash server-side.
+- Custom event properties are capped (scalars only, size-limited) so they can’t become a PII dumping ground.
+- Timing-safe auth; login and the collect endpoint are rate-limited.
+- All visitor-supplied values are HTML-escaped before they reach the DOM.
+- Run behind TLS; keep `.env` at `chmod 600`.
+
+## Tacilytics vs. Google Analytics
+
+| | Tacilytics | Google Analytics |
+|---|---|---|
+| Cookies / consent banner | ❌ none | ✅ required |
+| Stores IPs / personal data | ❌ never | ✅ yes |
+| Self-hosted, you own the data | ✅ | ❌ |
+| Weight | ~2 KB | ~45 KB+ |
+| Setup | 1 script + 1 process | tag manager, config… |
+
+## Credits
+
+- UI icons: [Lucide](https://lucide.dev) (ISC)
+- Brand marks: [Simple Icons](https://simpleicons.org) (CC0). Brand names and logos are trademarks of their owners; see `public/assets/DISCLAIMER-simple-icons.md`. Windows and Edge have no free official mark, so a neutral icon is shown.
+- Flags: [flag-icons](https://flagicons.lipis.dev) (MIT)
+- Font: [Inter](https://rsms.me/inter/) (SIL OFL 1.1), self-hosted
+
+## License
+
+[MIT](LICENSE) — built by **Nyx & Fabian** 🦞

package/cli.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+/* Tacilytics CLI — query your analytics from the terminal or an agent.
+ *
+ *   export TACILYTICS_URL=https://analytics.example.com
+ *   export TACILYTICS_API_KEY=xxx
+ *   tacilytics serve            (start the server; data/ and .env in the current directory)
+ *   tacilytics serve       start the server (data/ and .env in the current folder)
+ *   tacilytics sites
+ *   tacilytics stats example.com 30d
+ *   tacilytics live example.com --watch
+ *   tacilytics add example.com
+ *
+ * NYX_URL / NYX_API_KEY are still read for setups from before the rename.
+ *
+ * Add --json to any command for raw machine-readable output (for agents).
+ */
+'use strict';
+
+const URL_BASE = (process.env.TACILYTICS_URL || process.env.NYX_URL || 'http://localhost:3920').replace(/\/$/, '');
+const KEY = process.env.TACILYTICS_API_KEY || process.env.NYX_API_KEY || '';
+const args = process.argv.slice(2);
+const JSON_OUT = args.includes('--json');
+const WATCH = args.includes('--watch');
+const pos = args.filter((a) => !a.startsWith('--'));
+const cmd = pos[0];
+// --key=value flags → extra query params (filters: country,source,page,browser,os,device,lang,medium,campaign,goal · range: from,to)
+const flags = {};
+args.filter((a) => a.startsWith('--') && a.includes('=')).forEach((a) => { const i = a.indexOf('='); flags[a.slice(2, i)] = a.slice(i + 1); });
+function extraQuery() { return Object.keys(flags).filter((k) => k !== 'json' && k !== 'watch').map((k) => '&' + encodeURIComponent(k) + '=' + encodeURIComponent(flags[k])).join(''); }
+const fmtDur = (s) => (s == null ? '—' : s < 60 ? s + 's' : Math.floor(s / 60) + 'm' + (s % 60 ? ' ' + (s % 60) + 's' : ''));
+
+// ── tiny ANSI helpers ──
+const C = process.stdout.isTTY && !JSON_OUT;
+const c = (n, s) => (C ? `\x1b[${n}m${s}\x1b[0m` : s);
+const pink = (s) => c('38;5;211', s), purple = (s) => c('38;5;141', s), cyan = (s) => c('38;5;87', s);
+const dim = (s) => c('2', s), bold = (s) => c('1', s), green = (s) => c('38;5;120', s), red = (s) => c('38;5;210', s);
+
+function die(msg) { console.error(red('✖ ' + msg)); process.exit(1); }
+
+async function api(path) {
+  if (!KEY) die('Set TACILYTICS_API_KEY (and optionally TACILYTICS_URL).');
+  const res = await fetch(URL_BASE + path, { headers: { Authorization: 'Bearer ' + KEY } });
+  if (res.status === 401) die('Unauthorized — check TACILYTICS_API_KEY.');
+  const j = await res.json().catch(() => ({}));
+  if (!res.ok) die(j.error || ('HTTP ' + res.status));
+  return j;
+}
+async function post(path, body) {
+  if (!KEY) die('Set TACILYTICS_API_KEY (and optionally TACILYTICS_URL).');
+  const res = await fetch(URL_BASE + path, { method: 'POST', headers: { Authorization: 'Bearer ' + KEY, 'Content-Type': 'application/json' }, body: JSON.stringify(body) });
+  const j = await res.json().catch(() => ({}));
+  if (!res.ok) die(j.error || ('HTTP ' + res.status));
+  return j;
+}
+
+const flag = (cc) => (cc && cc.length === 2 ? cc.toUpperCase().replace(/./g, (x) => String.fromCodePoint(127397 + x.charCodeAt(0))) : '🌐');
+const pad = (s, n) => (String(s) + ' '.repeat(n)).slice(0, n);
+function bar(rows, key) {
+  if (!rows || !rows.length) return '  ' + dim('(none)');
+  const max = Math.max.apply(null, rows.map((r) => r[key] || 0)) || 1;
+  return rows.map((r) => {
+    const w = Math.round(((r[key] || 0) / max) * 22);
+    return '  ' + pad(r.label || r.name, 30) + ' ' + purple('▇'.repeat(w) || '▏') + ' ' + bold(r[key]);
+  }).join('\n');
+}
+
+function banner(t) { if (!JSON_OUT) console.log('\n' + pink('🦞 ') + bold(t)); }
+
+async function cmdSites() {
+  const sites = await api('/api/v1/sites');
+  if (JSON_OUT) return console.log(JSON.stringify(sites, null, 2));
+  banner('Sites');
+  if (!sites.length) return console.log('  ' + dim('No sites yet. Add one:  tacilytics add example.com'));
+  sites.forEach((s) => console.log('  ' + cyan(pad(s.domain, 28)) + dim('  id ' + s.id)));
+}
+
+async function cmdStats() {
+  const domain = pos[1] || die('Usage: tacilytics stats <domain> [period] [--country=DE] [--from=YYYY-MM-DD --to=YYYY-MM-DD]');
+  const period = pos[2] || '7d';
+  const range = flags.from && flags.to ? '' : `&period=${period}`;
+  const s = await api(`/api/v1/stats?site=${encodeURIComponent(domain)}${range}${extraQuery()}`);
+  if (JSON_OUT) return console.log(JSON.stringify(s, null, 2));
+  const t = s.totals, tr = s.trend || {};
+  const trend = (v) => (v == null ? '' : ' ' + (v >= 0 ? green('▲' + v + '%') : red('▼' + Math.abs(v) + '%')));
+  const label = s.range ? `${s.range.from} → ${s.range.to}` : period;
+  banner(`${domain}  ·  ${label}`);
+  const active = Object.keys(s.filters || {});
+  if (active.length) console.log('  ' + dim('filtered by ' + active.map((k) => k + '=' + s.filters[k]).join(', ')));
+  console.log('  ' + pad('Visitors', 16) + bold(t.visitors) + trend(tr.visitors));
+  console.log('  ' + pad('Pageviews', 16) + bold(t.pageviews) + trend(tr.pageviews));
+  console.log('  ' + pad('Bounce', 16) + bold(t.bounce + '%'));
+  console.log('  ' + pad('Views/visitor', 16) + bold(t.viewsPerVisitor));
+  console.log('  ' + pad('Avg. visit time', 16) + bold(fmtDur(t.duration)));
+  console.log('\n' + dim('  Top pages')); console.log(bar(s.pages, 'visitors'));
+  if (s.entryPages && s.entryPages.length) { console.log('\n' + dim('  Entry pages')); console.log(bar(s.entryPages, 'visitors')); }
+  console.log('\n' + dim('  Sources')); console.log(bar(s.sources, 'visitors'));
+  if (s.campaigns && s.campaigns.length) { console.log('\n' + dim('  Campaigns')); console.log(bar(s.campaigns, 'visitors')); }
+  console.log('\n' + dim('  Locations')); console.log(bar((s.countries || []).map((r) => ({ name: flag(r.name) + ' ' + r.name, visitors: r.visitors })), 'visitors'));
+  if (s.goals && s.goals.length) {
+    console.log('\n' + dim('  Goals  ' + dim('(conversion)')));
+    console.log(bar(s.goals.map((g) => ({ name: g.name + dim('  ' + (g.cr != null ? g.cr + '%' : '')), visitors: g.visitors })), 'visitors'));
+  }
+}
+
+async function renderLive(domain) {
+  const r = await api(`/api/v1/realtime?site=${encodeURIComponent(domain)}`);
+  if (JSON_OUT) return console.log(JSON.stringify(r, null, 2));
+  if (WATCH) process.stdout.write('\x1b[2J\x1b[H'); // clear
+  banner(`Live · ${domain}`);
+  console.log('  ' + green('● ') + bold(r.online) + ' online now' + dim('  (last 5 min)'));
+  const spark = '▁▂▃▄▅▆▇█';
+  const max = Math.max.apply(null, r.minutes.map((m) => m.pageviews).concat([1]));
+  const line = r.minutes.map((m) => (m.pageviews ? spark[Math.min(7, Math.round((m.pageviews / max) * 7))] : dim('·'))).join('');
+  console.log('  ' + purple(line) + dim('  ← 30 min'));
+  console.log('\n' + dim('  Recent activity'));
+  if (!r.recent.length) return console.log('  ' + dim('(quiet)'));
+  r.recent.slice(0, 20).forEach((e) => {
+    const ago = Math.round((r.now - e.ts) / 1000);
+    const t = ago < 8 ? 'now' : ago < 60 ? ago + 's' : Math.round(ago / 60) + 'm';
+    const what = e.name ? pink('🎯 ' + e.name) : e.path;
+    const src = e.source && e.source !== 'Direct' ? dim(' ↗ ' + e.source) : '';
+    console.log('  ' + flag(e.country) + ' ' + pad(what, 32) + ' ' + dim(pad((e.browser || '') + ' · ' + (e.device || ''), 20)) + src + dim('  ' + t));
+  });
+}
+async function cmdLive() {
+  const domain = pos[1] || die('Usage: tacilytics live <domain> [--watch]');
+  await renderLive(domain);
+  if (WATCH && !JSON_OUT) setInterval(() => renderLive(domain).catch(() => {}), 5000);
+}
+
+async function cmdAdd() {
+  const domain = pos[1] || die('Usage: tacilytics add <domain>');
+  const s = await post('/api/v1/sites', { domain });
+  if (JSON_OUT) return console.log(JSON.stringify(s, null, 2));
+  banner('Site added: ' + s.domain);
+  console.log('\n  Embed this in your site <head>:\n');
+  console.log('  ' + cyan(`<script defer data-domain="${s.domain}" src="${URL_BASE}/tacilytics.js"></script>`));
+}
+
+function help() {
+  console.log(`
+${pink('Tacilytics CLI')}
+
+${bold('Usage')}  tacilytics <command> [--json] [--watch]
+
+  ${cyan('serve')}                     start the server (data/ + .env in the current folder)
+  ${cyan('sites')}                     list tracked sites
+  ${cyan('stats')} <domain> [period]   key metrics + breakdowns (today|7d|30d|90d|12mo)
+  ${cyan('live')} <domain> [--watch]   online visitors + last-30-min feed
+  ${cyan('add')} <domain>              add a site, print the embed snippet
+
+${bold('Segment & range')} (on stats)
+  ${dim('--country=DE --source=… --page=… --browser=… --medium=… --campaign=… --goal=…')}
+  ${dim('--from=2026-01-01 --to=2026-01-31')}   custom date range
+
+${bold('Config')} (env)
+  TACILYTICS_URL       ${dim(URL_BASE)}
+  TACILYTICS_API_KEY   ${KEY ? green('set') : red('not set')}
+
+${dim('Add --json for machine-readable output (agents).')}
+`);
+}
+
+(async () => {
+  try {
+    if (cmd === 'serve' || cmd === 'start') { require('./server.js'); return; }
+    if (cmd === 'sites') await cmdSites();
+    else if (cmd === 'stats') await cmdStats();
+    else if (cmd === 'live' || cmd === 'realtime') await cmdLive();
+    else if (cmd === 'add') await cmdAdd();
+    else help();
+  } catch (e) { die(e.message || String(e)); }
+})();

package/day-salt.js

@@ -0,0 +1,55 @@
+'use strict';
+// Daily salt (13.10.2026, hardened after two reviews by Tyto 🦉): a fresh random secret per
+// UTC day, kept in its own small file, never in the database. See README "Privacy & security".
+//
+// Rules:
+// - Only the server clock decides the day. A salt is only ever created for *today*.
+// - A file with today's date but an invalid salt (e.g. truncated by a crash) is repaired by
+//   drawing a new salt. Otherwise every visitor would get a one-off hash until midnight.
+// - Only a file from a *later* day than our clock (clock went backwards) is left alone: then
+//   we return null and the caller uses an unlinkable one-off hash.
+// - Single process only. nyx-analytics runs one Node process (one app.listen, no cluster).
+//   With several processes, each would draw its own salt at midnight and the last writer
+//   would win; that would need an O_EXCL create + re-read instead.
+const fs = require('fs');
+const crypto = require('crypto');
+
+const SIZE = 128; // fixed size → the old value is fully overwritten in place
+const VALID = /^[0-9a-f]{64}$/;
+
+function dayStr(ts) { return new Date(ts).toISOString().slice(0, 10); }
+
+function createDaySalt(file, now = Date.now) {
+  let cache = { day: null, salt: null };
+
+  function writeInPlace(content) {
+    const buf = Buffer.alloc(SIZE, 0); buf.write(content);
+    const fd = fs.openSync(file, fs.existsSync(file) ? 'r+' : 'w', 0o600);
+    try { fs.fchmodSync(fd, 0o600); fs.writeSync(fd, buf, 0, buf.length, 0); fs.fsyncSync(fd); }
+    finally { fs.closeSync(fd); }
+  }
+
+  function read() {
+    try { return fs.readFileSync(file, 'utf8').replace(/\0+$/, '').split(' '); } catch { return null; }
+  }
+
+  return function todaysSalt() {
+    const today = dayStr(now());
+    if (cache.day === today) return cache.salt;
+    const stored = read();
+    const storedDay = stored && stored[0];
+    if (storedDay === today && VALID.test(stored[1] || '')) {
+      cache = { day: today, salt: stored[1] };
+    } else if (!storedDay || storedDay <= today) {
+      // missing, older day, or today's date with a broken salt → draw a new one
+      const salt = crypto.randomBytes(32).toString('hex');
+      writeInPlace(`${today} ${salt}`);
+      cache = { day: today, salt };
+    } else {
+      return null; // file is from a later day than our clock: never overwrite a newer salt
+    }
+    return cache.salt;
+  };
+}
+
+module.exports = { createDaySalt, dayStr };

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "tacilytics",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.2",
+  "description": "Privacy-first, cookieless analytics for websites and apps. Self-hosted: one Node process, one SQLite file.",
+  "main": "server.js",
+  "type": "commonjs",
+  "scripts": {
+    "start": "node server.js",
+    "cli": "node cli.js",
+    "test": "node --test test/*.test.js"
+  },
+  "author": "Nyx 🦞 & Fabian Budde",
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^12.10.0",
+    "express": "^4.21.2"
+  },
+  "bin": {
+    "tacilytics": "cli.js",
+    "nyx": "cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Open-Cosmic-Software/tacilytics.git"
+  },
+  "homepage": "https://github.com/Open-Cosmic-Software/tacilytics#readme",
+  "keywords": [
+    "analytics",
+    "privacy",
+    "cookieless",
+    "gdpr",
+    "self-hosted",
+    "web-analytics",
+    "sqlite",
+    "plausible-alternative",
+    "flutter",
+    "app-analytics"
+  ],
+  "bugs": {
+    "url": "https://github.com/Open-Cosmic-Software/tacilytics/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "server.js",
+    "cli.js",
+    "day-salt.js",
+    "tz-country.js",
+    "public/",
+    "sdk/flutter/",
+    "!sdk/flutter/.dart_tool/",
+    "!sdk/flutter/build/",
+    ".env.example",
+    "LICENSE",
+    "README.md"
+  ]
+}