dishub-analytics.sdk 1.1.0

package/README.md

@@ -0,0 +1,82 @@
+# dishub-analytics.sdk
+
+The official tracking SDK for Dishub Analytics. Lightweight, TypeScript-first, and optimized for real-time performance.
+
+## 🚀 Features
+
+- **Real-time Tracking**: Sub-second event reporting.
+- **Proactive Disconnect**: Automatic session cleanup using `keepalive` beacons.
+- **Smart Heartbeats**: Monitors tab visibility to ensure accuracy.
+- **Identity Support**: Link sessions to authenticated users.
+- **React Ready**: Includes a built-in `AnalyticsProvider` and `useAnalytics` hook.
+
+## 📦 Installation
+
+```bash
+npm install dishub-analytics.sdk
+```
+
+## 🛠️ Usage
+
+### Vanilla JavaScript
+
+```javascript
+import { AnalyticsClient } from 'dishub-analytics.sdk';
+
+const analytics = new AnalyticsClient({
+  apiKey: 'YOUR_API_KEY',
+  endpoint: 'https://dishubanalitics-production.up.railway.app/api/v1',
+  trackClicks: true,
+  trackHeartbeat: true
+});
+
+// Initialize session
+await analytics.init();
+
+// Track custom events
+analytics.trackEvent('purchase_completed', 'ecommerce', { amount: 99.99 });
+
+// Identify user
+analytics.identify('user_123', 'John Doe');
+```
+
+### React / Next.js
+
+Wrap your application with the `AnalyticsProvider`:
+
+```tsx
+import { AnalyticsProvider } from 'dishub-analytics.sdk';
+
+function App() {
+  return (
+    <AnalyticsProvider 
+      apiKey="YOUR_API_KEY"
+      endpoint="https://analytics-api.example.com"
+      config={{ trackClicks: true }}
+    >
+      <MyRoutes />
+    </AnalyticsProvider>
+  );
+}
+```
+
+Use the hook in your components:
+
+```tsx
+import { useAnalytics } from 'dishub-analytics.sdk';
+
+function CheckoutButton() {
+  const { trackEvent, identify } = useAnalytics();
+
+  const handleCheckout = async () => {
+    trackEvent('checkout_clicked');
+    // ...
+  };
+
+  return <button onClick={handleCheckout}>Checkout</button>;
+}
+```
+
+## 📄 License
+
+MIT © [Dishub](https://dishub.city)

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+import { AnalyticsConfig } from './types';
+export declare class AnalyticsClient {
+    private config;
+    private visitorId;
+    private sessionId;
+    private heartbeatInterval;
+    constructor(config: AnalyticsConfig);
+    getVisitorId(): string | null;
+    getSessionId(): string | null;
+    init(): Promise<void>;
+    identify(userId: string, name?: string): Promise<void>;
+    private request;
+    private trackSession;
+    trackEvent(name: string, category?: string, value?: string, metadata?: Record<string, any>): Promise<void>;
+    trackPageView(path?: string, title?: string): Promise<void>;
+    private startHeartbeat;
+    private setupDisconnectListeners;
+    disconnect(): Promise<void>;
+    private setupClickTracking;
+    trackInteraction(type: string, element: string, x?: number, y?: number, metadata?: Record<string, any>): Promise<void>;
+    private setupInteractionTracking;
+    private getSelector;
+    private getDeviceType;
+    private getBrowser;
+    private getOS;
+    private getSegment;
+    private getUtmParam;
+    private generateId;
+    destroy(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import React from 'react';
+
+interface AnalyticsConfig {
+    apiKey: string;
+    endpoint: string;
+    trackPageViews?: boolean;
+    trackClicks?: boolean;
+    trackHeartbeat?: boolean;
+    heartbeatInterval?: number;
+    excludePaths?: string[];
+    segment?: string;
+    externalUserId?: string;
+    externalUserName?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+}
+interface TrackEventOptions {
+    name: string;
+    category?: string;
+    value?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AnalyticsContext {
+    trackEvent: (name: string, category?: string, value?: string, metadata?: Record<string, unknown>) => Promise<void>;
+    trackInteraction: (type: string, element: string, x?: number, y?: number, metadata?: Record<string, unknown>) => Promise<void>;
+    identify: (userId: string, name?: string) => Promise<void>;
+    sessionId: string | null;
+    visitorId: string | null;
+}
+
+declare class AnalyticsClient {
+    private config;
+    private visitorId;
+    private sessionId;
+    private heartbeatInterval;
+    constructor(config: AnalyticsConfig);
+    getVisitorId(): string | null;
+    getSessionId(): string | null;
+    init(): Promise<void>;
+    identify(userId: string, name?: string): Promise<void>;
+    private request;
+    private trackSession;
+    trackEvent(name: string, category?: string, value?: string, metadata?: Record<string, any>): Promise<void>;
+    trackPageView(path?: string, title?: string): Promise<void>;
+    private startHeartbeat;
+    private setupDisconnectListeners;
+    disconnect(): Promise<void>;
+    private setupClickTracking;
+    trackInteraction(type: string, element: string, x?: number, y?: number, metadata?: Record<string, any>): Promise<void>;
+    private setupInteractionTracking;
+    private getSelector;
+    private getDeviceType;
+    private getBrowser;
+    private getOS;
+    private getSegment;
+    private getUtmParam;
+    private generateId;
+    destroy(): void;
+}
+
+interface AnalyticsProviderProps {
+    children: React.ReactNode;
+    apiKey: string;
+    endpoint: string;
+    config?: Partial<AnalyticsConfig>;
+}
+declare function AnalyticsProvider({ children, apiKey, endpoint, config }: AnalyticsProviderProps): React.JSX.Element;
+declare function useAnalytics(): AnalyticsContext;
+
+export { AnalyticsClient, AnalyticsProvider, useAnalytics };
+export type { AnalyticsConfig, AnalyticsContext, AnalyticsProviderProps, TrackEventOptions };