@od-oneapp/analytics 2026.2.1501-canary.1

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# @repo/analytics
+
+## 2.0.0
+
+### Major Changes
+
+- [`b626058`](https://github.com/OneDigital-Product/monorepo/commit/b6260582c2d9b7aaee89e3fb8c11515fd02cdfcf) Thanks
+  [@m-torin](https://github.com/m-torin)! - **BREAKING CHANGE**: Redesign AI tracking for ChatGPT/Claude-style product
+  features
+
+  Completely redesigned the AI tracking system to focus on **AI product features** instead of business use cases:
+
+  **Philosophy Change**: Track the AI product itself (chat features, artifacts, code generation), not what users do with
+  it (business workflows).
+
+  **Key Changes**:
+  - Renamed `aiSdk.*` → `ai.*` namespace for cleaner API
+  - 90+ new events for ChatGPT/Claude/Copilot-style features
+  - Clear separation from e-commerce tracking (`ai.*` vs `ecommerce.*`)
+  - Comprehensive product feature coverage:
+    - Message regeneration, editing, branching
+    - Conversation management & organization
+    - Code generation with copy/execute tracking
+    - Interactive artifacts & canvas (Claude-style)
+    - File upload, processing, referencing
+    - Context & memory management
+    - Collaboration & sharing features
+    - User feedback & quality signals
+    - System operations & performance
+
+  **Migration Guide**:
+
+  ```typescript
+  // Before (AI SDK v6 technical operations)
+  import { aiSdk } from '@repo/analytics/shared';
+  aiSdk.agentExecutionCompleted({ ... });
+  aiSdk.chatMessageReceived({ ... });
+
+  // After (AI product features)
+  import { ai } from '@repo/analytics/shared';
+  ai.MESSAGE_RECEIVED({ ... });
+  ai.MESSAGE_REGENERATED({ ... });
+  ai.CODE_GENERATED({ ... });
+  ai.ARTIFACT_CREATED({ ... });
+  ```
+
+  **New Features**:
+  - `ai.MESSAGE_REGENERATED()` - Track regeneration attempts
+  - `ai.BRANCH_CREATED()` - Track conversation branching
+  - `ai.CODE_GENERATED()` - Track code generation
+  - `ai.ARTIFACT_CREATED()` - Track Claude-style artifacts
+  - `ai.CONVERSATION_SHARED()` - Track sharing features
+  - `ai.CUSTOM_INSTRUCTIONS_UPDATED()` - Track user preferences
+  - ...and 84 more product-focused events
+
+  **Documentation**:
+  - New comprehensive README at `src/shared/emitters/ai/README.md`
+  - Clear examples for ChatGPT/Claude-style implementations
+  - Complete type definitions for all 90+ events
+
+  This is a major version bump because:
+  1. Renamed namespace (`aiSdk` → `ai`) breaks existing imports
+  2. Event structure completely redesigned for product features
+  3. Old e-commerce chatbot events deprecated (use `ecommerce.*` instead)
+
+### Minor Changes
+
+- [`b626058`](https://github.com/OneDigital-Product/monorepo/commit/b6260582c2d9b7aaee89e3fb8c11515fd02cdfcf) Thanks
+  [@m-torin](https://github.com/m-torin)! - feat(analytics): expand AI tracking to 100+ events covering complete chatbot
+  journey
+
+  Renamed from `aiSdk` to `ai` and dramatically expanded event coverage:
+
+  **100+ Comprehensive Events** organized by customer journey stage:
+  - **Conversation (7)**: Session lifecycle, messages
+  - **Intent & Understanding (8)**: Intent detection, context switching, clarifications, misunderstandings
+  - **Product Discovery (7)**: Search, browse, visual/voice search, comparisons
+  - **Size & Fit (5)**: Size charts, fit recommendations, virtual try-on
+  - **Style & Preferences (4)**: Style profiling, preference learning
+  - **Recommendations (11)**: Upsell, cross-sell, bundles, gifts, personalized
+  - **Cart & Purchase (8)**: Cart management, promo codes, checkout start
+  - **Checkout Assistance (7)**: Address, payment, shipping help
+  - **Post-Purchase (7)**: Order tracking, product support, warranty, reviews
+  - **Returns & Exchanges (5)**: Return policy, initiation, label requests
+  - **Proactive Engagement (8)**: Greetings, cart recovery, deal alerts, re-engagement
+  - **Support & Escalation (10)**: FAQ, complaints, handoffs, escalation
+  - **Sentiment & Satisfaction (6)**: Sentiment tracking, satisfaction surveys
+  - **Personalization (4)**: User profiling, segmentation
+  - **Technical (10)**: Agent execution, completions, tools, streaming
+
+  **Auto-Detection Utilities:**
+  - `detectIntent()` - Auto-detect user intent from message (11 intent types)
+  - `detectSentiment()` - Sentiment analysis (positive/negative/neutral/mixed)
+  - `needsClarification()` - Detect ambiguous messages
+  - `extractProductMentions()` - Extract product categories
+  - `calculateQualityScore()` - Conversation quality scoring
+
+  **Enhanced Event Properties:**
+  - Intent confidence scores & detected entities
+  - Sentiment triggers & confidence
+  - Recommendation sources & triggers
+  - Abandonment recovery metrics
+  - Handoff reasons & escalation paths
+  - User profile completeness
+  - Conversation quality metrics
+
+  **Complete Event Reference:**
+  - `AI_EVENTS_REFERENCE.md` - 100+ events with examples
+  - Organized by customer journey stage
+  - Quick reference for common events
+  - Integration examples for all scenarios
+
+  **Breaking Changes:**
+  - Renamed `aiSdk` namespace to `ai`
+  - Import: `import { ai } from '@repo/analytics/client/next'`
+  - All event names follow pattern: `AI_EVENTS.EVENT_NAME`
+
+  **Migration:**
+
+  ```typescript
+  // Before
+  import { aiSdk } from '@repo/analytics/client/next';
+  aiSdk.agentExecutionCompleted({ ... });
+
+  // After
+  import { ai } from '@repo/analytics/client/next';
+  ai.AGENT_EXECUTION_COMPLETED({ ... });
+  ```
+
+  Now tracks complete e-commerce chatbot customer journey from first interaction to post-purchase support with sentiment
+  analysis, proactive engagement, and quality monitoring.
+
+### Patch Changes
+
+- Updated dependencies
+  [[`e6c009d`](https://github.com/OneDigital-Product/monorepo/commit/e6c009dbd60afb0824a9418b97da15f8b43a3ecf),
+  [`9b7ff31`](https://github.com/OneDigital-Product/monorepo/commit/9b7ff317f2ac6d2088b4f194bea16aa15915cb80),
+  [`be5007c`](https://github.com/OneDigital-Product/monorepo/commit/be5007cf21959d0e5b15f8b602868b7adc567287),
+  [`1bec7a6`](https://github.com/OneDigital-Product/monorepo/commit/1bec7a65f975f3ff4ce35d1adc56611de76c16a4)]:
+  - @repo/observability@2025.11.1202
+  - @repo/shared@2025.11.1201

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.