flowgrid-sdk 1.1.0 → 1.2.1

package/dist/lib/client/transport.d.ts

@@ -0,0 +1,175 @@
+import { IdentityManager } from '../utils/identity';
+export type ConsentCategory = 'analytics' | 'marketing';
+export type BotDetectionMode = 'block' | 'tag' | 'disabled';
+export interface FlowGridTransportConfig {
+    /** Bot detection mode: 'block' skips events, 'tag' adds _bot flag, 'disabled' sends all */
+    botDetection?: BotDetectionMode;
+    /** Respect navigator.doNotTrack / globalPrivacyControl (default true) */
+    respectDNT?: boolean;
+    /** Global sampling rate 0.0–1.0 (default 1.0 = send everything) */
+    sampleRate?: number;
+}
+/**
+ * SDK Feature Types
+ */
+export type FeatureType = "engagement" | "cohorts" | "churn" | "monetization" | "multi_path_funnels" | "support" | "acquisition" | "paths" | "alerts" | "security" | "forecasting";
+/**
+ * FlowGridTransport — Unified transport layer for Flowgrid SDK.
+ *
+ * @description
+ * Provides a secure, validated RPC-style transport layer used by all SDK modules.
+ * Handles:
+ * - Input validation
+ * - Payload size enforcement
+ * - Timeout handling
+ * - Retry logic (network failures only)
+ * - Authorization headers
+ * - Feature-scoped endpoint routing
+ *
+ * This class is designed to be extended by higher-level modules
+ * (e.g., Analytics, Experiments, Engagement, Cohorts).
+ *
+ * @example
+ * ```ts
+ * const client = new FlowGridTransport("web_123", "api.flowgrid.com", "sk_live_xxx");
+ * ```
+ */
+export declare class FlowGridTransport {
+    /**
+     * Unique Web ID identifying the site or application.
+     * Used by the backend to associate incoming events.
+     */
+    protected webId: string;
+    /**
+     * Base API endpoint.
+     * Example values:
+     * - "api.flowgrid.com"
+     * - "https://api.flowgrid.com"
+     *
+     * Protocol is normalized automatically.
+     */
+    protected endpoint: string;
+    /**
+     * Private API key used for authenticating requests.
+     * Sent as a Bearer token in the Authorization header.
+     */
+    private apiKey;
+    /**
+     * Visitor ID for cross-session visitor tracking.
+     * Persisted per-visitor (cookie/localStorage) and sent with every event.
+     */
+    protected visitorId: string;
+    /**
+     * Optional identity manager that owns the visitor/session lifecycle.
+     * When provided, visitor_id is resolved at call time (not construction time).
+     */
+    protected identityManager?: IdentityManager;
+    /**
+     * Maximum allowed payload size (in bytes).
+     * Prevents oversized event submissions.
+     */
+    private static readonly MAX_PAYLOAD_SIZE;
+    /**
+     * Maximum time (ms) before request is aborted.
+     */
+    private static readonly TIMEOUT_MS;
+    /**
+     * Maximum retry attempts for network-level failures and 5xx server errors.
+     */
+    private static readonly MAX_RETRIES;
+    /** Max events to persist in localStorage buffer */
+    private static readonly MAX_BUFFER_EVENTS;
+    /** Max buffer size in bytes */
+    private static readonly MAX_BUFFER_SIZE;
+    /** localStorage key for failed event buffer */
+    private static readonly EVENT_BUFFER_KEY;
+    /** Consent state */
+    private static consent;
+    /** Transport config */
+    protected transportConfig: FlowGridTransportConfig;
+    /**
+     * Creates a new FlowGridTransport instance.
+     *
+     * @param webId - Unique identifier for the web property.
+     * @param endpoint - API base endpoint.
+     * @param apiKey - Private API key for authentication.
+     * @param visitorId - Optional visitor ID for cross-session tracking.
+     *
+     * @throws {Error} If required parameters are missing.
+     */
+    constructor(webId: string, endpoint: string, apiKey: string, visitorId?: string, identityManager?: IdentityManager, config?: FlowGridTransportConfig);
+    static setConsent(consent: Partial<Record<ConsentCategory, boolean>>): void;
+    static hasConsent(category: ConsentCategory): boolean;
+    private static isLikelyBot;
+    private isDNTEnabled;
+    private static getDeviceContext;
+    /**
+     * Fire-and-forget event via sendBeacon. Used for page unload events.
+     */
+    sendViaBeacon(eventName: string, properties?: Record<string, any>): boolean;
+    private bufferEvent;
+    private drainEventBuffer;
+    /**
+     * Core RPC transport method for standard SDK calls.
+     *
+     * @template T Expected JSON response type.
+     *
+     * @param eventName - Logical event or function name.
+     * @param properties - Arbitrary event payload properties.
+     * @param method - HTTP method ("GET", "POST", "PATCH").
+     *
+     * @returns Promise resolving to typed response.
+     */
+    protected init<T>(eventName: string, properties?: Record<string, any>, method?: "GET" | "POST" | "PATCH"): Promise<T>;
+    /**
+     * Feature-scoped RPC transport method.
+     * Routes to the SDK API endpoint with a feature type qualifier.
+     *
+     * @param eventName - Name of the event to track.
+     * @param properties - Additional properties to send (must include type).
+     */
+    protected initFeature<T>(eventName: string, properties: Record<string, any> & {
+        type: FeatureType;
+    }): Promise<T>;
+    /**
+     * Executes HTTP request with timeout and retry handling.
+     *
+     * @template T Expected response type.
+     *
+     * @param url - Fully constructed request URL.
+     * @param method - HTTP method.
+     * @param body - Optional JSON body (POST/PATCH only).
+     * @param extraHeaders - Additional headers to include.
+     *
+     * @throws {Error} On timeout, network failure, or non-OK HTTP status.
+     */
+    private executeRequest;
+    /**
+     * Exponential backoff: 1s, 2s, 4s ...
+     */
+    private backoff;
+    /**
+     * Validates event name and payload.
+     *
+     * @param eventName - Event identifier.
+     * @param properties - Associated event properties.
+     *
+     * @throws {Error} If validation fails.
+     */
+    private validateInput;
+    /**
+     * Normalizes endpoint input.
+     * Ensures protocol is present and removes trailing slashes.
+     *
+     * @param endpoint - Raw endpoint string.
+     * @returns Normalized endpoint URL.
+     */
+    private normalizeEndpoint;
+    /**
+     * Safely reads response text without throwing.
+     *
+     * @param res - Fetch Response object.
+     * @returns Response text or empty string.
+     */
+    private safeRead;
+}

