shopkit-analytics 1.0.0

package/README.md

@@ -0,0 +1,769 @@
+# @shopkit/analytics
+
+A comprehensive analytics package for e-commerce applications with support for multiple analytics platforms including Google Analytics 4, Facebook Pixel, MoEngage, PostHog, Shopify Analytics, KwikPass, and KwikCheckout.
+
+## 🚀 Features
+
+- **Multiple Analytics Platforms**: Support for 7+ analytics adapters
+- **Event-Driven Architecture**: Publisher-subscriber pattern for flexible event handling
+- **TypeScript Support**: Full type safety and IntelliSense
+- **Affiliate Tracking**: Built-in UTM parameter and attribution tracking
+- **React Integration**: Easy-to-use React components
+- **Selective Adapter Routing**: Route events to specific adapters
+- **Professional Logging**: High-performance structured logging with Pino
+- **Debug Mode**: Comprehensive logging for development and production
+
+## 📦 Installation
+
+```bash
+npm install @shopkit/analytics
+# or
+yarn add @shopkit/analytics
+# or
+bun add @shopkit/analytics
+```
+
+## 🎯 Quick Start
+
+### Basic Setup
+
+```tsx
+import { ShopkitAnalytics } from "@shopkit/analytics";
+
+export function App() {
+  return (
+    <ShopkitAnalytics
+      config={{
+        googleAnalytics: {
+          measurementId: "G-XXXXXXXXXX",
+        },
+        facebookPixel: {
+          pixelId: "123456789",
+        },
+        logger: {
+          enabled: true,
+          level: "info",
+          prettyPrint: process.env.NODE_ENV === "development",
+        },
+      }}
+      onInitialized={() => console.log("Analytics initialized")}
+      onError={(error) => console.error("Analytics error:", error)}
+    >
+      <YourApp />
+    </ShopkitAnalytics>
+  );
+}
+```
+
+### Event Tracking
+
+```tsx
+import { publishEvent, EventType } from "@shopkit/analytics";
+
+// Track page view
+publishEvent({
+  type: EventType.PAGE_VIEW,
+  path: "/products/example",
+  title: "Product Page",
+});
+
+// Track add to cart
+publishEvent({
+  type: EventType.ADD_TO_CART,
+  productId: "123",
+  productName: "Example Product",
+  price: 29.99,
+  quantity: 1,
+});
+```
+
+## 🔧 Analytics Adapters
+
+### 1. Google Analytics 4
+
+Track events to Google Analytics 4 with enhanced e-commerce support.
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    googleAnalytics: {
+      measurementId: "G-XXXXXXXXXX",
+      enableDebugLogs: true,
+      customDimensions: {
+        user_type: "premium",
+      },
+    },
+  }}
+/>
+```
+
+**Supported Events:**
+- Page views, product views, add to cart
+- Checkout events, purchases
+- Search, scroll, form interactions
+- Custom events with parameters
+
+### 2. Facebook Pixel
+
+Track conversions and optimize Facebook ad campaigns.
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    facebookPixel: {
+      pixelId: "123456789",
+      enableDebugLogs: true,
+      enableAdvancedMatching: true,
+    },
+  }}
+/>
+```
+
+**Supported Events:**
+- ViewContent, AddToCart, Purchase
+- InitiateCheckout, Search
+- Custom conversions
+
+### 3. MoEngage
+
+Engage users with personalized campaigns and analytics.
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    moengage: {
+      appId: "YOUR_MOENGAGE_APP_ID",
+      enableDebugLogs: true,
+      region: "DEFAULT", // or "EU"
+    },
+  }}
+/>
+```
+
+**Supported Events:**
+- E-commerce events (purchase, cart updates)
+- User lifecycle events (registration, login)
+- Custom events with user attributes
+
+### 4. PostHog
+
+Product analytics and feature flags platform.
+
+> **Important**: PostHog adapter assumes the PostHog script is already loaded in your application. You need to include the PostHog script in your HTML or load it separately.
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    posthog: {
+      enableDebugLogs: true,
+    },
+  }}
+/>
+```
+
+**Setup Requirements:**
+
+Add PostHog script to your HTML head or load it programmatically:
+
+```html
+<!-- Add to your HTML head -->
+<script>
+  !function(t,e){var o,n,p,r;e.__SV||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]);t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}(p=t.createElement("script")).type="text/javascript",p.async=!0,p.src=s.api_host+"/static/array.js",(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],u.toString=function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e},u.people.toString=function(){return u.toString(1)+".people (stub)"},o="capture identify alias people.set people.set_once set_config register register_once unregister opt_out_capturing has_opted_out_capturing opt_in_capturing reset isFeatureEnabled onFeatureFlags getFeatureFlag getFeatureFlagPayload reloadFeatureFlags group updateEarlyAccessFeatureEnrollment getEarlyAccessFeatures getActiveMatchingSurveys getSurveys".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+  posthog.init('YOUR_POSTHOG_KEY', {api_host: 'https://app.posthog.com'})
+</script>
+```
+
+Or load it programmatically:
+
+```tsx
+// In your app initialization
+import posthog from 'posthog-js'
+
+posthog.init('YOUR_POSTHOG_KEY', {
+  api_host: 'https://app.posthog.com'
+})
+```
+
+**Environment Variables:**
+```bash
+NEXT_PUBLIC_POSTHOG_KEY="phc_xxxxxxxxxx"
+```
+
+**Supported Events:**
+- Product analytics events
+- User behavior tracking
+- Feature usage analytics
+
+### 5. Shopify Analytics
+
+Native Shopify Admin Analytics integration.
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    shopify: {
+      shopId: "your-shop-id",
+      domain: "your-shop.myshopify.com",
+      currency: "USD",
+    },
+  }}
+/>
+```
+
+**Environment Variables:**
+```bash
+NEXT_PUBLIC_SHOPIFY_SHOP_ID="your-shop-id"
+NEXT_PUBLIC_SHOPIFY_DOMAIN="your-shop.myshopify.com"
+NEXT_PUBLIC_SHOPIFY_CURRENCY="USD"
+```
+
+**Supported Events:**
+- Page views, product views
+- Add to cart, checkout events
+- Session tracking with Shopify cookies
+
+### 6. KwikPass Analytics
+
+Custom analytics adapter for KwikPass platform integration.
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    kwikpass: {
+      enableDebugLogs: true,
+      enableKwikPassEvents: true,
+    },
+  }}
+/>
+```
+
+**Supported Events:**
+- Product views, collection views
+- Page views with custom event dispatching
+- Enhanced affiliate parameter tracking
+
+### 7. KwikCheckout Analytics (GoKwik)
+
+Comprehensive checkout analytics adapter for GoKwik platform integration.
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    kwikcheckout: {
+      mid: "your-gokwik-mid",
+      environment: "production", // or "staging"
+      storeId: "your-store-id",
+      enableDebugLogs: true,
+    },
+  }}
+/>
+```
+
+**Environment Variables:**
+```bash
+NEXT_PUBLIC_GOKWIK_MID="your-gokwik-mid"
+NEXT_PUBLIC_GOKWIK_ENVIRONMENT="production"
+NEXT_PUBLIC_STORE_ID="your-store-id"
+```
+
+**Supported Events:**
+- Checkout flow events (started, completed)
+- Address and payment method selection
+- Mobile number and PIN code addition
+- Order success and completion tracking
+- Cart viewing and payment info events
+
+**GoKwik-Specific Events:**
+- `STARTED_CHECKOUT_GK` - Checkout initiation
+- `MOBILE_ADDED_GK` - Mobile number added
+- `ADDRESS_SELECTED_GK` - Address selection
+- `ADDRESS_COMPLETED_GK` - Address completion
+- `ADDRESS_ADDED_GK` - New address added
+- `PIN_CODE_ADDED_GK` - PIN code verification
+- `PAYMENT_METHOD_SELECTED_GK` - Payment method choice
+- `PAYMENT_COMPLETED_GK` - Payment completion
+- `ORDER_SUCCESS` - Order success confirmation
+- `ORDER_COMPLETED` - Order fulfillment
+
+## 📝 Professional Logging System
+
+The analytics package includes a comprehensive logging system built on [Pino](https://github.com/pinojs/pino), a high-performance JSON logger for Node.js and browsers.
+
+### Logger Configuration
+
+Configure logging behavior for all adapters:
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    // ... other config
+    logger: {
+      enabled: true,
+      level: "info", // "trace" | "debug" | "info" | "warn" | "error" | "fatal"
+      prettyPrint: process.env.NODE_ENV === "development",
+      redact: ["password", "token", "apiKey"], // Redact sensitive data
+    },
+    // Legacy support (deprecated but still works)
+    enableDebugLogs: true, // Maps to logger.enabled
+  }}
+/>
+```
+
+### Log Levels
+
+The logger supports standard log levels with appropriate use cases:
+
+```tsx
+// TRACE: Very detailed debugging information
+logger.trace("Detailed execution flow");
+
+// DEBUG: General debugging information
+logger.debug("Processing event", { eventType: "add_to_cart" });
+
+// INFO: General information about application flow
+logger.info("Analytics adapter initialized", { adapterName: "GoogleAnalytics" });
+
+// WARN: Warning messages for potential issues
+logger.warn("Missing optional parameter", { parameter: "currency" });
+
+// ERROR: Error conditions that don't stop the application
+logger.error("Failed to send event", new Error("Network timeout"));
+
+// FATAL: Critical errors that may cause application termination
+logger.fatal("Critical system failure", new Error("Database connection lost"));
+```
+
+### Structured Logging
+
+All logs are structured with contextual information:
+
+```json
+{
+  "level": 30,
+  "time": 1635724800000,
+  "name": "@shopkit/analytics",
+  "adapter": "GoogleAnalytics",
+  "msg": "Event tracked successfully",
+  "eventType": "add_to_cart",
+  "productId": "123",
+  "price": 29.99
+}
+```
+
+### Browser-Friendly Output
+
+In development mode with `prettyPrint: true`:
+
+```
+[14:20:00.123] INFO (@shopkit/analytics/GoogleAnalytics): Event tracked successfully
+    eventType: "add_to_cart"
+    productId: "123"
+    price: 29.99
+```
+
+### Sensitive Data Redaction
+
+Automatically redact sensitive information:
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    logger: {
+      enabled: true,
+      redact: [
+        "password",
+        "token",
+        "apiKey",
+        "creditCard",
+        "ssn",
+        "email", // Optional: redact PII
+      ],
+    },
+  }}
+/>
+```
+
+### Adapter-Specific Logging
+
+Each adapter gets its own logger instance with proper naming:
+
+```tsx
+// Google Analytics logs
+[GoogleAnalytics] Event tracked successfully
+
+// Facebook Pixel logs  
+[FacebookPixel] Pixel event sent
+
+// MoEngage logs
+[MoEngage] User attribute updated
+
+// PostHog logs
+[PostHog] Feature flag evaluated
+
+// Shopify Analytics logs
+[ShopifyAnalytics] Session tracking enabled
+
+// KwikPass logs
+[KwikPass] Custom event dispatched
+
+// KwikCheckout logs
+[KwikCheckout] Checkout event processed
+```
+
+### Production Logging
+
+For production environments, use structured JSON logging:
+
+```tsx
+const analyticsConfig = {
+  logger: {
+    enabled: true,
+    level: process.env.NODE_ENV === "production" ? "warn" : "debug",
+    prettyPrint: false, // JSON output for log aggregation
+    redact: ["password", "token", "apiKey", "email"],
+  },
+};
+```
+
+## 🎯 Event Types
+
+### E-commerce Events
+
+```tsx
+// Product View
+publishEvent({
+  type: EventType.PRODUCT_VIEW,
+  productId: "123",
+  productName: "Example Product",
+  price: 29.99,
+  currency: "USD",
+  category: "Electronics",
+});
+
+// Add to Cart
+publishEvent({
+  type: EventType.ADD_TO_CART,
+  productId: "123",
+  productName: "Example Product",
+  price: 29.99,
+  quantity: 2,
+  variant: "Red",
+});
+
+// Checkout Started
+publishEvent({
+  type: EventType.CHECKOUT_STARTED,
+  cartValue: 59.98,
+  currency: "USD",
+  itemCount: 2,
+  items: [
+    {
+      productId: "123",
+      productName: "Example Product",
+      price: 29.99,
+      quantity: 2,
+    },
+  ],
+});
+```
+
+### User Interaction Events
+
+```tsx
+// Page View
+publishEvent({
+  type: EventType.PAGE_VIEW,
+  path: "/products/example",
+  title: "Product Page",
+  referrer: document.referrer,
+});
+
+// Button Click
+publishEvent({
+  type: EventType.BUTTON_CLICK,
+  buttonId: "cta-button",
+  buttonText: "Buy Now",
+  location: "product-page",
+});
+
+// Search
+publishEvent({
+  type: EventType.SEARCH,
+  searchTerm: "wireless headphones",
+  resultsCount: 25,
+});
+```
+
+### GoKwik Checkout Events
+
+```tsx
+// Started Checkout
+publishEvent({
+  type: EventType.STARTED_CHECKOUT_GK,
+  cartValue: 99.99,
+  currency: "USD",
+});
+
+// Mobile Added
+publishEvent({
+  type: EventType.MOBILE_ADDED_GK,
+  mobile: "+1234567890",
+});
+
+// Address Selected
+publishEvent({
+  type: EventType.ADDRESS_SELECTED_GK,
+  addressId: "addr_123",
+});
+
+// Payment Method Selected
+publishEvent({
+  type: EventType.PAYMENT_METHOD_SELECTED_GK,
+  paymentMethod: "credit_card",
+});
+
+// Payment Completed
+publishEvent({
+  type: EventType.PAYMENT_COMPLETED_GK,
+  amount: 99.99,
+  currency: "USD",
+});
+
+// Order Success
+publishEvent({
+  type: EventType.ORDER_SUCCESS,
+  orderId: "order_123",
+  amount: 99.99,
+  currency: "USD",
+});
+```
+
+## 🔀 Selective Adapter Routing
+
+Route events to specific adapters for optimized performance:
+
+```tsx
+// Send to specific adapters only
+publishEvent(
+  {
+    type: EventType.ADD_TO_CART,
+    productId: "123",
+    productName: "Example Product",
+    price: 29.99,
+  },
+  {
+    adapters: ["GoogleAnalytics", "FacebookPixel"], // Only these adapters
+  }
+);
+
+// Send GoKwik events only to KwikCheckout adapter
+publishEvent(
+  {
+    type: EventType.STARTED_CHECKOUT_GK,
+    cartValue: 99.99,
+    currency: "USD",
+  },
+  {
+    adapters: ["KwikCheckout"], // Only GoKwik adapter
+  }
+);
+
+// Exclude specific adapters
+publishEvent(
+  {
+    type: EventType.PAGE_VIEW,
+    path: "/internal-page",
+    title: "Internal Page",
+  },
+  {
+    excludeAdapters: ["FacebookPixel"], // All except Facebook Pixel
+  }
+);
+```
+
+## 🏷️ Affiliate Tracking
+
+Built-in affiliate parameter tracking and attribution:
+
+```tsx
+<ShopkitAnalytics
+  config={{
+    // ... other config
+    affiliate: {
+      enabled: true,
+      autoCapture: true,
+      config: {
+        utmParams: ["utm_source", "utm_medium", "utm_campaign"],
+        customParams: ["ref", "affiliate_id"],
+        storageKey: "affiliate_data",
+        expirationDays: 30,
+      },
+    },
+  }}
+/>
+```
+
+### Affiliate Hooks
+
+```tsx
+import { useAffiliateTracker, useHasAffiliateData } from "@shopkit/analytics";
+
+function MyComponent() {
+  const hasAffiliateData = useHasAffiliateData();
+  const affiliateSource = useAffiliateSource();
+
+  if (hasAffiliateData) {
+    console.log("Affiliate source:", affiliateSource);
+  }
+}
+```
+
+## 🛠️ Advanced Configuration
+
+### Custom Adapters
+
+Create your own analytics adapter:
+
+```tsx
+import { BaseAdapter } from "@shopkit/analytics";
+
+class CustomAdapter extends BaseAdapter {
+  public readonly name = "CustomAnalytics";
+
+  async initialize() {
+    this.initializeLogger();
+    // Initialize your analytics service
+    this.initialized = true;
+  }
+
+  async trackEvent(event) {
+    // Send event to your analytics service
+    this.logger.info("Custom tracking", { event });
+  }
+}
+
+// Use custom adapter
+<ShopkitAnalytics
+  config={{
+    customAdapters: [new CustomAdapter()],
+  }}
+/>
+```
+
+### Environment-Based Configuration
+
+```tsx
+const analyticsConfig = {
+  googleAnalytics: process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID
+    ? {
+        measurementId: process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID,
+      }
+    : undefined,
+  facebookPixel: process.env.NEXT_PUBLIC_FB_PIXEL_ID
+    ? {
+        pixelId: process.env.NEXT_PUBLIC_FB_PIXEL_ID,
+      }
+    : undefined,
+  logger: {
+    enabled: true,
+    level: process.env.NODE_ENV === "development" ? "debug" : "info",
+    prettyPrint: process.env.NODE_ENV === "development",
+  },
+};
+
+<ShopkitAnalytics config={analyticsConfig} />
+```
+
+## 🔧 API Reference
+
+### ShopkitAnalytics Props
+
+```tsx
+interface ShopkitAnalyticsProps {
+  config: ShopkitAnalyticsConfig;
+  children?: React.ReactNode;
+  onInitialized?: () => void;
+  onError?: (error: Error) => void;
+}
+```
+
+### Configuration Interface
+
+```tsx
+interface ShopkitAnalyticsConfig {
+  // Analytics Adapters
+  googleAnalytics?: GoogleAdapterConfig;
+  facebookPixel?: PixelAdapterConfig;
+  moengage?: MoengageAdapterConfig;
+  posthog?: PostHogAdapterConfig;
+  shopify?: ShopifyAdapterConfig;
+  kwikpass?: KwikPassConfig;
+  kwikcheckout?: KwikCheckoutConfig;
+  customAdapters?: TrackingAdapter[];
+
+  // Logging Configuration
+  logger?: {
+    enabled?: boolean;
+    level?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    prettyPrint?: boolean;
+    redact?: string[];
+    name?: string;
+  };
+
+  // Affiliate Tracking
+  affiliate?: {
+    enabled?: boolean;
+    config?: Partial<AffiliateConfig>;
+    autoCapture?: boolean;
+  };
+
+  // General Settings
+  enableDebugLogs?: boolean; // Deprecated: use logger.enabled
+  autoInitialize?: boolean;
+}
+```
+
+## 🚨 Important Notes
+
+### Requirements
+
+- React 16.8+ (for hooks support)
+- Modern browser with ES2020 support
+- Valid analytics account credentials
+
+### Best Practices
+
+1. **Environment Variables**: Store sensitive keys in environment variables
+2. **Logger Configuration**: Use appropriate log levels for production
+3. **Event Validation**: Ensure required event properties are provided
+4. **Performance**: Use selective adapter routing for high-traffic events
+5. **Privacy**: Implement proper consent management
+
+### Limitations
+
+- Some adapters may have rate limits
+- Event data size limits vary by platform
+- Real-time reporting availability depends on the platform
+
+## 📄 License
+
+MIT License - see LICENSE file for details.
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## 📞 Support
+
+For issues and questions:
+- Create an issue on GitHub
+- Check the documentation
+- Review the debug logs
+
+---
+
+**@shopkit/analytics** - Comprehensive analytics solution for modern e-commerce applications.