feat: add PostHog tracking for docs feedback

.gitignore

@@ -26,7 +26,7 @@ src/pages.gen.ts
 .env
 .vercel
 .vocs
-
+.env*.local
 src/pages/protocol/tips/tip-*
 
 # Playwright

package.json

@@ -25,6 +25,7 @@
     "monaco-editor": "^0.55.1",
     "ox": "^0.11.3",
     "posthog-js": "^1.333.0",
+    "posthog-node": "^5.24.8",
     "prool": "^0.2.2",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -44,14 +45,14 @@
   "devDependencies": {
     "@biomejs/biome": "^2.3.11",
     "@playwright/test": "^1.58.0",
-    "@types/node": "^25.0.10",
+    "@types/node": "^25.1.0",
     "@types/react": "^19.2.9",
     "@types/react-dom": "^19.2.3",
     "@typescript/native-preview": "7.0.0-dev.20260122.3",
     "@vitejs/plugin-react": "^5.1.2",
     "anser": "^2.3.5",
     "tsx": "^4.21.0",
-    "typescript": "~5.9.3",
+    "typescript": "^5.9.3",
     "use-sync-external-store": "^1.6.0",
     "vite": "^7.3.1"
   },

src/components/PostHogSetup.tsx

@@ -15,6 +15,12 @@ function PostHogInitializer() {
       defaults: '2025-05-24',
       capture_exceptions: true,
       debug: import.meta.env.MODE === 'development',
+      session_recording: {
+        maskAllInputs: false,
+        maskInputOptions: {
+          password: true,
+        },
+      },
       loaded: (posthog) => {
         posthog.capture('$pageview')
       },

src/lib/feedback-adapter.ts

@@ -0,0 +1,75 @@
+import { Feedback } from 'vocs/config'
+import { PostHog } from 'posthog-node'
+import { POSTHOG_EVENTS, POSTHOG_PROPERTIES } from './posthog'
+
+type FeedbackData = {
+  helpful: boolean
+  category?: string | undefined
+  message?: string | undefined
+  pageUrl: string
+  timestamp: string
+}
+
+/**
+ * Creates a combined feedback adapter that sends to both Slack and PostHog.
+ *
+ * PostHog events captured:
+ * - docs_feedback_submitted: All feedback submissions
+ * - docs_feedback_helpful: When user marks page as helpful
+ * - docs_feedback_not_helpful: When user marks page as not helpful
+ */
+export function createFeedbackAdapter() {
+  const slackAdapter = Feedback.slack()
+
+  const posthogKey = process.env['VITE_POSTHOG_KEY']
+  const posthogHost = process.env['VITE_POSTHOG_HOST'] || 'https://us.i.posthog.com'
+
+  const posthog = posthogKey
+    ? new PostHog(posthogKey, { host: posthogHost })
+    : null
+
+  return Feedback.from({
+    type: 'slack+posthog',
+    async submit(data: FeedbackData) {
+      const promises: Promise<void>[] = []
+
+      // Send to Slack
+      promises.push(slackAdapter.submit(data))
+
+      // Send to PostHog
+      if (posthog) {
+        const distinctId = `docs_feedback_${Date.now()}_${Math.random().toString(36).slice(2)}`
+
+        const commonProperties = {
+          [POSTHOG_PROPERTIES.FEEDBACK_HELPFUL]: data.helpful,
+          [POSTHOG_PROPERTIES.FEEDBACK_CATEGORY]: data.category,
+          [POSTHOG_PROPERTIES.FEEDBACK_MESSAGE]: data.message,
+          [POSTHOG_PROPERTIES.FEEDBACK_PAGE_URL]: data.pageUrl,
+          [POSTHOG_PROPERTIES.PAGE_PATH]: new URL(data.pageUrl).pathname,
+          [POSTHOG_PROPERTIES.SITE]: 'docs',
+          timestamp: data.timestamp,
+        }
+
+        // Capture main feedback event
+        posthog.capture({
+          distinctId,
+          event: POSTHOG_EVENTS.FEEDBACK_SUBMITTED,
+          properties: commonProperties,
+        })
+
+        // Capture sentiment-specific event for easier filtering
+        posthog.capture({
+          distinctId,
+          event: data.helpful
+            ? POSTHOG_EVENTS.FEEDBACK_HELPFUL
+            : POSTHOG_EVENTS.FEEDBACK_NOT_HELPFUL,
+          properties: commonProperties,
+        })
+
+        promises.push(posthog.flush().then(() => {}))
+      }
+
+      await Promise.all(promises)
+    },
+  })
+}

src/lib/posthog.ts

@@ -35,6 +35,11 @@ export const POSTHOG_EVENTS = {
   // Code interactions
   CODE_EXAMPLE_VIEW: 'docs_code_example_view',
   CODE_EXAMPLE_COPY: 'docs_code_example_copy',
+
+  // Feedback
+  FEEDBACK_SUBMITTED: 'docs_feedback_submitted',
+  FEEDBACK_HELPFUL: 'docs_feedback_helpful',
+  FEEDBACK_NOT_HELPFUL: 'docs_feedback_not_helpful',
 } as const
 
 /**
@@ -68,6 +73,12 @@ export const POSTHOG_PROPERTIES = {
   SEARCH_QUERY: 'search_query',
   SEARCH_RESULT_TITLE: 'search_result_title',
   SEARCH_RESULT_URL: 'search_result_url',
+
+  // Feedback properties
+  FEEDBACK_HELPFUL: 'feedback_helpful',
+  FEEDBACK_CATEGORY: 'feedback_category',
+  FEEDBACK_MESSAGE: 'feedback_message',
+  FEEDBACK_PAGE_URL: 'feedback_page_url',
 } as const
 
 /**

vocs.config.ts

@@ -1,4 +1,5 @@
-import { Changelog, defineConfig, Feedback, McpSource } from 'vocs/config'
+import { Changelog, defineConfig, McpSource } from 'vocs/config'
+import { createFeedbackAdapter } from './src/lib/feedback-adapter'
 
 const baseUrl = (() => {
   if (process.env.VERCEL_ENV === 'production')
@@ -14,7 +15,7 @@ export default defineConfig({
   title: 'Tempo',
   titleTemplate: '%s ⋅ Tempo',
   description: 'Documentation for the Tempo network and protocol specifications',
-  feedback: Feedback.slack(),
+  feedback: createFeedbackAdapter(),
   mcp: {
     enabled: true,
     sources: [