package/dist/lib/consent/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview FlowGrid Consent Management Module
+ * @module consent
+ *
+ * @description
+ * Cookie consent management for GDPR, CCPA, and ePrivacy compliance.
+ * Provides a framework-agnostic {@link ConsentManager} and types for
+ * building customisable cookie banner components.
+ *
+ * ## Quick Start
+ *
+ * ```ts
+ * import { ConsentManager, FlowGridTransport } from 'flowgrid-sdk';
+ *
+ * const consent = new ConsentManager({
+ *   onChange: (prefs) => {
+ *     FlowGridTransport.setConsent({
+ *       analytics: prefs.analytics,
+ *       marketing: prefs.marketing,
+ *     });
+ *   },
+ * });
+ *
+ * if (!consent.hasConsented()) {
+ *   // Show your cookie banner
+ * }
+ * ```
+ *
+ * ## Framework Components
+ *
+ * - **React / Next.js**: `import { CookieBanner } from 'flowgrid-sdk/react'`
+ * - **Vue / Nuxt**: `import { CookieBanner } from 'flowgrid-sdk/vue'`
+ *
+ * @see {@link ConsentManager} for the core API.
+ */
+export { ConsentManager } from './manager';
+export type { ConsentCategory, ConsentPreferences, ConsentConfig, ConsentChangeEvent, CookieBannerConfig, CookieBannerTheme, } from './types';

