@od-oneapp/analytics 2026.2.2301-canary → 2026.2.2899-canary

package/README.md

@@ -1,91 +1,70 @@
-# @repo/analytics
+# @od-oneapp/analytics
 
-> **Multi-provider analytics package with type-safe event tracking, comprehensive ecommerce support, and AI product
-> analytics**
+> **Multi-provider analytics with Segment.io-style fan-out, type-safe event tracking, and Zod-validated catalogs**
 
 [![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)
+- Node.js 22.0.0+
 - 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`
+- **Client**: `./client`, `./client/next`
+- **Server**: `./server`, `./server/next`
+- **Types**: `./types`
+- **Catalogs**: `./catalogs`
+- **HTTP Provider**: `./providers/http`, `./providers/http/client`, `./providers/http/server`
 
 **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)
+- Multi-Provider fan-out (PostHog, Segment, Vercel Analytics, HTTP, Console)
+- Type-Safe Emitters (Segment.io specification)
+- Zod-validated event catalogs (ecommerce, AI)
+- Universal (client/server environments)
+- Next.js App Router integration (hooks, components, provider)
+- **Opt-in external providers** — only install what you use
 
 ---
 
 ## 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
+pnpm add @od-oneapp/analytics
 ```
 
-### Install Providers (Peer Dependencies)
+### External Providers (opt-in)
 
-Install only the providers you need:
+External analytics providers are **not bundled** with this package. Install only the ones 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
+# PostHog
+pnpm add @od-oneapp/integration-posthog
 
 # Segment
-pnpm add @segment/analytics-next --filter=your-app
+pnpm add @od-oneapp/integration-segment
 
-# Console (built-in, no installation needed)
+# Vercel Analytics
+pnpm add @od-oneapp/integration-vercel
 ```
 
----
-
-## Quick Start
-
-### Environment Variables
-
-```bash
-# .env.local
+Built-in providers (`console`, `http`) are always available with no additional installation.
 
-# PostHog (Primary)
-NEXT_PUBLIC_POSTHOG_KEY=phc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-NEXT_PUBLIC_POSTHOG_HOST=https://app.posthog.com
+If you configure a provider without installing its package, you'll get a clear error:
 
-# Vercel Analytics (Optional)
-VERCEL_ANALYTICS_ID=your-analytics-id
+```
+Analytics provider "posthog" is configured but its package is not installed.
+Run: pnpm add @od-oneapp/integration-posthog
+```
 
-# Segment (Optional)
-NEXT_PUBLIC_SEGMENT_WRITE_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+---
 
-# Development
-NEXT_PUBLIC_CONSOLE_ANALYTICS=true
-```
+## Quick Start
 
 ### Next.js Setup
 
@@ -93,7 +72,7 @@ NEXT_PUBLIC_CONSOLE_ANALYTICS=true
 // app/providers.tsx
 "use client";
 
-import { AnalyticsProvider } from "@repo/analytics/client/next";
+import { AnalyticsProvider } from "@od-oneapp/analytics/client/next";
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return (
@@ -104,14 +83,14 @@ export function Providers({ children }: { children: React.ReactNode }) {
             apiKey: process.env.NEXT_PUBLIC_POSTHOG_KEY!,
             options: {
               debug: process.env.NODE_ENV === "development",
-              capture_pageview: false
-            }
+              capture_pageview: false,
+            },
           },
           console: {
-            enabled: process.env.NODE_ENV === "development"
-          }
+            enabled: process.env.NODE_ENV === "development",
+          },
         },
-        debug: process.env.NODE_ENV === "development"
+        debug: process.env.NODE_ENV === "development",
       }}
     >
       {children}
@@ -120,118 +99,76 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
-### Usage Examples
-
-#### Client Component
+### Client Component
 
 ```tsx
 "use client";
 
-import { useAnalytics, track } from "@repo/analytics/client/next";
+import { useAnalytics, track } from "@od-oneapp/analytics/client/next";
 
 export function SignupButton() {
   const analytics = useAnalytics();
 
   const handleClick = async () => {
-    // Method 1: Direct tracking
-    await analytics.track("Button Clicked", { button_name: "signup" });
+    // Direct tracking
+    await analytics?.track("Button Clicked", { button_name: "signup" });
 
-    // Method 2: Emitter pattern (recommended)
+    // Emitter pattern
     const event = track("CTA Clicked", { cta_type: "signup" });
-    await analytics.emit(event);
+    await analytics?.emit(event);
   };
 
   return <button onClick={handleClick}>Sign Up</button>;
 }
 ```
 
-#### Server Component / API Route
+### Server (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! }
-    }
-  });
+```typescript
+import { createServerAnalytics } from "@od-oneapp/analytics/server";
 
-  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 }]
-    })
-  );
+const analytics = await createServerAnalytics({
+  providers: {
+    posthog: { apiKey: process.env.POSTHOG_API_KEY! },
+  },
+});
 
-  return Response.json({ success: true });
-}
+await analytics.track("Order Completed", { orderId: "ord-123", total: 99.99 });
 ```
 
-#### E-commerce Events
+### Console + HTTP Only (no external deps needed)
 
 ```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"
-});
+import { createClientAnalytics } from "@od-oneapp/analytics/client";
 
