shopkit-analytics 1.0.0

package/dist/index-BnNRgdUv.d.ts

@@ -0,0 +1,676 @@
+import { TEvent } from './types.js';
+import { T as TrackingAdapter } from './subscriber-43gnCKWe.js';
+import { AnalyticsEventName, ShopifyAnalyticsProduct, ShopifyPageViewPayload } from '@shopify/hydrogen-react';
+
+/**
+ * Logger configuration options
+ */
+interface LoggerConfig {
+    level?: "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+    enabled?: boolean;
+    name?: string;
+    prettyPrint?: boolean;
+    redact?: string[];
+}
+/**
+ * Logger interface for consistent logging across adapters
+ */
+interface Logger {
+    trace: (message: string, ...args: any[]) => void;
+    debug: (message: string, ...args: any[]) => void;
+    info: (message: string, ...args: any[]) => void;
+    warn: (message: string, ...args: any[]) => void;
+    error: (message: string, error?: Error, ...args: any[]) => void;
+    fatal: (message: string, error?: Error, ...args: any[]) => void;
+    child: (bindings: Record<string, any>) => Logger;
+}
+/**
+ * Create a logger instance
+ */
+declare function createLogger(config?: LoggerConfig): Logger;
+/**
+ * Default logger instance
+ */
+declare const logger: Logger;
+/**
+ * Create adapter-specific logger
+ */
+declare function createAdapterLogger(adapterName: string, config?: LoggerConfig): Logger;
+
+/**
+ * Abstract base class for tracking adapters
+ */
+declare abstract class BaseAdapter implements TrackingAdapter {
+    /**
+     * Name of the tracking adapter
+     */
+    abstract readonly name: string;
+    /**
+     * Configuration for the adapter
+     */
+    protected config: Record<string, any>;
+    /**
+     * Logger instance for this adapter
+     */
+    protected logger: Logger;
+    /**
+     * Whether the adapter has been initialized
+     */
+    protected initialized: boolean;
+    /**
+     * Constructor
+     * @param config Configuration for the adapter
+     */
+    constructor(config?: Record<string, any>);
+    /**
+     * Initialize logger with proper adapter name
+     * Should be called by subclasses after name is available
+     */
+    protected initializeLogger(): void;
+    /**
+     * Check if the adapter is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Initialize the adapter
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Track an event
+     * @param event The event to track
+     */
+    abstract trackEvent(event: TEvent): Promise<void>;
+    /**
+     * Get a configuration value
+     * @param key The configuration key
+     * @param defaultValue The default value if the key is not found
+     */
+    protected getConfig<T>(key: string, defaultValue?: T): T;
+    /**
+     * Get affiliate parameters from session storage or custom implementation
+     * Override this method to provide your own affiliate tracking implementation
+     * @returns Affiliate parameters or null if not available
+     */
+    protected getAffiliateParams(): Record<string, string> | null;
+    /**
+     * Enhance event parameters with affiliate data
+     * @param params The original parameters
+     * @returns Parameters enhanced with affiliate data
+     */
+    protected enhanceWithAffiliateParams(params: Record<string, any>): Record<string, any>;
+}
+
+declare global {
+    interface Window {
+        fbq?: (type: string, eventName: string, params?: Record<string, any>) => void;
+    }
+}
+/**
+ * Configuration for the Facebook Pixel adapter
+ */
+interface PixelAdapterConfig {
+    /**
+     * Facebook Pixel ID
+     */
+    pixelId: string;
+}
+/**
+ * Facebook Pixel tracking adapter
+ * Assumes that the Facebook Pixel script is already loaded in the page
+ */
+declare class PixelAdapter extends BaseAdapter {
+    readonly name = "FacebookPixel";
+    constructor(config: PixelAdapterConfig);
+    /**
+     * Initialize the Facebook Pixel
+     */
+    initialize(): Promise<void>;
+    /**
+     * Track an event with Facebook Pixel
+     * @param event The event to track
+     */
+    trackEvent(event: TEvent): Promise<void>;
+    /**
+     * Track a page view event
+     * @param event The page view event
+     */
+    private trackPageView;
+    /**
+     * Track a product view event
+     * @param event The product view event
+     */
+    private trackProductView;
+    /**
+     * Track an add to cart event
+     * @param event The add to cart event
+     */
+    private trackAddToCart;
+    /**
+     * Track a checkout started event
+     * @param event The checkout started event
+     */
+    private trackCheckoutStarted;
+    /**
+     * Track a checkout completed event
+     * @param event The checkout completed event
+     */
+    private trackCheckoutCompleted;
+    /**
+     * Track a search event
+     * @param event The search event
+     */
+    private trackSearch;
+    /**
+     * Track an add payment info event
+     * @param event The add payment info event
+     */
+    private trackAddPaymentInfo;
+    /**
+     * Track a view content event
+     * @param event The view content event
+     */
+    private trackViewContent;
+    /**
+     * Track a purchase event
+     * @param event The purchase event
+     */
+    private trackPurchase;
+    /**
+     * Convert an event to Facebook Pixel parameters
+     * @param event The event to convert
+     */
+    private eventToParams;
+}
+
+declare global {
+    interface Window {
+        gtag?: (...args: any[]) => void;
+    }
+}
+/**
+ * Configuration for the Google Analytics adapter
+ */
+interface GoogleAdapterConfig {
+    /**
+     * Google Analytics measurement ID (e.g., G-XXXXXXXXXX)
+     */
+    measurementId: string;
+}
+/**
+ * Google Analytics tracking adapter
+ * Assumes that the Google Analytics script is already loaded in the page
+ */
+declare class GoogleAdapter extends BaseAdapter {
+    readonly name = "GoogleAnalytics";
+    constructor(config: GoogleAdapterConfig);
+    /**
+     * Initialize Google Analytics adapter
+     * This just checks if gtag is available
+     */
+    isEnabled(): boolean;
+    initialize(): Promise<void>;
+    /**
+     * Track an event with Google Analytics
+     * @param event The event to track
+     */
+    trackEvent(event: TEvent): Promise<void>;
+    /**
+     * Track a page view event
+     * @param event The page view event
+     * @param measurementId The Google Analytics measurement ID
+     */
+    private trackPageView;
+    private trackUserEngagement;
+    private trackSessionStart;
+    private trackFirstVisit;
+    private trackViewItem;
+    private trackScroll;
+    private trackCheckoutPayment;
+    private trackViewedProduct;
+    private trackAddToCart;
+    private trackFormStart;
+    private trackCheckoutStarted;
+    private trackFormSubmission;
+    private trackSearch;
+    /**
+     * Track a checkout completed event
+     * @param event The checkout completed event
+     */
+    private trackCheckoutCompleted;
+    /**
+     * Track a custom event
+     * @param event The custom event
+     */
+    private trackCustomEvent;
+    /**
+     * Track an add payment info event
+     * @param event The add payment info event
+     */
+    private trackAddPaymentInfo;
+    /**
+     * Track a view content event
+     * @param event The view content event
+     */
+    private trackViewContent;
+    /**
+     * Track a purchase event
+     * @param event The purchase event
+     */
+    private trackPurchase;
+    /**
+     * Track a view search results event
+     * @param event The view search results event
+     */
+    private trackViewSearchResults;
+    /**
+     * Track an order placed event
+     * @param event The order placed event
+     */
+    private trackOrderPlaced;
+    /**
+     * Track a begin checkout event
+     * @param event The begin checkout event
+     */
+    private trackBeginCheckout;
+    /**
+     * Convert an event to Google Analytics parameters
+     * @param event The event to convert
+     */
+    private eventToParams;
+}
+
+/**
+ * Configuration for the MoenGage adapter
+ */
+interface MoengageAdapterConfig {
+    /**
+     * MoenGage App ID (required for SDK initialization)
+     */
+    appId: string;
+    /**
+     * Whether to enable user identification
+     */
+    enableUserIdentification?: boolean;
+    /**
+     * Debug mode for MoenGage SDK
+     */
+    debug?: boolean;
+    /**
+     * Data center region (default: 'dc_01')
+     */
+    region?: string;
+}
+/**
+ * MoenGage tracking adapter using the official Web SDK
+ */
+declare class MoengageAdapter extends BaseAdapter {
+    readonly name = "MoEngage";
+    private sdk;
+    constructor(config: MoengageAdapterConfig);
+    /**
+     * Initialize the MoenGage adapter using the Web SDK
+     */
+    initialize(): Promise<void>;
+    /**
+     * Track an event with MoenGage SDK
+     * @param event The event to track
+     */
+    trackEvent(event: TEvent): Promise<void>;
+    /**
+     * Track a page view event
+     * @param event The page view event
+     */
+    private trackPageView;
+    /**
+     * Track a button click event
+     * @param event The button click event
+     */
+    private trackButtonClick;
+    /**
+     * Track a form submission event
+     * @param event The form submission event
+     */
+    private trackFormSubmission;
+    /**
+     * Track a product view event
+     * @param event The product view event
+     */
+    private trackProductView;
+    /**
+     * Track an add to cart event
+     * @param event The add to cart event
+     */
+    private trackAddToCart;
+    /**
+     * Track a remove from cart event
+     * @param event The remove from cart event
+     */
+    private trackRemoveFromCart;
+    /**
+     * Track a checkout started event
+     * @param event The checkout started event
+     */
+    private trackCheckoutStarted;
+    /**
+     * Track a checkout completed event
+     * @param event The checkout completed event
+     */
+    private trackCheckoutCompleted;
+    /**
+     * Track a search event
+     * @param event The search event
+     */
+    private trackSearch;
+    /**
+     * Track a user signup event
+     * @param event The user signup event
+     */
+    private trackUserSignup;
+    /**
+     * Track a user login event
+     * @param event The user login event
+     */
+    private trackUserLogin;
+    /**
+     * Track a custom event
+     * @param event The custom event
+     */
+    private trackCustomEvent;
+    /**
+     * Convert an event to MoenGage parameters
+     * @param event The event to convert
+     */
+    private eventToParams;
+    /**
+     * Set user attributes in MoenGage
+     * @param attributes User attributes to set
+     */
+    setUserAttributes(attributes: Record<string, any>): void;
+}
+
+declare global {
+    interface Window {
+        posthog?: {
+            capture: (eventName: string, properties?: Record<string, any>) => void;
+            identify: (distinctId: string, properties?: Record<string, any>) => void;
+        };
+    }
+}
+/**
+ * Configuration for the PostHog adapter
+ */
+interface PostHogAdapterConfig {
+    /**
+     * Enable debug logs
+     */
+    enableDebugLogs?: boolean;
+}
+/**
+ * PostHog tracking adapter
+ * Assumes that the PostHog script is already loaded in the page
+ */
+declare class PostHogAdapter extends BaseAdapter {
+    readonly name = "PostHog";
+    constructor(config?: PostHogAdapterConfig);
+    /**
+     * Initialize PostHog
+     */
+    initialize(): Promise<void>;
+    /**
+     * Track an event with PostHog
+     * @param event The event to track
+     */
+    trackEvent(event: TEvent): Promise<void>;
+    /**
+     * Track a page view event
+     * @param event The page view event
+     */
+    private trackPageView;
+    /**
+     * Track a product view event
+     * @param event The product view event
+     */
+    private trackProductView;
+    /**
+     * Track an add to cart event
+     * @param event The add to cart event
+     */
+    private trackAddToCart;
+    /**
+     * Track a checkout started event
+     * @param event The checkout started event
+     */
+    private trackCheckoutStarted;
+    /**
+     * Track a checkout completed event
+     * @param event The checkout completed event
+     */
+    private trackCheckoutCompleted;
+    /**
+     * Track a search event
+     * @param event The search event
+     */
+    private trackSearch;
+    /**
+     * Track an add payment info event
+     * @param event The add payment info event
+     */
+    private trackAddPaymentInfo;
+    /**
+     * Convert an event to PostHog parameters
+     * @param event The event to convert
+     */
+    private eventToParams;
+}
+
+/**
+ * Type definitions for analytics payloads
+ */
+type SendPageViewPayload = {
+    pageType?: string;
+    products?: ShopifyAnalyticsProduct[];
+    collectionHandle?: string;
+    searchString?: string;
+    totalValue?: number;
+    cartId?: string;
+};
+type SendAddToCartPayload = {
+    cartId: string;
+    products?: ShopifyAnalyticsProduct[];
+    totalValue?: ShopifyPageViewPayload["totalValue"];
+};
+/**
+ * Configuration interface for Shopify Analytics Adapter
+ */
+interface ShopifyAdapterConfig {
+    shopId: string;
+    domain: string;
+    currency?: string;
+}
+/**
+ * Shopify Analytics Adapter for tracking events to Shopify Admin Analytics
+ */
+declare class ShopifyAdapter extends BaseAdapter {
+    readonly name = "ShopifyAnalytics";
+    private shopId;
+    private domain;
+    private currency;
+    constructor(config: ShopifyAdapterConfig);
+    /**
+     * Initialize the Shopify Analytics adapter
+     */
+    initialize(): Promise<void>;
+    /**
+     * Convert product ID to Shopify GID format if it's not already
+     */
+    private formatProductGid;
+    /**
+     * Get user consent status from your consent management system
+     */
+    private getUserConsent;
+    /**
+     * Check user consent (implement based on your consent management)
+     */
+    private checkUserConsent;
+    private checkAnalyticsConsent;
+    private checkMarketingConsent;
+    private checkSaleOfDataConsent;
+    /**
+     * Create base payload for all events
+     */
+    private createBasePayload;
+    /**
+     * Send page view event using the enhanced functionality
+     */
+    sendPageView: (eventName: keyof typeof AnalyticsEventName, payload?: SendPageViewPayload) => Promise<void>;
+    /**
+     * Send add to cart event using the enhanced functionality
+     */
+    sendAddToCart: ({ cartId, totalValue, products, }: SendAddToCartPayload) => Promise<void>;
+    /**
+     * Track an event using Shopify Analytics
+     */
+    trackEvent(event: TEvent): Promise<void>;
+    /**
+     * Check if Shopify session is properly established
+     */
+    isSessionValid(): boolean;
+    /**
+     * Get session debug information
+     */
+    getSessionDebugInfo(): object;
+    /**
+     * Track add to cart event with enhanced error handling
+     */
+    private trackAddToCart;
+}
+
+/**
+ * Configuration interface for KwikPass Adapter
+ */
+interface KwikPassConfig {
+    enableDebugLogs?: boolean;
+    enableKwikPassEvents?: boolean;
+}
+/**
+ * KwikPass Analytics Adapter for tracking events to KwikPass platform
+ */
+declare class KwikPassAdapter extends BaseAdapter {
+    readonly name = "KwikPass";
+    private enableKwikPassEvents;
+    constructor(config?: KwikPassConfig);
+    /**
+     * Initialize the KwikPass adapter
+     */
+    initialize(): Promise<void>;
+    /**
+     * Track an event using KwikPass
+     */
+    trackEvent(event: TEvent): Promise<void>;
+    /**
+     * Send event to KwikPass platform
+     */
+    private sendKwikPassEvent;
+    /**
+     * Track product view event
+     */
+    private trackCollectionView;
+    /**
+     * Track collection view event
+     */
+    private trackProductView;
+    /**
+     * Track page view event
+     */
+    private trackPageView;
+}
+
+/**
+ * Configuration interface for Kwik Checkout Adapter
+ */
+interface KwikCheckoutConfig {
+    mid?: string;
+    environment?: string;
+    storeId?: string;
+    enableDebugLogs?: boolean;
+}
+/**
+ * Kwik Checkout Analytics Adapter for tracking checkout events to GoKwik platform
+ */
+declare class KwikCheckoutAdapter extends BaseAdapter {
+    readonly name = "KwikCheckout";
+    private mid;
+    private environment;
+    private storeId;
+    constructor(config: KwikCheckoutConfig);
+    /**
+     * Initialize the GoKwik adapter
+     */
+    initialize(): Promise<void>;
+    /**
+     * Track an event using GoKwik
+     */
+    trackEvent(event: TEvent): Promise<void>;
+    /**
+     * Send event to GoKwik platform
+     */
+    private sendGoKwikEvent;
+    /**
+     * Track started checkout GK event
+     */
+    private trackStartedCheckoutGK;
+    /**
+     * Track mobile added GK event
+     */
+    private trackMobileAddedGK;
+    /**
+     * Track address selected GK event
+     */
+    private trackAddressSelectedGK;
+    /**
+     * Track address completed GK event
+     */
+    private trackAddressCompletedGK;
+    /**
+     * Track address added GK event
+     */
+    private trackAddressAddedGK;
+    /**
+     * Track PIN code added GK event
+     */
+    private trackPinCodeAddedGK;
+    /**
+     * Track payment method selected GK event
+     */
+    private trackPaymentMethodSelectedGK;
+    /**
+     * Track payment completed GK event
+     */
+    private trackPaymentCompletedGK;
+    /**
+     * Track order success event
+     */
+    private trackOrderSuccess;
+    /**
+     * Track order completed event
+     */
+    private trackOrderCompleted;
+    /**
+     * Track cart viewed event
+     */
+    private trackCartViewed;
+    /**
+     * Track checkout started event
+     */
+    private trackCheckoutStarted;
+    /**
+     * Track checkout completed event
+     */
+    private trackCheckoutCompleted;
+    /**
+     * Track add payment info event
+     */
+    private trackAddPaymentInfo;
+}
+
+export { BaseAdapter as B, type GoogleAdapterConfig as G, type KwikPassConfig as K, type LoggerConfig as L, type MoengageAdapterConfig as M, type PixelAdapterConfig as P, type ShopifyAdapterConfig as S, type PostHogAdapterConfig as a, type KwikCheckoutConfig as b, PixelAdapter as c, GoogleAdapter as d, MoengageAdapter as e, PostHogAdapter as f, ShopifyAdapter as g, KwikPassAdapter as h, KwikCheckoutAdapter as i, type Logger as j, createLogger as k, logger as l, createAdapterLogger as m };