package/dist/lib/consent/manager.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @fileoverview FlowGrid Consent Manager
+ * @module consent/manager
+ *
+ * @description
+ * Framework-agnostic consent manager that stores user cookie preferences,
+ * integrates with the FlowGrid transport layer's consent gates, and
+ * respects DNT / GPC signals.
+ *
+ * The consent manager uses a single cookie (`fg_consent` by default) to
+ * persist the user's per-category choices. It exposes a simple API that
+ * framework-specific cookie banner components can wrap.
+ *
+ * @example
+ * ```ts
+ * import { ConsentManager } from 'flowgrid-sdk';
+ * import { FlowGridTransport } from 'flowgrid-sdk';
+ *
+ * const consent = new ConsentManager({
+ *   onChange: (prefs) => {
+ *     // Sync with FlowGrid transport consent gates
+ *     FlowGridTransport.setConsent({
+ *       analytics: prefs.analytics,
+ *       marketing: prefs.marketing,
+ *     });
+ *   },
+ * });
+ *
+ * // Check if user has already consented
+ * if (!consent.hasConsented()) {
+ *   showCookieBanner();
+ * }
+ *
+ * // Accept all
+ * consent.acceptAll();
+ *
+ * // Or reject non-essential
+ * consent.rejectNonEssential();
+ *
+ * // Or update individual categories
+ * consent.update({ analytics: true, marketing: false, preferences: true });
+ *
+ * // Read current state
+ * const prefs = consent.getPreferences();
+ * console.log(prefs.analytics); // true
+ * ```
+ */
+import type { ConsentConfig, ConsentPreferences } from './types';
+/**
+ * Manages cookie consent state for GDPR/CCPA compliance.
+ *
+ * Stores the user's per-category consent choices in a single cookie and
+ * provides methods to accept, reject, or customise preferences. Integrates
+ * with the FlowGrid transport layer via the `onChange` callback.
+ *
+ * @example
+ * ```ts
+ * import { ConsentManager, FlowGridTransport } from 'flowgrid-sdk';
+ *
+ * const consent = new ConsentManager({
+ *   onChange: (prefs) => {
+ *     FlowGridTransport.setConsent({
+ *       analytics: prefs.analytics,
+ *       marketing: prefs.marketing,
+ *     });
+ *   },
+ * });
+ *
+ * // In your cookie banner "Accept All" handler:
+ * consent.acceptAll();
+ *
+ * // In your "Reject All" handler:
+ * consent.rejectNonEssential();
+ *
+ * // In your "Save Preferences" handler:
+ * consent.update({ analytics: true, marketing: false, preferences: true });
+ * ```
+ */
+export declare class ConsentManager {
+    private config;
+    private preferences;
+    /**
+     * Create a new ConsentManager.
+     *
+     * @param config - Consent configuration options.
+     *
+     * @example
+     * ```ts
+     * const consent = new ConsentManager({
+     *   cookieName: 'my_app_consent',
+     *   cookieDays: 180,
+     *   respectDNT: true,
+     *   requireExplicitConsent: true,
+     *   onChange: (prefs) => {
+     *     console.log('Consent changed:', prefs);
+     *   },
+     * });
+     * ```
+     */
+    constructor(config?: ConsentConfig);
+    /**
+     * Check if the user has previously given consent (cookie exists).
+     *
+     * @returns `true` if the consent cookie exists, `false` otherwise.
+     *
+     * @example
+     * ```ts
+     * if (!consent.hasConsented()) {
+     *   showCookieBanner();
+     * }
+     * ```
+     */
+    hasConsented(): boolean;
+    /**
+     * Get the current consent preferences.
+     *
+     * @returns A copy of the current {@link ConsentPreferences}.
+     *
+     * @example
+     * ```ts
+     * const prefs = consent.getPreferences();
+     * if (prefs.analytics) {
+     *   initAnalytics();
+     * }
+     * ```
+     */
+    getPreferences(): ConsentPreferences;
+    /**
+     * Check if a specific consent category is enabled.
+     *
+     * @param category - The category to check.
+     * @returns `true` if the category is consented to.
+     *
+     * @example
+     * ```ts
+     * if (consent.hasCategory('marketing')) {
+     *   loadMarketingPixels();
+     * }
+     * ```
+     */
+    hasCategory(category: keyof ConsentPreferences): boolean;
+    /**
+     * Accept all consent categories.
+     *
+     * @example
+     * ```ts
+     * // "Accept All" button handler
+     * document.getElementById('accept-all')?.addEventListener('click', () => {
+     *   consent.acceptAll();
+     * });
+     * ```
+     */
+    acceptAll(): void;
+    /**
+     * Reject all non-essential categories.
+     * Only `necessary` remains enabled.
+     *
+     * @example
+     * ```ts
+     * // "Reject All" button handler
+     * consent.rejectNonEssential();
+     * ```
+     */
+    rejectNonEssential(): void;
+    /**
+     * Update individual consent categories.
+     *
+     * @param updates - Partial preferences to merge.
+     *
+     * @example
+     * ```ts
+     * // "Save Preferences" handler
+     * consent.update({
+     *   analytics: true,
+     *   marketing: false,
+     *   preferences: true,
+     * });
+     * ```
+     */
+    update(updates: Partial<Omit<ConsentPreferences, 'necessary'>>): void;
+    /**
+     * Reset consent — removes the cookie and restores defaults.
+     * The cookie banner should be shown again after this.
+     *
+     * @example
+     * ```ts
+     * // "Reset Cookies" link
+     * consent.reset();
+     * ```
+     */
+    reset(): void;
+    private setPreferences;
+    private isDNTEnabled;
+    private loadFromCookie;
+    private saveToCookie;
+    private deleteCookie;
+}

package/dist/lib/consent/types.d.ts

