kanna-code 0.33.8 → 0.34.0

package/src/server/analytics.test.ts

@@ -0,0 +1,305 @@
+import { describe, expect, test } from "bun:test"
+import { KannaAnalyticsReporter, getLaunchAnalyticsProperties } from "./analytics"
+
+const originalLogAnalytics = process.env.KANNA_LOG_ANALYTICS
+
+function restoreAnalyticsLoggingEnv() {
+  if (originalLogAnalytics === undefined) {
+    delete process.env.KANNA_LOG_ANALYTICS
+    return
+  }
+  process.env.KANNA_LOG_ANALYTICS = originalLogAnalytics
+}
+
+describe("getLaunchAnalyticsProperties", () => {
+  test("expands launch flags into app_launch properties", () => {
+    expect(getLaunchAnalyticsProperties({
+      port: 4000,
+      host: "0.0.0.0",
+      openBrowser: false,
+      share: "quick",
+      password: "secret",
+      strictPort: true,
+    })).toEqual({
+      custom_port_enabled: true,
+      no_open_enabled: true,
+      password_enabled: true,
+      strict_port_enabled: true,
+      remote_enabled: true,
+      host_enabled: false,
+      share_quick_enabled: true,
+      share_token_enabled: false,
+    })
+  })
+})
+
+describe("KannaAnalyticsReporter", () => {
+  test("posts the userId, event name, and shared properties", async () => {
+    const originalLog = console.log
+    const calls: Array<{ url: string; init?: RequestInit }> = []
+    console.log = () => {}
+
+    try {
+      const reporter = new KannaAnalyticsReporter({
+        endpoint: "https://kanna.sh/api/t",
+        currentVersion: "0.33.9",
+        environment: "dev",
+        settings: {
+          getState: () => ({
+            analyticsEnabled: true,
+            analyticsUserId: "anon_123",
+            warning: null,
+            filePathDisplay: "~/.kanna/data/settings.json",
+          }),
+        },
+        fetchImpl: async (url, init) => {
+          calls.push({ url: String(url), init })
+          return new Response(JSON.stringify({ ok: true }), { status: 200 })
+        },
+      })
+
+      reporter.track("message_sent")
+      await (reporter as any).queue
+
+      expect(calls).toHaveLength(1)
+      expect(calls[0]?.url).toBe("https://kanna.sh/api/t")
+      expect(calls[0]?.init?.method).toBe("POST")
+      expect(calls[0]?.init?.headers).toEqual({
+        "content-type": "application/json",
+      })
+      expect(JSON.parse(String(calls[0]?.init?.body))).toEqual({
+        userId: "anon_123",
+        environment: "dev",
+        event: {
+          name: "message_sent",
+          properties: {
+            current_version: "0.33.9",
+            environment: "dev",
+          },
+        },
+      })
+    } finally {
+      console.log = originalLog
+    }
+  })
+
+  test("posts app_launch with launch flags as properties", async () => {
+    const calls: Array<{ url: string; init?: RequestInit }> = []
+    const reporter = new KannaAnalyticsReporter({
+      endpoint: "https://kanna.sh/api/t",
+      currentVersion: "0.33.9",
+      environment: "prod",
+      settings: {
+        getState: () => ({
+          analyticsEnabled: true,
+          analyticsUserId: "anon_123",
+          warning: null,
+          filePathDisplay: "~/.kanna/data/settings.json",
+        }),
+      },
+      fetchImpl: async (url, init) => {
+        calls.push({ url: String(url), init })
+        return new Response(JSON.stringify({ ok: true }), { status: 200 })
+      },
+    })
+
+    reporter.trackLaunch({
+      port: 4000,
+      host: "localhost",
+      openBrowser: false,
+      share: false,
+      password: null,
+      strictPort: true,
+    })
+    await (reporter as any).queue
+
+    expect(JSON.parse(String(calls[0]?.init?.body))).toEqual({
+      userId: "anon_123",
+      environment: "prod",
+      event: {
+        name: "app_launch",
+        properties: {
+          current_version: "0.33.9",
+          environment: "prod",
+          custom_port_enabled: true,
+          no_open_enabled: true,
+          password_enabled: false,
+          strict_port_enabled: true,
+          remote_enabled: false,
+          host_enabled: false,
+          share_quick_enabled: false,
+          share_token_enabled: false,
+        },
+      },
+    })
+  })
+
+  test("skips requests when analytics is disabled", async () => {
+    let called = false
+    const reporter = new KannaAnalyticsReporter({
+      currentVersion: "0.33.9",
+      environment: "prod",
+      settings: {
+        getState: () => ({
+          analyticsEnabled: false,
+          analyticsUserId: "anon_123",
+          warning: null,
+          filePathDisplay: "~/.kanna/data/settings.json",
+        }),
+      },
+      fetchImpl: async () => {
+        called = true
+        return new Response(null, { status: 200 })
+      },
+    })
+
+    reporter.track("message_sent")
+    await (reporter as any).queue
+
+    expect(called).toBe(false)
+  })
+
+  test("does not warn when analytics request logging is disabled and the request fails", async () => {
+    const originalWarn = console.warn
+    const warnings: unknown[][] = []
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args)
+    }
+    delete process.env.KANNA_LOG_ANALYTICS
+
+    try {
+      const reporter = new KannaAnalyticsReporter({
+        endpoint: "https://kanna.sh/api/t",
+        currentVersion: "0.33.9",
+        environment: "dev",
+        settings: {
+          getState: () => ({
+            analyticsEnabled: true,
+            analyticsUserId: "anon_123",
+            warning: null,
+            filePathDisplay: "~/.kanna/data/settings.json",
+          }),
+        },
+        fetchImpl: async () => new Response(JSON.stringify({ error: "bad request" }), { status: 400 }),
+      })
+
+      reporter.track("message_sent")
+      await (reporter as any).queue
+
+      expect(warnings).toHaveLength(0)
+    } finally {
+      console.warn = originalWarn
+      restoreAnalyticsLoggingEnv()
+    }
+  })
+
+  test("warns when analytics request logging is enabled and the request fails", async () => {
+    const originalWarn = console.warn
+    const warnings: unknown[][] = []
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args)
+    }
+    process.env.KANNA_LOG_ANALYTICS = "1"
+
+    try {
+      const reporter = new KannaAnalyticsReporter({
+        endpoint: "https://kanna.sh/api/t",
+        currentVersion: "0.33.9",
+        environment: "prod",
+        settings: {
+          getState: () => ({
+            analyticsEnabled: true,
+            analyticsUserId: "anon_123",
+            warning: null,
+            filePathDisplay: "~/.kanna/data/settings.json",
+          }),
+        },
+        fetchImpl: async () => new Response(JSON.stringify({ error: "bad request" }), { status: 400 }),
+      })
+
+      reporter.track("message_sent")
+      await (reporter as any).queue
+
+      expect(warnings).toHaveLength(1)
+      expect(warnings[0]?.[0]).toBe("[kanna/analytics] Failed to send analytics event:")
+      expect(warnings[0]?.[1]).toBe("message_sent")
+      expect(warnings[0]?.[2]).toBeInstanceOf(Error)
+    } finally {
+      console.warn = originalWarn
+      restoreAnalyticsLoggingEnv()
+    }
+  })
+
+  test("logs when analytics request logging is enabled and the request succeeds", async () => {
+    const originalLog = console.log
+    const logs: unknown[][] = []
+    console.log = (...args: unknown[]) => {
+      logs.push(args)
+    }
+    process.env.KANNA_LOG_ANALYTICS = "1"
+
+    try {
+      const reporter = new KannaAnalyticsReporter({
+        endpoint: "https://kanna.sh/api/t",
+        currentVersion: "0.33.9",
+        environment: "dev",
+        settings: {
+          getState: () => ({
+            analyticsEnabled: true,
+            analyticsUserId: "anon_123",
+            warning: null,
+            filePathDisplay: "~/.kanna/data/settings.json",
+          }),
+        },
+        fetchImpl: async () => new Response(JSON.stringify({ ok: true }), { status: 200 }),
+      })
+
+      reporter.track("message_sent")
+      await (reporter as any).queue
+
+      expect(logs).toHaveLength(1)
+      expect(logs[0]).toEqual([
+        "[kanna/analytics] Sent analytics event:",
+        "message_sent",
+        200,
+      ])
+    } finally {
+      console.log = originalLog
+      restoreAnalyticsLoggingEnv()
+    }
+  })
+
+  test("does not log when analytics request logging is disabled and the request succeeds", async () => {
+    const originalLog = console.log
+    const logs: unknown[][] = []
+    console.log = (...args: unknown[]) => {
+      logs.push(args)
+    }
+    delete process.env.KANNA_LOG_ANALYTICS
+
+    try {
+      const reporter = new KannaAnalyticsReporter({
+        endpoint: "https://kanna.sh/api/t",
+        currentVersion: "0.33.9",
+        environment: "prod",
+        settings: {
+          getState: () => ({
+            analyticsEnabled: true,
+            analyticsUserId: "anon_123",
+            warning: null,
+            filePathDisplay: "~/.kanna/data/settings.json",
+          }),
+        },
+        fetchImpl: async () => new Response(JSON.stringify({ ok: true }), { status: 200 }),
+      })
+
+      reporter.track("message_sent")
+      await (reporter as any).queue
+
+      expect(logs).toHaveLength(0)
+    } finally {
+      console.log = originalLog
+      restoreAnalyticsLoggingEnv()
+    }
+  })
+})

