feat: anonymous opt-in telemetry module (#91)

Author: Benzilla

.env.example

@@ -66,3 +66,7 @@ LIVEMODE=
 # hosting, POST /v1/billing/run with x-operator-key via cron / Cloud Scheduler.
 # BILLING_MONITOR_ENABLED=false
 # BILLING_POLL_INTERVAL_MS=60000
+
+# Anonymous usage telemetry (opt-in via setup/settings; off by default).
+# Set to 0 to force disable.
+# ZONELESS_TELEMETRY=

.env.production.example

@@ -59,4 +59,8 @@ LIVEMODE=true
 # Trigger POST /v1/billing/run from Cloud Scheduler with x-operator-key,
 # or POST /v1/billing/run_for_platform with a platform API key.
 # BILLING_MONITOR_ENABLED=false
-# BILLING_POLL_INTERVAL_MS=60000
+# BILLING_POLL_INTERVAL_MS=60000
+
+# Anonymous usage telemetry (opt-in via setup/settings; off by default).
+# Set to 0 to force disable.
+# ZONELESS_TELEMETRY=

README.md

@@ -172,6 +172,11 @@ zoneless/
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, style guidelines, and the pull request process.
 
+## Anonymous usage telemetry
+
+Self-hosted Zoneless can optionally share anonymous usage heartbeats with
+maintainers (opt-in, off by default). See [TELEMETRY.md](./TELEMETRY.md).
+
 ## Security
 
 See [SECURITY.md](./SECURITY.md) to report vulnerabilities.

SECURITY.md

@@ -49,6 +49,11 @@ Key points:
 - Never commit `.env` files to version control
 - Rotate API keys periodically
 
+### Anonymous usage telemetry
+
+Opt-in anonymous usage heartbeats may be sent to zoneless.com (off by default).
+Force disable with `ZONELESS_TELEMETRY=0`. See [TELEMETRY.md](./TELEMETRY.md).
+
 ## Acknowledgments
 
 We would like to thank the following individuals for responsibly disclosing security issues.

TELEMETRY.md

@@ -0,0 +1,37 @@
+# Anonymous Usage Telemetry
+
+Zoneless can optionally send **anonymous, aggregate usage heartbeats** to
+[zoneless.com](https://zoneless.com). Telemetry is **opt-in and off by default**,
+and only applies to **self-hosted** instances (not operator-managed hosting).
+
+## Consent
+
+Enable via the checkbox during setup or under **Settings → Anonymous usage**,
+or `POST /v1/telemetry` with `{ "enabled": true }` as a platform user.
+
+Disable the same way, or set `ZONELESS_TELEMETRY=0`.
+
+## What is sent
+
+One HTTPS POST roughly once per day when enabled **and** `LIVEMODE=true`.
+Test-mode instances (`LIVEMODE` unset/false) never send; consent can still be
+saved and will take effect after switching to live mode.
+
+| Field                   | Description                                                                                           |
+| ----------------------- | ----------------------------------------------------------------------------------------------------- |
+| `instance_id`           | Random UUID generated at opt-in                                                                       |
+| `zoneless_version`      | Package version string                                                                                |
+| `livemode`              | Always `true` when a report is sent (test mode never reports)                                         |
+| `single_tenant`         | Whether single-tenant mode is on                                                                      |
+| `setup_completed`       | Whether at least one platform account exists                                                          |
+| `os`                    | `process.platform` (e.g. `linux`)                                                                     |
+| `node_major`            | Major Node.js version number                                                                          |
+| `payment_count_7d`      | Bucket: `0`, `1-10`, `11-100`, `101-1000`, `1000+` (payment/charge BTs)                               |
+| `usdc_volume_7d`        | Payment/charge volume bucket: `0`, `lt_10`, `lt_100`, `lt_1k`, `lt_10k`, `lt_100k`, `lt_1m`, `gte_1m` |
+| `usdc_payout_volume_7d` | Payout volume bucket (same bands; absolute amount)                                                    |
+| `connected_accounts`    | Bucket: `0`, `1`, `2-10`, `11-100`, `100+`                                                            |
+
+## What is never sent
+
+Emails, business names, domains, API keys, wallet addresses, customer PII,
+exact dollar amounts, request bodies, logs, or IP addresses.

apps/api/src/main.ts

@@ -26,6 +26,10 @@ import {
 import { db } from './modules/Database';
 import { GetTopUpMonitor, TopUpMonitor } from './modules/TopUpMonitor';
 import { GetBillingMonitor, BillingMonitor } from './modules/BillingMonitor';
+import {
+  GetTelemetryMonitor,
+  TelemetryMonitor,
+} from './modules/TelemetryMonitor';
 import { AccountModule } from './modules/Account';
 import { ExternalWalletModule } from './modules/ExternalWallet';
 
@@ -207,6 +211,11 @@ async function StartServer() {
       );
     }
 
+    // Daily anonymous usage heartbeats (no-ops unless opted in)
+    if (TelemetryMonitor.ShouldStart()) {
+      GetTelemetryMonitor(db).Start();
+    }
+
     const server = app.listen(port, () => {
       console.log(`🚀 API running at http://localhost:${port}/v1`);
       console.log(`📊 Health check at http://localhost:${port}/api/health`);
@@ -241,6 +250,11 @@ async function StartServer() {
         billingMonitor.Stop();
       }
 
+      if (TelemetryMonitor.ShouldStart()) {
+        const telemetryMonitor = GetTelemetryMonitor(db);
+        telemetryMonitor.Stop();
+      }
+
       server.close(async () => {
         await mongoose.connection.close();
         console.log('Server closed');

apps/api/src/modules/Database.ts

@@ -449,6 +449,7 @@ export class Database {
       'TopUps',
       'Transfers',
       'UsageCounters',
+      'TelemetryConfigs',
       'WebhookEndpoints',
     ];
 

apps/api/src/modules/Setup.ts

@@ -16,8 +16,10 @@ import { ExternalWalletModule } from './ExternalWallet';
 import { SignToken } from '../utils/Token';
 import { SetupRequest, SetupResponse } from '@zoneless/shared-types';
 import { GetJwtSecret } from './AppConfig';
+import { GetTelemetryModule } from './Telemetry';
 import { AppError } from '../utils/AppError';
 import { ERRORS } from '../utils/Errors';
+import { Logger } from '../utils/Logger';
 
 /**
  * Validates a setup request body.
@@ -159,6 +161,17 @@ export class SetupModule {
       '7d'
     );
 
+    // Persist telemetry consent from setup (default off)
+    if (request.telemetry_enabled === true) {
+      try {
+        await GetTelemetryModule(this.db).SetEnabled(true);
+      } catch (err) {
+        Logger.warn('Failed to enable telemetry during setup', {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
     return {
       object: 'setup_response',
       success: true,