@@ -0,0 +1,162 @@
+/**
+ * @fileoverview FlowGrid Consent Management — Types
+ * @module consent/types
+ *
+ * @description
+ * Types for cookie consent management, GDPR/CCPA compliance,
+ * and customizable cookie banner configuration.
+ */
+/**
+ * Consent categories that can be individually toggled.
+ *
+ * - `necessary` — Always enabled; cannot be declined (session, security).
+ * - `analytics` — Page views, sessions, funnels, heatmaps.
+ * - `marketing` — UTM tracking, attribution, retargeting pixels.
+ * - `preferences` — UI preferences, locale, theme stored in cookies.
+ */
+export type ConsentCategory = 'necessary' | 'analytics' | 'marketing' | 'preferences';
+/**
+ * User's consent choices per category.
+ *
+ * @example
+ * ```ts
+ * const prefs: ConsentPreferences = {
+ *   necessary: true,    // always true
+ *   analytics: true,
+ *   marketing: false,
+ *   preferences: true,
+ * };
+ * ```
+ */
+export interface ConsentPreferences {
+    necessary: true;
+    analytics: boolean;
+    marketing: boolean;
+    preferences: boolean;
+}
+/**
+ * Configuration for the {@link ConsentManager}.
+ *
+ * @example
+ * ```ts
+ * import { ConsentManager } from 'flowgrid-sdk';
+ *
+ * const consent = new ConsentManager({
+ *   cookieName: 'fg_consent',
+ *   cookieDays: 365,
+ *   defaultPreferences: {
+ *     necessary: true,
+ *     analytics: false,
+ *     marketing: false,
+ *     preferences: true,
+ *   },
+ *   onChange: (prefs) => {
+ *     console.log('Consent updated:', prefs);
+ *   },
+ * });
+ * ```
+ */
+export interface ConsentConfig {
+    /** Cookie name to store consent state. Defaults to `"fg_consent"`. */
+    cookieName?: string;
+    /** Days until the consent cookie expires. Defaults to `365`. */
+    cookieDays?: number;
+    /** Cookie domain (e.g. `.example.com`). Defaults to current domain. */
+    cookieDomain?: string;
+    /** Default consent state before the user makes a choice. */
+    defaultPreferences?: Partial<ConsentPreferences>;
+    /** Called whenever consent preferences change. */
+    onChange?: (preferences: ConsentPreferences) => void;
+    /** Respect `navigator.doNotTrack` / `globalPrivacyControl`. Defaults to `true`. */
+    respectDNT?: boolean;
+    /** Auto-block analytics/marketing before consent is given. Defaults to `true`. */
+    requireExplicitConsent?: boolean;
+}
+/**
+ * Event emitted when consent changes.
+ */
+export interface ConsentChangeEvent {
+    /** Previous consent state (null if first interaction). */
+    previous: ConsentPreferences | null;
+    /** New consent state. */
+    current: ConsentPreferences;
+    /** Timestamp of the change. */
+    timestamp: string;
+}
+/**
+ * Theme / appearance configuration for the cookie banner component.
+ *
+ * @example
+ * ```ts
+ * const theme: CookieBannerTheme = {
+ *   position: 'bottom',
+ *   primaryColor: '#4F46E5',
+ *   backgroundColor: '#FFFFFF',
+ *   textColor: '#1F2937',
+ *   borderRadius: '8px',
+ *   fontFamily: 'Inter, system-ui, sans-serif',
+ * };
+ * ```
+ */
+export interface CookieBannerTheme {
+    /** Banner position. Defaults to `'bottom'`. */
+    position?: 'top' | 'bottom' | 'bottom-left' | 'bottom-right' | 'center';
+    /** Primary/accent color (buttons). Defaults to `'#4F46E5'`. */
+    primaryColor?: string;
+    /** Banner background color. Defaults to `'#FFFFFF'`. */
+    backgroundColor?: string;
+    /** Text color. Defaults to `'#1F2937'`. */
+    textColor?: string;
+    /** Border radius for the banner container. Defaults to `'8px'`. */
+    borderRadius?: string;
+    /** Font family. Defaults to `'system-ui, sans-serif'`. */
+    fontFamily?: string;
+    /** Z-index for the banner. Defaults to `9999`. */
+    zIndex?: number;
+}
+/**
+ * Full configuration for a cookie banner component.
+ *
+ * @example
+ * ```tsx
+ * // React
+ * import { CookieBanner } from 'flowgrid-sdk/react';
+ *
+ * <CookieBanner
+ *   config={{
+ *     title: 'We use cookies',
+ *     description: 'We use cookies to improve your experience.',
+ *     acceptAllLabel: 'Accept All',
+ *     rejectAllLabel: 'Reject All',
+ *     customizeLabel: 'Customize',
+ *     privacyPolicyUrl: '/privacy',
+ *     theme: { position: 'bottom', primaryColor: '#4F46E5' },
+ *   }}
+ *   onAcceptAll={() => consent.acceptAll()}
+ *   onRejectAll={() => consent.rejectNonEssential()}
+ *   onCustomize={(prefs) => consent.update(prefs)}
+ * />
+ * ```
+ */
+export interface CookieBannerConfig {
+    /** Banner title. Defaults to `"Cookie Preferences"`. */
+    title?: string;
+    /** Banner description text. */
+    description?: string;
+    /** "Accept All" button label. Defaults to `"Accept All"`. */
+    acceptAllLabel?: string;
+    /** "Reject All" button label. Defaults to `"Reject All"`. */
+    rejectAllLabel?: string;
+    /** "Customize" / "Manage" button label. Defaults to `"Customize"`. */
+    customizeLabel?: string;
+    /** "Save Preferences" button label (in detail view). Defaults to `"Save Preferences"`. */
+    saveLabel?: string;
+    /** Link to privacy policy page. */
+    privacyPolicyUrl?: string;
+    /** Theme / appearance settings. */
+    theme?: CookieBannerTheme;
+    /** Category descriptions shown in the customization panel. */
+    categoryDescriptions?: Partial<Record<ConsentCategory, string>>;
+    /** Show the banner even if consent was already given (e.g. for a "manage cookies" link). */
+    forceShow?: boolean;
+}