package/src/server/analytics.ts

@@ -0,0 +1,126 @@
+import { ANALYTICS_ENDPOINT } from "../shared/analytics"
+import { PROD_SERVER_PORT } from "../shared/ports"
+import type { ShareMode } from "../shared/share"
+import { isTokenShareMode } from "../shared/share"
+import type { AppSettingsManager } from "./app-settings"
+
+interface AnalyticsRequestBody {
+  userId: string
+  environment: AnalyticsEnvironment
+  event: {
+    name: string
+    properties: Record<string, unknown>
+  }
+}
+
+export interface LaunchAnalyticsOptions {
+  port: number
+  host: string
+  openBrowser: boolean
+  share: ShareMode
+  password: string | null
+  strictPort: boolean
+}
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>
+type AnalyticsEnvironment = "dev" | "prod"
+
+function isAnalyticsLoggingEnabled() {
+  return process.env.KANNA_LOG_ANALYTICS === "1"
+}
+
+export interface AnalyticsReporter {
+  track: (eventName: string, properties?: Record<string, unknown>) => void
+  trackLaunch: (options: LaunchAnalyticsOptions) => void
+}
+
+export class KannaAnalyticsReporter implements AnalyticsReporter {
+  private readonly settings: Pick<AppSettingsManager, "getState">
+  private readonly endpoint: string
+  private readonly fetchImpl: FetchLike
+  private readonly currentVersion: string
+  private readonly environment: AnalyticsEnvironment
+  private queue = Promise.resolve()
+
+  constructor(args: {
+    settings: Pick<AppSettingsManager, "getState">
+    currentVersion: string
+    environment: AnalyticsEnvironment
+    endpoint?: string
+    fetchImpl?: FetchLike
+  }) {
+    this.settings = args.settings
+    this.currentVersion = args.currentVersion
+    this.environment = args.environment
+    this.endpoint = args.endpoint ?? ANALYTICS_ENDPOINT
+    this.fetchImpl = args.fetchImpl ?? fetch
+  }
+
+  track(eventName: string, properties?: Record<string, unknown>) {
+    const { analyticsEnabled, analyticsUserId } = this.settings.getState()
+    if (!analyticsEnabled || !analyticsUserId) {
+      return
+    }
+
+    const body: AnalyticsRequestBody = {
+      userId: analyticsUserId,
+      environment: this.environment,
+      event: {
+        name: eventName,
+        properties: this.buildEventProperties(properties),
+      },
+    }
+
+    this.queue = this.queue
+      .then(async () => {
+        const response = await this.fetchImpl(this.endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+          },
+          body: JSON.stringify(body),
+        })
+        if (!response.ok) {
+          throw new Error(`Analytics request failed with status ${response.status}`)
+        }
+        if (isAnalyticsLoggingEnabled()) {
+          console.log("[kanna/analytics] Sent analytics event:", eventName, response.status)
+        }
+      })
+      .catch((error) => {
+        if (isAnalyticsLoggingEnabled()) {
+          console.warn("[kanna/analytics] Failed to send analytics event:", eventName, error)
+        }
+      })
+  }
+
+  trackLaunch(options: LaunchAnalyticsOptions) {
+    this.track("app_launch", getLaunchAnalyticsProperties(options))
+  }
+
+  private buildEventProperties(properties?: Record<string, unknown>) {
+    return {
+      current_version: this.currentVersion,
+      environment: this.environment,
+      ...(properties ?? {}),
+    }
+  }
+}
+
+export function getLaunchAnalyticsProperties(options: LaunchAnalyticsOptions) {
+  return {
+    custom_port_enabled: options.port !== PROD_SERVER_PORT,
+    no_open_enabled: !options.openBrowser,
+    password_enabled: Boolean(options.password),
+    strict_port_enabled: options.strictPort,
+    remote_enabled: options.host === "0.0.0.0",
+    host_enabled: options.host !== "0.0.0.0" && options.host !== "127.0.0.1" && options.host !== "localhost",
+    share_quick_enabled: options.share === "quick",
+    share_token_enabled: isTokenShareMode(options.share),
+  }
+}
+
+export const NoopAnalyticsReporter: AnalyticsReporter = {
+  track: () => {},
+  trackLaunch: () => {},
+}

