@od-oneapp/analytics 2026.1.1301

package/README.md

@@ -0,0 +1,509 @@
+# @repo/analytics
+
+> **Multi-provider analytics package with type-safe event tracking, comprehensive ecommerce support, and AI product
+> analytics**
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
+
+## Quick Reference
+
+**Status:** Development (Tests passing: 634/655, TypeCheck: ✅)
+
+**Requirements:**
+
+- Node.js 22.0.0+ (uses Node 22+ features: `structuredClone`, `AbortSignal.timeout`, bigint timing)
+- pnpm 10.0.0+
+- Next.js 15.0.0+ (if using Next.js integration)
+
+**Exports:**
+
+- **Core**: `./client`, `./server`, `./shared`, `./types`
+- **Next.js**: `./client/next`, `./server/next`, `./server/edge`
+
+**Key Features:**
+
+- ✅ Multi-Provider (PostHog, Vercel Analytics, Segment, Console)
+- ✅ Type-Safe Emitters (Segment.io specification)
+- ✅ Universal (client/server/edge environments)
+- ✅ E-commerce (50+ standardized events)
+- ✅ AI Product Tracking (90+ ChatGPT/Claude-style events)
+- ✅ Feature Flags (PostHog integration)
+- ✅ Next.js 15 (App Router, Server Components, hooks)
+
+---
+
+## Installation
+
+### Prerequisites
+
+⚠️ **Required:** Node.js 22+ (package uses `structuredClone`, `AbortSignal.timeout`, `process.hrtime.bigint`)
+
+```bash
+# Check Node version
+node --version # Must be v22.0.0 or higher
+
+# Install package
+pnpm add @repo/analytics --filter=your-app
+```
+
+### Install Providers (Peer Dependencies)
+
+Install only the providers you need:
+
+```bash
+# PostHog (recommended - analytics + feature flags)
+pnpm add posthog-js posthog-node --filter=your-app
+
+# Vercel Analytics
+pnpm add @vercel/analytics --filter=your-app
+
+# Segment
+pnpm add @segment/analytics-next --filter=your-app
+
+# Console (built-in, no installation needed)
+```
+
+---
+
+## Quick Start
+
+### Environment Variables
+
+```bash
+# .env.local
+
+# PostHog (Primary)
+NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com
+
+# Vercel Analytics (Optional)
+VERCEL_ANALYTICS_ID=your-analytics-id
+
+# Segment (Optional)
+NEXT_PUBLIC_SEGMENT_WRITE_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# Development
+NEXT_PUBLIC_CONSOLE_ANALYTICS=true
+```
+
+### Next.js Setup
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import { AnalyticsProvider } from "@repo/analytics/client/next";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <AnalyticsProvider
+      config={{
+        providers: {
+          posthog: {
+            apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY!,
+            options: {
+              debug: process.env.NODE_ENV === "development",
+              capture_pageview: false
+            }
+          },
+          console: {
+            enabled: process.env.NODE_ENV === "development"
+          }
+        },
+        debug: process.env.NODE_ENV === "development"
+      }}
+    >
+      {children}
+    </AnalyticsProvider>
+  );
+}
+```
+
+### Usage Examples
+
+#### Client Component
+
+```tsx
+"use client";
+
+import { useAnalytics, track } from "@repo/analytics/client/next";
+
+export function SignupButton() {
+  const analytics = useAnalytics();
+
+  const handleClick = async () => {
+    // Method 1: Direct tracking
+    await analytics.track("Button Clicked", { button_name: "signup" });
+
+    // Method 2: Emitter pattern (recommended)
+    const event = track("CTA Clicked", { cta_type: "signup" });
+    await analytics.emit(event);
+  };
+
+  return <button onClick={handleClick}>Sign Up</button>;
+}
+```
+
+#### Server Component / API Route
+
+```tsx
+// app/api/checkout/route.ts
+import { createServerAnalytics, ecommerce } from "@repo/analytics/server/next";
+
+export async function POST(request: Request) {
+  const analytics = await createServerAnalytics({
+    providers: {
+      posthog: { apiKey: process.env.POSTHOG_API_KEY! }
+    }
+  });
+
+  await analytics.emit(
+    ecommerce.CHECKOUT_STARTED({
+      order_id: "order_123",
+      value: 299.99,
+      currency: "USD",
+      products: [{ product_id: "prod_abc", price: 299.99, quantity: 1 }]
+    })
+  );
+
+  return Response.json({ success: true });
+}
+```
+
+#### E-commerce Events
+
+```typescript
+import { ecommerce } from "@repo/analytics/client/next";
+
+// Product viewed
+ecommerce.PRODUCT_VIEWED({
+  product_id: "prod_123",
+  name: "Premium Plan",
+  price: 299.99,
+  currency: "USD"
+});
+
+// Product added to cart
+ecommerce.PRODUCT_ADDED({
+  cart_id: "cart_abc",
+  product_id: "prod_123",
+  quantity: 1,
+  price: 299.99
+});
+
+// Order completed
+ecommerce.ORDER_COMPLETED({
+  order_id: "order_789",
+  revenue: 499.97,
+  currency: "USD",
+  products: [
+    /* ... */
+  ],
+  payment_method: "card"
+});
+```
+
+#### AI Product Events
+
+```typescript
+import { ai } from "@repo/analytics/client/next";
+
+// Chat message sent
+ai.CHAT_MESSAGE_SENT({
+  conversation_id: "conv_123",
+  message_id: "msg_456",
+  model_id: "gpt-4",
+  message_length: 150
+});
+
+// Message regenerated
+ai.MESSAGE_REGENERATED({
+  conversation_id: "conv_123",
+  model_id: "gpt-4",
+  original_message_id: "msg_456",
+  attempt_number: 2,
+  reason: "user-requested"
+});
+
+// Conversation branched
+ai.CONVERSATION_BRANCHED({
+  conversation_id: "conv_123",
+  parent_conversation_id: "conv_122",
+  branch_point_message_id: "msg_450",
+  reason: "explore-alternative"
+});
+```
+
+---
+
+## Architecture
+
+### Four-File Export Pattern
+
+```
+@repo/analytics
+├── /client          → Browser-only (posthog-js, @vercel/analytics client)
+├── /server          → Node.js server (posthog-node, segment server)
+├── /client/next     → Next.js client (hooks, provider, components)
+├── /server/next     → Next.js server (API routes, server components)
+├── /server/edge     → Edge runtime (middleware, edge API routes)
+└── /shared          → Environment-agnostic (emitters, types, utils)
+```
+
+**Import Rules:**
+
+- ✅ Client components: `@repo/analytics/client/next`
+- ✅ Server components/API routes: `@repo/analytics/server/next`
+- ✅ Edge runtime: `@repo/analytics/server/edge`
+- ❌ Never mix: Client + server imports cause build errors
+
+**Edge Runtime Limitations:**
+
+The `/server/edge` export provides a simplified implementation compatible with edge runtime:
+
+- ✅ Basic tracking (track, identify, page, group, alias)
+- ✅ Console provider (console API)
+- ✅ PostHog provider (HTTP API, no SDK dependency)
+- ✅ Emitter pattern support (`emit()`)
+- ❌ No event deduplication (no LRU cache)
+- ❌ No rate limiting enforcement
+- ❌ No feature flags (requires Node.js SDK)
+- ❌ No batch processing optimization
+
+For full features, use `/server` or `/server/next` in Node.js environments.
+
+---
+
+## Core API
+
+### Analytics Manager
+
+```typescript
+// Create analytics instance
+const analytics = await createClientAnalytics(config);
+
+// Track events
+await analytics.track("Event Name", { property: "value" });
+
+// Identify users
+await analytics.identify("user_123", { email: "user@example.com" });
+
+// Track page views
+await analytics.page("/pricing", { title: "Pricing Page" });
+
+// Group/organization
+await analytics.group("org_456", { name: "Acme Corp" });
+
+// Emit emitter payloads
+const event = track("Event", { data: "value" });
+await analytics.emit(event);
+
+// Batch processing
+await analytics.emitBatch([event1, event2, event3], {
+  concurrency: 5,
+  failFast: false
+});
+```
+
+### React Hooks
+
+```typescript
+// Access analytics manager
+const analytics = useAnalytics();
+
+// Track on mount
+useTrackEvent("Page Viewed", { page: "/dashboard" });
+
+// Identify user on mount
+useIdentifyUser(user.id, { email: user.email });
+
+// Auto page tracking
+usePageTracking();
+```
+
+---
+
+## Feature Flags (PostHog)
+
+### Client-Side
+
+```typescript
+import { useAnalytics } from '@repo/analytics/client/next';
+
+function FeatureFlag() {
+  const analytics = useAnalytics();
+  const provider = analytics.getProvider('posthog');
+  const [enabled, setEnabled] = useState(false);
+
+  useEffect(() => {
+    provider?.isFeatureEnabled('new-feature').then(setEnabled);
+  }, [provider]);
+
+  return enabled ? <NewFeature /> : <OldFeature />;
+}
+```
+
+### Server-Side
+
+```tsx
+// app/page.tsx
+import { createServerAnalytics } from "@repo/analytics/server/next";
+
+export default async function Page() {
+  const analytics = await createServerAnalytics({
+    providers: { posthog: { apiKey: process.env.POSTHOG_API_KEY! } }
+  });
+
+  const provider = analytics.getProvider("posthog");
+  const showFeature = await provider?.getFeatureFlag("new-feature", "user_123");
+
+  return <div>{showFeature ? <New /> : <Old />}</div>;
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**"Analytics not initialized"**
+
+- Ensure you await `createClientAnalytics()` or `createServerAnalytics()`
+
+**"Provider not available in this environment"**
+
+- Check you're using correct import path (client vs server vs edge)
+
+**Events not showing in PostHog**
+
+- Verify API key is correct
+- Enable debug mode: `options: { debug: true }`
+- Check network tab for failed requests
+
+**"structuredClone is not defined"**
+
+- Upgrade to Node.js 22+ (required)
+
+### Debug Mode
+
+```typescript
+const analytics = await createClientAnalytics({
+  providers: {
+    posthog: {
+      apiKey: "...",
+      options: { debug: true }
+    }
+  },
+  debug: true,
+  onInfo: (msg) => console.log("[Analytics]", msg),
+  onError: (err, ctx) => console.error("[Analytics Error]", err, ctx)
+});
+```
+
+### Health Check
+
+```typescript
+const health = await analytics.healthCheck(5000);
+console.log("Healthy:", health.healthy);
+console.log("Providers:", health.providers);
+```
+
+---
+
+## Security
+
+⚠️ **Important Security Notes:**
+
+1. **Never track PII** - Avoid email, phone, SSN, credit cards
+2. **Sanitize input** - Validate all properties before tracking
+3. **Use env variables** - Never hardcode API keys
+4. **Rotate keys** - Update API keys periodically
+
+**Security Features (Implemented):**
+
+- ✅ Input sanitization (`sanitizeProperties()`)
+- ✅ PII detection and redaction (`containsPII()`, `redactPII()`)
+- ✅ XSS protection (`stripHTML()`)
+- ✅ Payload size limits (default: 100KB max)
+- ✅ Dangerous key blocking (prevents `__proto__`, `constructor`)
+- ✅ Rate limiting (token bucket algorithm, 100 calls/second default)
+
+**Usage:**
+
+```typescript
+import { sanitizeProperties, containsPII } from "@repo/analytics/server";
+
+// Sanitize before tracking
+const sanitized = sanitizeProperties(userInput, {
+  stripPII: true,
+  stripHTML: true,
+  maxPayloadSize: 50_000 // 50KB
+});
+
+// Check for PII
+if (containsPII(JSON.stringify(properties))) {
+  console.warn("PII detected in analytics payload");
+}
+```
+
+---
+
+## Documentation
+
+- **Full Documentation**: [Analytics Package Docs](../../apps/docs/packages/analytics.mdx)
+- **Audit Findings**: [AUDIT_FINDINGS.md](./AUDIT_FINDINGS.md)
+- **API Reference**: See source code JSDoc comments
+- **Examples**: [`src/examples/`](./src/examples/)
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm --filter=@repo/analytics test
+
+# Type check
+pnpm --filter=@repo/analytics typecheck
+
+# Lint
+pnpm --filter=@repo/analytics lint
+
+# Coverage
+pnpm --filter=@repo/analytics test:coverage
+
+# Check circular deps
+pnpm --filter=@repo/analytics circular
+```
+
+---
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/your-org/monorepo/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/your-org/monorepo/discussions)
+
+---
+
+## License
+
+MIT License
+
+---
+
+**Built with ❤️ by the Platform Team**
+
+## 📚 Comprehensive Documentation
+
+For detailed documentation, see:
+
+- **[Audit Reports](../../apps/docs/content/docs/audits/analytics/)** - Comprehensive audits, fixes, and security
+  reviews
+- **[Technical Guides](../../apps/docs/content/docs/packages/analytics/)** - Implementation guides and best practices
+
+All comprehensive documentation has been centralized in the docs app.