feat: add opt-in anonymous telemetry reporting

Add an opt-in telemetry system that sends anonymised instance
statistics to the public API once per day, which proxies them to
PostHog when `POSTHOG_API_KEY` is configured.

- Add `packages/core/src/telemetry.ts` — `performTelemetryReport`
  and `isTelemetryEnabled`; user and title counts are bucketed
  before sending to avoid exposing exact figures
- Add `getInstanceId()` to `settings.ts` — generates and persists a
  stable UUIDv7 for the instance
- Schedule a daily `telemetryReport` cron job (00:30)
- Add `POST /v1/telemetry` to `apps/public-api`; forwards payload
  to PostHog or returns 204 silently if key is absent
- Add `admin.telemetry` and `admin.toggleTelemetry` oRPC procedures
  for inspecting and toggling the setting
- Expose `instanceId` on `system.publicInfo`

packages/api/src/contract.ts

@@ -33,12 +33,14 @@ import {
   SearchOutput,
   SystemHealthOutput,
   SystemStatusOutput,
+  TelemetryOutput,
   TitleDetailOutput,
   TitleRecommendationsOutput,
   TitleResolveOutput,
   TmdbIdParam,
   TmdbIdTypeParam,
   ToggleRegistrationInput,
+  ToggleTelemetryInput,
   ToggleUpdateCheckInput,
   TrendingOutput,
   TrendingTypeParam,
@@ -367,6 +369,13 @@ export const contract = {
       .route({ method: "PUT", path: "/admin/update-check", tags: ["Admin"] })
       .input(ToggleUpdateCheckInput)
       .output(z.void()),
+    telemetry: oc
+      .route({ method: "GET", path: "/admin/telemetry", tags: ["Admin"] })
+      .output(TelemetryOutput),
+    toggleTelemetry: oc
+      .route({ method: "PUT", path: "/admin/telemetry", tags: ["Admin"] })
+      .input(ToggleTelemetryInput)
+      .output(z.void()),
     triggerJob: oc
       .route({
         method: "POST",

packages/api/src/schemas.ts

@@ -70,6 +70,11 @@ export const CreateIntegrationInput = z.object({
 
 export const ToggleRegistrationInput = z.object({ open: z.boolean() });
 export const ToggleUpdateCheckInput = z.object({ enabled: z.boolean() });
+export const ToggleTelemetryInput = z.object({ enabled: z.boolean() });
+export const TelemetryOutput = z.object({
+  enabled: z.boolean(),
+  lastReportedAt: z.string().nullable(),
+});
 
 const cronJobName = z.enum([
   "scheduledBackup",
@@ -80,6 +85,7 @@ const cronJobName = z.enum([
   "cacheImages",
   "refreshCredits",
   "updateCheck",
+  "telemetryReport",
 ]);
 
 export const TriggerJobInput = z.object({ name: cronJobName });
@@ -555,6 +561,7 @@ export const QuickAddOutput = z.object({
 // ─── System outputs ───────────────────────────────────────────
 
 export const PublicInfoOutput = z.object({
+  instanceId: z.string(),
   tmdbConfigured: z.boolean(),
   userCount: z.number(),
   registrationOpen: z.boolean(),

packages/core/package.json

@@ -16,6 +16,7 @@
     "./providers": "./src/providers.ts",
     "./settings": "./src/settings.ts",
     "./system-health": "./src/system-health.ts",
+    "./telemetry": "./src/telemetry.ts",
     "./tracking": "./src/tracking.ts",
     "./update-check": "./src/update-check.ts",
     "./webhooks": "./src/webhooks.ts"

packages/core/src/settings.ts

@@ -23,6 +23,14 @@ export function getUserCount(): number {
   return result?.count ?? 0;
 }
 
+export function getInstanceId(): string {
+  const existing = getSetting("instanceId");
+  if (existing) return existing;
+  const id = Bun.randomUUIDv7();
+  setSetting("instanceId", id);
+  return id;
+}
+
 export function isRegistrationOpen(): boolean {
   const userCount = getUserCount();
   if (userCount === 0) return true;

packages/core/src/telemetry.ts

@@ -0,0 +1,95 @@
+import { db } from "@sofa/db/client";
+import { count } from "@sofa/db/helpers";
+import { titles } from "@sofa/db/schema";
+import { createLogger } from "@sofa/logger";
+import { imageCacheEnabled } from "./image-cache";
+import {
+  getInstanceId,
+  getSetting,
+  getUserCount,
+  setSetting,
+} from "./settings";
+
+const APP_VERSION = process.env.APP_VERSION || "0.0.0";
+const PUBLIC_API_URL =
+  process.env.PUBLIC_API_URL || "https://public-api.sofa.watch";
+const REPORT_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+const log = createLogger("telemetry");
+
+export function isTelemetryEnabled(): boolean {
+  return getSetting("telemetryEnabled") === "true";
+}
+
+function bucketUsers(n: number): string {
+  if (n <= 1) return "1";
+  if (n <= 5) return "2-5";
+  if (n <= 10) return "6-10";
+  if (n <= 25) return "11-25";
+  return "26+";
+}
+
+function bucketTitles(n: number): string {
+  if (n === 0) return "0";
+  if (n <= 50) return "1-50";
+  if (n <= 200) return "51-200";
+  if (n <= 500) return "201-500";
+  return "501+";
+}
+
+function getTitleCount(): number {
+  const result = db.select({ count: count() }).from(titles).get();
+  return result?.count ?? 0;
+}
+
+export async function performTelemetryReport(): Promise<void> {
+  if (!isTelemetryEnabled()) {
+    log.debug("Telemetry disabled, skipping");
+    return;
+  }
+
+  // Respect report interval
+  const lastReported = getSetting("telemetryLastReportedAt");
+  if (lastReported) {
+    const elapsed = Date.now() - new Date(lastReported).getTime();
+    if (elapsed < REPORT_INTERVAL_MS) {
+      return;
+    }
+  }
+
+  try {
+    const body = {
+      instanceId: getInstanceId(),
+      version: APP_VERSION,
+      arch: `${process.platform}-${process.arch}`,
+      users: bucketUsers(getUserCount()),
+      titles: bucketTitles(getTitleCount()),
+      features: {
+        imageCache: imageCacheEnabled(),
+        oidc: !!(
+          process.env.OIDC_CLIENT_ID &&
+          process.env.OIDC_CLIENT_SECRET &&
+          process.env.OIDC_ISSUER_URL
+        ),
+        scheduledBackups: getSetting("scheduledBackups") === "true",
+      },
+    };
+
+    const res = await fetch(`${PUBLIC_API_URL}/v1/telemetry`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "User-Agent": "sofa-telemetry",
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(10_000),
+    });
+
+    if (!res.ok) throw new Error(`Public API ${res.status}`);
+
+    setSetting("telemetryLastReportedAt", new Date().toISOString());
+    log.info("Telemetry report sent");
+  } catch (err) {
+    log.warn("Telemetry report failed:", err);
+  }
+}