@codaijs/keel 0.1.0

package/sails/analytics/README.md

@@ -0,0 +1,178 @@
+# PostHog Analytics Sail
+
+Adds privacy-friendly analytics to your keel application using PostHog. Supports automatic page view tracking, user identification, custom events, and more.
+
+## Features
+
+- Automatic page view tracking on SPA route changes
+- User identification tied to BetterAuth sessions
+- Custom event tracking API
+- Session recording and heatmaps (configurable in PostHog)
+- Feature flags support
+- Works with PostHog Cloud or self-hosted instances
+- GDPR-compatible (supports cookie-less tracking and consent)
+- No backend dependencies — everything runs client-side
+
+## Prerequisites
+
+- A PostHog account (cloud or self-hosted)
+  - Cloud: https://app.posthog.com (US) or https://eu.posthog.com (EU)
+  - Self-hosted: https://posthog.com/docs/self-host
+
+## Installation
+
+```bash
+npx tsx sails/analytics/install.ts
+```
+
+The installer will ask whether you are using PostHog Cloud or self-hosted and collect your API key.
+
+## Manual Setup
+
+### 1. Get Your API Key
+
+#### PostHog Cloud
+1. Sign up at https://app.posthog.com
+2. Create a project
+3. Go to **Project Settings**
+4. Copy the **Project API Key** (starts with `phc_`)
+
+#### Self-Hosted
+1. Log into your PostHog instance
+2. Go to **Project Settings**
+3. Copy the **Project API Key**
+
+### 2. Environment Variables
+
+```env
+VITE_POSTHOG_KEY=phc_your_project_api_key
+VITE_POSTHOG_HOST=https://us.i.posthog.com
+```
+
+For EU cloud, use `https://eu.i.posthog.com`. For self-hosted, use your instance URL.
+
+## Architecture
+
+### Analytics Service (`src/lib/analytics.ts`)
+
+Singleton service that wraps the PostHog SDK:
+
+```typescript
+import analytics from "@/lib/analytics";
+
+// Initialize (done automatically by AnalyticsProvider)
+analytics.init();
+
+// Identify user after login
+analytics.identify("user-123", { email: "user@example.com", plan: "pro" });
+
+// Track custom event
+analytics.trackEvent("feature_used", { feature: "dark-mode" });
+
+// Track page view (done automatically on route changes)
+analytics.trackPageView();
+
+// Reset on logout
+analytics.reset();
+```
+
+When `VITE_POSTHOG_KEY` is not set (local development), all calls become no-ops.
+
+### AnalyticsProvider Component
+
+Wraps your app and handles:
+- PostHog initialization on mount
+- User identification when logged in
+- Identity reset on logout
+- Page view tracking on route changes
+
+```tsx
+// In App.tsx (added automatically by installer)
+import { AnalyticsProvider } from "./components/AnalyticsProvider";
+
+export default function App() {
+  return (
+    <AnalyticsProvider>
+      <AppRouter />
+    </AnalyticsProvider>
+  );
+}
+```
+
+### useAnalytics Hook
+
+For tracking events in components:
+
+```tsx
+import { useAnalytics } from "@/hooks/useAnalytics";
+
+function PricingPage() {
+  const { trackEvent } = useAnalytics();
+
+  const handlePlanSelect = (plan: string) => {
+    trackEvent("plan_selected", { plan });
+  };
+
+  return (
+    <button onClick={() => handlePlanSelect("pro")}>
+      Select Pro Plan
+    </button>
+  );
+}
+```
+
+The hook also auto-handles user identification and page views, so you can use it in any component that needs event tracking.
+
+## Common Events to Track
+
+| Event | When | Properties |
+|-------|------|------------|
+| `signup_completed` | After successful signup | `{ method: "email" }` |
+| `plan_selected` | User clicks a pricing plan | `{ plan: "pro" }` |
+| `feature_used` | User interacts with a feature | `{ feature: "export" }` |
+| `error_occurred` | An error happens | `{ page: "/settings", type: "validation" }` |
+| `onboarding_step` | User progresses in onboarding | `{ step: 3, total: 5 }` |
+
+## PostHog Features
+
+### Session Recording
+
+Enable in PostHog > Project Settings > Session Recording. Records user sessions as videos for debugging and UX research.
+
+### Feature Flags
+
+```typescript
+import { getPostHog } from "@/lib/analytics";
+
+const posthog = getPostHog();
+if (posthog?.isFeatureEnabled("new-dashboard")) {
+  // Show new dashboard
+}
+```
+
+### Surveys
+
+Create in-app surveys directly from the PostHog dashboard. They appear automatically when conditions are met.
+
+## GDPR Compliance
+
+PostHog offers several privacy-friendly options:
+
+1. **Cookie-less tracking**: PostHog can work without cookies using localStorage
+2. **Consent management**: Disable autocapture until consent is given:
+   ```typescript
+   // In analytics.ts, change persistence to "memory" and disable autocapture
+   // Then enable after consent:
+   posthog.opt_in_capturing();
+   ```
+3. **EU hosting**: Use `https://eu.i.posthog.com` for EU data residency
+4. **Self-hosting**: Full data control with a self-hosted instance
+
+If you have the GDPR sail installed, consider integrating analytics initialization with the consent tracking system.
+
+## Disabling in Development
+
+Analytics is automatically disabled when `VITE_POSTHOG_KEY` is not set. In local development, you can either:
+
+- Leave `VITE_POSTHOG_KEY` empty in your `.env` (analytics disabled)
+- Set it to your dev/staging PostHog project key (analytics enabled)