-// Product added to cart
-ecommerce.PRODUCT_ADDED({
-  cart_id: "cart_abc",
-  product_id: "prod_123",
-  quantity: 1,
-  price: 299.99
+const analytics = await createClientAnalytics({
+  providers: {
+    console: { enabled: true },
+    http: { options: { endpoint: "/api/v1/ingest" } },
+  },
 });
 
-// Order completed
-ecommerce.ORDER_COMPLETED({
-  order_id: "order_789",
-  revenue: 499.97,
-  currency: "USD",
-  products: [
-    /* ... */
-  ],
-  payment_method: "card"
-});
+await analytics.track("Page Loaded", { path: window.location.pathname });
 ```
 
-#### AI Product Events
+### Event Catalogs (Zod-validated)
 
 ```typescript
-import { ai } from "@repo/analytics/client/next";
+import { ecommerceCatalog, aiCatalog } from "@od-oneapp/analytics/catalogs";
 
-// Chat message sent
-ai.CHAT_MESSAGE_SENT({
-  conversation_id: "conv_123",
-  message_id: "msg_456",
-  model_id: "gpt-4",
-  message_length: 150
+// Type-safe ecommerce events
+const event = ecommerceCatalog.track("Product Viewed", {
+  product_id: "sku-123",
+  name: "Premium Plan",
+  price: 29.99,
+  currency: "USD",
 });
 
-// Message regenerated
-ai.MESSAGE_REGENERATED({
-  conversation_id: "conv_123",
+// Type-safe AI events
+const aiEvent = aiCatalog.track("Chat Message Sent", {
+  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"
+  message_length: 150,
 });
 ```
 
@@ -239,39 +176,35 @@ ai.CONVERSATION_BRANCHED({
 
 ## 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)
+@od-oneapp/analytics
+├── /client          → Browser-only (built-in registry + dynamic external loader)
+├── /server          → Node.js server (built-in registry + dynamic external loader)
+├── /client/next     → Next.js client (hooks, provider, components, dynamic imports)
+├── /server/next     → Next.js server (re-exports from /server)
+├── /types           → TypeScript types + MissingProviderPackageError
+├── /catalogs        → Zod-validated event catalogs
+└── /providers/http  → Built-in HTTP provider
 ```
 
 **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:**
+- Client components: `@od-oneapp/analytics/client/next`
+- Server components/API routes: `@od-oneapp/analytics/server/next`
+- Non-Next.js client: `@od-oneapp/analytics/client`
+- Non-Next.js server: `@od-oneapp/analytics/server`
 
-The `/server/edge` export provides a simplified implementation compatible with edge runtime:
+**Provider Architecture:**
 
-- ✅ 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
+| Provider | Type | Package |
+|----------|------|---------|
+| Console | Built-in | (included) |
+| HTTP | Built-in | (included) |
+| PostHog | Opt-in | `@od-oneapp/integration-posthog` |
+| Segment | Opt-in | `@od-oneapp/integration-segment` |
+| Vercel | Opt-in | `@od-oneapp/integration-vercel` |
 
-For full features, use `/server` or `/server/next` in Node.js environments.
+External providers are loaded dynamically at runtime via `import()` — only when configured. If the package isn't installed, a `MissingProviderPackageError` is thrown with the install command.
 
 ---
 
@@ -280,230 +213,78 @@ For full features, use `/server` or `/server/next` in Node.js environments.
 ### 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
+// Emitter pattern
 const event = track("Event", { data: "value" });
 await analytics.emit(event);
 
 // Batch processing
-await analytics.emitBatch([event1, event2, event3], {
-  concurrency: 5,
-  failFast: false
-});
+await analytics.emitBatch([event1, event2, event3]);
 ```
 
 ### React Hooks
 
 ```typescript
-// Access analytics manager
 const analytics = useAnalytics();
+const track = useTrackEvent();
+const identify = useIdentifyUser();
 
-// 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 />;
-}
+usePageTracking({ trackSearch: true });
 ```
 
-### Server-Side
+### Tracked Components
 
 ```tsx
-// app/page.tsx
-import { createServerAnalytics } from "@repo/analytics/server/next";
+<TrackedButton eventName="Sign Up Clicked" properties={{ location: "header" }}>
+  Sign Up
+</TrackedButton>
 
-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)
-});
+<TrackedLink href="/products" eventName="Product Link Clicked">
+  View Products
+</TrackedLink>
 ```
 
-### 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:**
+### Error Handling
 
 ```typescript
-import { sanitizeProperties, containsPII } from "@repo/analytics/server";
-
-// Sanitize before tracking
-const sanitized = sanitizeProperties(userInput, {
-  stripPII: true,
-  stripHTML: true,
-  maxPayloadSize: 50_000 // 50KB
-});
+import { MissingProviderPackageError } from "@od-oneapp/analytics/types";
 
-// Check for PII
-if (containsPII(JSON.stringify(properties))) {
-  console.warn("PII detected in analytics payload");
+try {
+  const analytics = await createClientAnalytics({
+    providers: { posthog: { apiKey: "..." } },
+  });
+} catch (error) {
+  if (error instanceof MissingProviderPackageError) {
+    console.error(error.message);
+    // "Analytics provider "posthog" is configured but its package is not installed.
+    //  Run: pnpm add @od-oneapp/integration-posthog"
+  }
 }
 ```
 
 ---
 
-## Documentation
+## Security
 
-- **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/)
+- Input sanitization (`sanitizeProperties()`)
+- PII detection and redaction (`containsPII()`, `redactPII()`)
+- XSS protection (`stripHTML()`)
+- Payload size limits (default: 100KB max)
+- Rate limiting (token bucket algorithm)
 
 ---
 
 ## 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
+pnpm --filter @od-oneapp/analytics test
+pnpm --filter @od-oneapp/analytics typecheck
+pnpm --filter @od-oneapp/analytics lint
+pnpm --filter @od-oneapp/analytics build
 ```
-
----
-
-## 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.