package/dist/lib/features/analytics/attribution.d.ts

@@ -42,7 +42,7 @@
  * const report = await attribution.getReport({ range: 'last30days' });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { MoneyValue, DateRangeFilter } from "../../types";
 /**
  * Attribution model types.
@@ -141,7 +141,7 @@ export interface AttributionReportData {
 /**
  * Attribution - Multi-touch attribution tracking.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides attribution capabilities including:
@@ -177,7 +177,7 @@ export interface AttributionReportData {
  * });
  * ```
  */
-export declare class Attribution extends FTRPC {
+export declare class Attribution extends FlowGridTransport {
     /**
      * Tracks a marketing touchpoint.
      *

package/dist/lib/features/analytics/events.d.ts

@@ -46,7 +46,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { ClickEvent, FormEvent, SearchEvent, ErrorEvent, TimeSeriesData, DateRangeFilter, PaginationParams } from "../../types";
 /**
  * Configuration for tracking a custom event.
@@ -134,7 +134,7 @@ export interface EventAnalyticsData {
 /**
  * Events - Track and analyze custom events.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides flexible custom event tracking including:
@@ -162,7 +162,7 @@ export interface EventAnalyticsData {
  * const analytics = await events.getAnalytics({ range: 'last7days' });
  * ```
  */
-export declare class Events extends FTRPC {
+export declare class Events extends FlowGridTransport {
     /**
      * Tracks a custom event.
      *

package/dist/lib/features/analytics/funnels.d.ts

@@ -42,7 +42,7 @@
  * const analysis = await funnels.analyze('checkout_funnel');
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { FunnelAnalysis, DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Funnel definition configuration.
@@ -138,7 +138,7 @@ export interface FunnelComparisonData {
 /**
  * Funnels - Define and analyze conversion funnels.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides funnel analysis capabilities including:
@@ -170,7 +170,7 @@ export interface FunnelComparisonData {
  * });
  * ```
  */
-export declare class Funnels extends FTRPC {
+export declare class Funnels extends FlowGridTransport {
     /**
      * Defines a new funnel or updates existing.
      *

package/dist/lib/features/analytics/heatmaps.d.ts

@@ -40,7 +40,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { DateRangeFilter } from "../../types";
 /**
  * Click interaction data.
@@ -160,7 +160,7 @@ export interface HeatmapData {
 /**
  * Heatmaps - Track user interactions for heatmap visualization.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides heatmap data collection including:
@@ -190,7 +190,13 @@ export interface HeatmapData {
  * const data = await heatmaps.getData('/pricing', { range: 'last7days' });
  * ```
  */
-export declare class Heatmaps extends FTRPC {
+export declare class Heatmaps extends FlowGridTransport {
+    /** Throttle timestamps */
+    private lastMovementTime;
+    private lastScrollTime;
+    /** Throttle intervals (ms) */
+    private static readonly MOVEMENT_THROTTLE_MS;
+    private static readonly SCROLL_THROTTLE_MS;
     /**
      * Tracks a click interaction.
      *