package/sails/analytics/addon.json

@@ -0,0 +1,27 @@
+{
+  "name": "analytics",
+  "displayName": "PostHog Analytics",
+  "description": "Privacy-friendly analytics with PostHog — auto page views, user identification, and custom event tracking",
+  "version": "1.0.0",
+  "compatibility": ">=1.0.0",
+  "requiredEnvVars": [
+    { "key": "VITE_POSTHOG_KEY", "description": "PostHog project API key" },
+    { "key": "VITE_POSTHOG_HOST", "description": "PostHog instance URL (e.g., https://us.i.posthog.com)" }
+  ],
+  "dependencies": {
+    "backend": {},
+    "frontend": { "posthog-js": "^1.200.0" }
+  },
+  "modifies": {
+    "backend": [],
+    "frontend": ["src/App.tsx"]
+  },
+  "adds": {
+    "backend": [],
+    "frontend": [
+      "src/lib/analytics.ts",
+      "src/hooks/useAnalytics.ts",
+      "src/components/AnalyticsProvider.tsx"
+    ]
+  }
+}

package/sails/analytics/files/frontend/components/AnalyticsProvider.tsx

@@ -0,0 +1,58 @@
+import { useEffect, type ReactNode } from "react";
+import { useLocation } from "react-router";
+import { useAuth } from "@/hooks/useAuth.js";
+import {
+  initAnalytics,
+  identify,
+  reset,
+  trackPageView,
+} from "@/lib/analytics.js";
+
+interface AnalyticsProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Provider component that initializes PostHog analytics and handles
+ * automatic user identification and page view tracking.
+ *
+ * Wrap your app (or router) with this component:
+ *
+ *   <AnalyticsProvider>
+ *     <AppRouter />
+ *   </AnalyticsProvider>
+ *
+ * Behavior:
+ *   - Initializes PostHog on mount
+ *   - Identifies the user when they are logged in
+ *   - Resets identity on logout
+ *   - Tracks page views on every route change
+ */
+export function AnalyticsProvider({ children }: AnalyticsProviderProps) {
+  const { user, isAuthenticated } = useAuth();
+  const location = useLocation();
+
+  // Initialize PostHog on mount
+  useEffect(() => {
+    initAnalytics();
+  }, []);
+
+  // Identify or reset user when auth state changes
+  useEffect(() => {
+    if (isAuthenticated && user) {
+      identify(user.id, {
+        email: user.email,
+        name: user.name,
+      });
+    } else {
+      reset();
+    }
+  }, [isAuthenticated, user]);
+
+  // Track page views on route changes
+  useEffect(() => {
+    trackPageView();
+  }, [location.pathname]);
+
+  return <>{children}</>;
+}

package/sails/analytics/files/frontend/hooks/useAnalytics.ts