package/src/server/app-settings.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, test } from "bun:test"
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { AppSettingsManager, readAppSettingsSnapshot } from "./app-settings"
+
+let tempDirs: string[] = []
+
+afterEach(async () => {
+  await Promise.all(tempDirs.map((dir) => rm(dir, { recursive: true, force: true })))
+  tempDirs = []
+})
+
+async function createTempFilePath() {
+  const dir = await mkdtemp(path.join(tmpdir(), "kanna-settings-"))
+  tempDirs.push(dir)
+  return path.join(dir, "settings.json")
+}
+
+describe("readAppSettingsSnapshot", () => {
+  test("returns defaults when the file does not exist", async () => {
+    const filePath = await createTempFilePath()
+    const snapshot = await readAppSettingsSnapshot(filePath)
+
+    expect(snapshot).toEqual({
+      analyticsEnabled: true,
+      warning: null,
+      filePathDisplay: filePath,
+    })
+  })
+
+  test("returns a warning when the file contains invalid json", async () => {
+    const filePath = await createTempFilePath()
+    await writeFile(filePath, "{not-json", "utf8")
+
+    const snapshot = await readAppSettingsSnapshot(filePath)
+    expect(snapshot.analyticsEnabled).toBe(true)
+    expect(snapshot.warning).toContain("invalid JSON")
+  })
+})
+
+describe("AppSettingsManager", () => {
+  test("creates a settings file with analytics enabled and a stable anonymous id", async () => {
+    const filePath = await createTempFilePath()
+    const manager = new AppSettingsManager(filePath)
+
+    await manager.initialize()
+
+    const payload = JSON.parse(await readFile(filePath, "utf8")) as {
+      analyticsEnabled: boolean
+      analyticsUserId: string
+    }
+    expect(payload.analyticsEnabled).toBe(true)
+    expect(payload.analyticsUserId).toMatch(/^anon_/)
+    expect(manager.getSnapshot()).toEqual({
+      analyticsEnabled: true,
+      warning: null,
+      filePathDisplay: filePath,
+    })
+
+    manager.dispose()
+  })
+
+  test("writes analyticsEnabled without replacing the stored user id", async () => {
+    const filePath = await createTempFilePath()
+    const manager = new AppSettingsManager(filePath)
+
+    await manager.initialize()
+    const initialPayload = JSON.parse(await readFile(filePath, "utf8")) as {
+      analyticsEnabled: boolean
+      analyticsUserId: string
+    }
+
+    const snapshot = await manager.write({ analyticsEnabled: false })
+    const nextPayload = JSON.parse(await readFile(filePath, "utf8")) as {
+      analyticsEnabled: boolean
+      analyticsUserId: string
+    }
+
+    expect(snapshot).toEqual({
+      analyticsEnabled: false,
+      warning: null,
+      filePathDisplay: filePath,
+    })
+    expect(nextPayload.analyticsEnabled).toBe(false)
+    expect(nextPayload.analyticsUserId).toBe(initialPayload.analyticsUserId)
+
+    manager.dispose()
+  })
+})