@@ -0,0 +1,64 @@
+import { useEffect, useCallback } from "react";
+import { useLocation } from "react-router";
+import { useAuth } from "@/hooks/useAuth.js";
+import { identify, reset, trackEvent, trackPageView } from "@/lib/analytics.js";
+
+interface UseAnalyticsResult {
+  trackEvent: (name: string, properties?: Record<string, string | number | boolean>) => void;
+  identify: (userId: string, traits?: Record<string, string | number | boolean>) => void;
+  reset: () => void;
+}
+
+/**
+ * React hook that integrates PostHog analytics with auth state and routing.
+ *
+ * - Auto-identifies the user when they log in (using useAuth)
+ * - Auto-resets identity when the user logs out
+ * - Auto-tracks page views on every route change (using useLocation)
+ * - Returns functions for manual event tracking
+ */
+export function useAnalytics(): UseAnalyticsResult {
+  const { user, isAuthenticated } = useAuth();
+  const location = useLocation();
+
+  // Auto-identify / reset when auth state changes
+  useEffect(() => {
+    if (isAuthenticated && user) {
+      identify(user.id, {
+        email: user.email,
+        name: user.name,
+      });
+    } else {
+      reset();
+    }
+  }, [isAuthenticated, user]);
+
+  // Auto-track page views on route changes
+  useEffect(() => {
+    trackPageView();
+  }, [location.pathname]);
+
+  const track = useCallback(
+    (name: string, properties?: Record<string, string | number | boolean>) => {
+      trackEvent(name, properties);
+    },
+    [],
+  );
+
+  const identifyUser = useCallback(
+    (userId: string, traits?: Record<string, string | number | boolean>) => {
+      identify(userId, traits);
+    },
+    [],
+  );
+
+  const resetIdentity = useCallback(() => {
+    reset();
+  }, []);
+
+  return {
+    trackEvent: track,
+    identify: identifyUser,
+    reset: resetIdentity,
+  };
+}

package/sails/analytics/files/frontend/lib/analytics.ts

@@ -0,0 +1,103 @@
+import posthog from "posthog-js";
+
+// ---------------------------------------------------------------------------
+// PostHog Analytics Service
+// ---------------------------------------------------------------------------
+
+const POSTHOG_KEY = import.meta.env.VITE_POSTHOG_KEY as string | undefined;
+const POSTHOG_HOST = import.meta.env.VITE_POSTHOG_HOST as string | undefined;
+
+/** Whether PostHog is configured and initialized. */
+let isInitialized = false;
+
+/**
+ * Initialize PostHog analytics.
+ *
+ * If VITE_POSTHOG_KEY is not set (common in local dev), all calls become
+ * no-ops so analytics never interfere with development.
+ */
+export function initAnalytics(): void {
+  if (isInitialized) return;
+
+  if (!POSTHOG_KEY) {
+    if (import.meta.env.DEV) {
+      console.log("[analytics] VITE_POSTHOG_KEY not set — analytics disabled in dev");
+    }
+    return;
+  }
+
+  posthog.init(POSTHOG_KEY, {
+    api_host: POSTHOG_HOST || "https://us.i.posthog.com",
+    autocapture: true,
+    capture_pageview: false, // We handle page views manually for SPA routing
+    capture_pageleave: true,
+    persistence: "localStorage",
+    person_profiles: "identified_only",
+  });
+
+  isInitialized = true;
+}
+
+/**
+ * Identify a user after login. Associates all future events with this user.
+ *
+ * @param userId - The user's unique ID
+ * @param traits - Optional user properties (email, name, plan, etc.)
+ */
+export function identify(
+  userId: string,
+  traits?: Record<string, string | number | boolean>,
+): void {
+  if (!isInitialized) return;
+  posthog.identify(userId, traits);
+}
+
+/**
+ * Reset analytics identity after logout.
+ * Creates a new anonymous ID for subsequent events.
+ */
+export function reset(): void {
+  if (!isInitialized) return;
+  posthog.reset();
+}
+
+/**
+ * Track a custom event.
+ *
+ * @param name - Event name (e.g., "subscription_started", "feature_used")
+ * @param properties - Optional event properties
+ */
+export function trackEvent(
+  name: string,
+  properties?: Record<string, string | number | boolean>,
+): void {
+  if (!isInitialized) return;
+  posthog.capture(name, properties);
+}
+
+/**
+ * Track a page view. Call this on every route change in an SPA.
+ */
+export function trackPageView(): void {
+  if (!isInitialized) return;
+  posthog.capture("$pageview");
+}
+
+/**
+ * Get the PostHog instance for advanced usage.
+ * Returns null if not initialized.
+ */
+export function getPostHog(): typeof posthog | null {
+  return isInitialized ? posthog : null;
+}
+
+export const analytics = {
+  init: initAnalytics,
+  identify,
+  reset,
+  trackEvent,
+  trackPageView,
+  getPostHog,
+};
+
+export default analytics;