flowgrid-sdk 1.2.0 → 1.3.0

package/dist/lib/consent/manager.js

@@ -0,0 +1,336 @@
+/**
+ * @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
+ * ```
+ */
+// ============================================================================
+// DEFAULTS
+// ============================================================================
+const DEFAULT_COOKIE_NAME = 'fg_consent';
+const DEFAULT_TRACKING_COOKIE_NAME = 'fg_tracking_consent';
+const DEFAULT_COOKIE_DAYS = 365;
+const DEFAULT_PREFERENCES = {
+    necessary: true,
+    analytics: false,
+    marketing: false,
+    preferences: true,
+};
+// ============================================================================
+// CONSENT MANAGER
+// ============================================================================
+/**
+ * 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 class ConsentManager {
+    /**
+     * 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) {
+        this.config = {
+            cookieName: config?.cookieName ?? DEFAULT_COOKIE_NAME,
+            cookieDays: config?.cookieDays ?? DEFAULT_COOKIE_DAYS,
+            cookieDomain: config?.cookieDomain,
+            respectDNT: config?.respectDNT ?? true,
+            requireExplicitConsent: config?.requireExplicitConsent ?? true,
+            onChange: config?.onChange,
+            defaultPreferences: {
+                ...DEFAULT_PREFERENCES,
+                ...config?.defaultPreferences,
+                necessary: true, // always true
+            },
+        };
+        // Load saved preferences or use defaults
+        const saved = this.loadFromCookie();
+        if (saved) {
+            this.preferences = saved;
+        }
+        else if (this.isDNTEnabled() && this.config.respectDNT) {
+            // DNT/GPC: default to rejecting non-essential
+            this.preferences = {
+                necessary: true,
+                analytics: false,
+                marketing: false,
+                preferences: false,
+            };
+        }
+        else if (this.config.requireExplicitConsent) {
+            this.preferences = { ...this.config.defaultPreferences };
+        }
+        else {
+            // Implied consent mode: all enabled by default
+            this.preferences = {
+                necessary: true,
+                analytics: true,
+                marketing: true,
+                preferences: true,
+            };
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // PUBLIC API
+    // ---------------------------------------------------------------------------
+    /**
+     * 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() {
+        return this.loadFromCookie() !== null;
+    }
+    /**
+     * Get the current consent preferences.
+     *
+     * @returns A copy of the current {@link ConsentPreferences}.
+     *
+     * @example
+     * ```ts
+     * const prefs = consent.getPreferences();
+     * if (prefs.analytics) {
+     *   initAnalytics();
+     * }
+     * ```
+     */
+    getPreferences() {
+        return { ...this.preferences };
+    }
+    /**
+     * 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) {
+        return this.preferences[category] ?? false;
+    }
+    /**
+     * Accept all consent categories.
+     *
+     * @example
+     * ```ts
+     * // "Accept All" button handler
+     * document.getElementById('accept-all')?.addEventListener('click', () => {
+     *   consent.acceptAll();
+     * });
+     * ```
+     */
+    acceptAll() {
+        this.setPreferences({
+            necessary: true,
+            analytics: true,
+            marketing: true,
+            preferences: true,
+        });
+    }
+    /**
+     * Reject all non-essential categories.
+     * Only `necessary` remains enabled.
+     *
+     * @example
+     * ```ts
+     * // "Reject All" button handler
+     * consent.rejectNonEssential();
+     * ```
+     */
+    rejectNonEssential() {
+        this.setPreferences({
+            necessary: true,
+            analytics: false,
+            marketing: false,
+            preferences: false,
+        });
+    }
+    /**
+     * 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) {
+        this.setPreferences({
+            ...this.preferences,
+            ...updates,
+            necessary: true,
+        });
+    }
+    /**
+     * 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() {
+        this.deleteCookie();
+        this.preferences = { ...this.config.defaultPreferences };
+    }
+    // ---------------------------------------------------------------------------
+    // PRIVATE
+    // ---------------------------------------------------------------------------
+    setPreferences(prefs) {
+        const previous = { ...this.preferences };
+        this.preferences = { ...prefs, necessary: true };
+        this.saveToCookie();
+        if (this.config.onChange) {
+            this.config.onChange(this.preferences);
+        }
+    }
+    isDNTEnabled() {
+        if (typeof navigator === 'undefined')
+            return false;
+        if (navigator.globalPrivacyControl)
+            return true;
+        if (navigator.doNotTrack === '1')
+            return true;
+        return false;
+    }
+    // ---------------------------------------------------------------------------
+    // COOKIE I/O
+    // ---------------------------------------------------------------------------
+    loadFromCookie() {
+        if (typeof document === 'undefined')
+            return null;
+        const match = document.cookie.match(new RegExp('(^| )' + this.config.cookieName + '=([^;]+)'));
+        if (!match)
+            return null;
+        try {
+            const parsed = JSON.parse(decodeURIComponent(match[2]));
+            if (typeof parsed === 'object' && parsed !== null && typeof parsed.necessary === 'boolean') {
+                return { ...DEFAULT_PREFERENCES, ...parsed, necessary: true };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    saveToCookie() {
+        if (typeof document === 'undefined')
+            return;
+        const value = encodeURIComponent(JSON.stringify(this.preferences));
+        const maxAge = this.config.cookieDays * 24 * 60 * 60;
+        const domain = this.config.cookieDomain ? `; Domain=${this.config.cookieDomain}` : '';
+        const secure = typeof location !== 'undefined' && location.protocol === 'https:' ? '; Secure' : '';
+        document.cookie = `${this.config.cookieName}=${value}; Path=/; Max-Age=${maxAge}; SameSite=Lax${secure}${domain}`;
+        // Simple boolean cookie for track.js compatibility
+        const trackingAllowed = this.preferences.analytics ? 'true' : 'false';
+        document.cookie = `${DEFAULT_TRACKING_COOKIE_NAME}=${trackingAllowed}; Path=/; Max-Age=${maxAge}; SameSite=Lax${secure}${domain}`;
+    }
+    deleteCookie() {
+        if (typeof document === 'undefined')
+            return;
+        const domain = this.config.cookieDomain ? `; Domain=${this.config.cookieDomain}` : '';
+        document.cookie = `${this.config.cookieName}=; Path=/; Max-Age=0${domain}`;
+        document.cookie = `${DEFAULT_TRACKING_COOKIE_NAME}=; Path=/; Max-Age=0${domain}`;
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/lib/consent/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../../src/lib/consent/manager.ts"],"names":[],"mappings":"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"}

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

@@ -117,26 +117,9 @@ export interface CookieBannerTheme {
 /**
  * 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)}
- * />
- * ```
+ * Pass this to your own UI implementation — `ConsentManager` handles the
+ * persistence; rendering is left to consumer code so the SDK stays
+ * framework-agnostic.
  */
 export interface CookieBannerConfig {
     /** Banner title. Defaults to `"Cookie Preferences"`. */

package/dist/lib/consent/types.js

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview FlowGrid Consent Management — Types
+ * @module consent/types
+ *
+ * @description
+ * Types for cookie consent management, GDPR/CCPA compliance,
+ * and customizable cookie banner configuration.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/consent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/consent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

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

@@ -37,13 +37,10 @@
  *   campaign: 'brand_terms',
  *   medium: 'cpc'
  * });
- *
- * // Get attribution report
- * const report = await attribution.getReport({ range: 'last30days' });
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { MoneyValue, DateRangeFilter } from "../../types";
+import { MoneyValue } from "../../types";
 /**
  * Attribution model types.
  */
@@ -85,6 +82,8 @@ export interface ConversionEvent {
     value?: MoneyValue;
     /** Conversion identifier (e.g., order ID) */
     conversionId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
 }
 /**
  * Touchpoint response from API.
@@ -170,11 +169,6 @@ export interface AttributionReportData {
  *   value: { amount: 9999, currency: 'USD' },
  *   conversionId: 'ORD-12345'
  * });
- *
- * // Get attribution report
- * const report = await attribution.getReport({
- *   model: 'linear'
- * });
  * ```
  */
 export declare class Attribution extends FlowGridTransport {
@@ -214,44 +208,9 @@ export declare class Attribution extends FlowGridTransport {
      */
     recordConversion(event: ConversionEvent): Promise<TouchpointResponse>;
     /**
-     * Gets attribution report with specified model.
-     *
-     * @param options - Report options
-     * @returns Promise resolving to attribution report
-     *
-     * @example
-     * ```typescript
-     * const report = await attribution.getReport({
-     *   model: 'position_based',
-     *   filter: { range: 'last30days' }
-     * });
-     *
-     * // Bar chart - revenue by channel
-     * const channelChart = report.byChannel.map(c => ({
-     *   name: c.channel,
-     *   value: c.attributedRevenue.amount
-     * }));
-     *
-     * // Sankey - top conversion paths
-     * const pathData = report.topPaths;
-     * ```
+     * Auto-capture a touchpoint from `utm_*` query params and `document.referrer`.
+     * Browser-only; returns null on the server or when no UTM/referrer data is present.
      */
-    getReport(options?: {
-        model?: AttributionModel;
-        filter?: DateRangeFilter;
-    }): Promise<AttributionReportData>;
-    /**
-     * Gets user journey/path for a specific user.
-     *
-     * @param userId - User identifier
-     * @returns Promise resolving to user journey data
-     */
-    getUserJourney(userId: string): Promise<{
-        touchpoints: Array<TouchpointConfig & {
-            timestamp: string;
-        }>;
-        conversions: ConversionEvent[];
-        totalValue: MoneyValue;
-    }>;
+    captureFromUrl(userId: string): TouchpointConfig | null;
 }
 export default Attribution;

package/dist/lib/features/analytics/attribution.js

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview Product Analytics - Revenue Attribution
+ * @module features/analytics/attribution
+ *
+ * @description
+ * Multi-touch attribution modeling to understand which marketing
+ * channels and touchpoints drive conversions and revenue.
+ *
+ * @useCases
+ * - Track marketing touchpoints across customer journey
+ * - Calculate attribution for conversions
+ * - Compare attribution models (first-touch, last-touch, linear)
+ * - Optimize marketing spend allocation
+ * - Understand channel effectiveness
+ *
+ * @metrics
+ * - Attributed revenue by channel
+ * - Conversion paths
+ * - Assisted conversions
+ * - Time to conversion
+ * - Channel influence score
+ *
+ * @chartData
+ * - Sankey diagram: Customer journey paths
+ * - Bar chart: Revenue by channel
+ * - Table: Attribution comparison by model
+ * - Pie chart: Channel contribution
+ *
+ * @example
+ * ```typescript
+ * const attribution = new Attribution(webId, endpoint, apiKey);
+ *
+ * // Track touchpoint
+ * await attribution.trackTouchpoint({
+ *   userId: 'user_123',
+ *   channel: 'google_ads',
+ *   campaign: 'brand_terms',
+ *   medium: 'cpc'
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+import { getWindow, getDocument, isBrowser } from "../../utils/browser";
+// ============================================================================
+// ATTRIBUTION CLASS
+// ============================================================================
+/**
+ * Attribution - Multi-touch attribution tracking.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides attribution capabilities including:
+ * - Touchpoint tracking
+ * - Conversion attribution
+ * - Multiple attribution models
+ * - Path analysis
+ * - Channel effectiveness
+ *
+ * @example
+ * ```typescript
+ * const attribution = new Attribution(webId, endpoint, apiKey);
+ *
+ * // Track touchpoints throughout customer journey
+ * await attribution.trackTouchpoint({
+ *   userId: 'user_123',
+ *   channel: 'email',
+ *   campaign: 'welcome_series',
+ *   medium: 'email'
+ * });
+ *
+ * // Record conversion
+ * await attribution.recordConversion({
+ *   userId: 'user_123',
+ *   conversionType: 'purchase',
+ *   value: { amount: 9999, currency: 'USD' },
+ *   conversionId: 'ORD-12345'
+ * });
+ * ```
+ */
+export class Attribution extends FlowGridTransport {
+    /**
+     * Tracks a marketing touchpoint.
+     *
+     * @param config - Touchpoint configuration
+     * @returns Promise resolving to touchpoint response
+     *
+     * @example
+     * ```typescript
+     * await attribution.trackTouchpoint({
+     *   userId: 'user_123',
+     *   channel: 'facebook_ads',
+     *   campaign: 'retargeting_cart',
+     *   medium: 'paid_social',
+     *   landingPage: '/products/special-offer'
+     * });
+     * ```
+     */
+    async trackTouchpoint(config) {
+        return await this.init("attribution_touchpoint", {
+            type: "attribution_touchpoint",
+            userId: config.userId,
+            channel: config.channel,
+            campaign: config.campaign,
+            medium: config.medium,
+            source: config.source,
+            content: config.content,
+            term: config.term,
+            referrer: config.referrer,
+            landingPage: config.landingPage,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Records a conversion for attribution.
+     *
+     * @param event - Conversion event
+     * @returns Promise resolving to conversion response
+     *
+     * @example
+     * ```typescript
+     * await attribution.recordConversion({
+     *   userId: 'user_123',
+     *   conversionType: 'purchase',
+     *   value: { amount: 14999, currency: 'USD' },
+     *   conversionId: 'ORD-98765'
+     * });
+     * ```
+     */
+    async recordConversion(event) {
+        return await this.init("attribution_conversion", {
+            type: "attribution_conversion",
+            userId: event.userId,
+            conversionType: event.conversionType,
+            value: event.value,
+            conversionId: event.conversionId,
+            ...event.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Auto-capture a touchpoint from `utm_*` query params and `document.referrer`.
+     * Browser-only; returns null on the server or when no UTM/referrer data is present.
+     */
+    captureFromUrl(userId) {
+        if (!isBrowser())
+            return null;
+        const win = getWindow();
+        const doc = getDocument();
+        if (!win || !doc)
+            return null;
+        const params = new URLSearchParams(win.location.search);
+        const utm = {
+            utmSource: params.get("utm_source") ?? undefined,
+            utmMedium: params.get("utm_medium") ?? undefined,
+            utmCampaign: params.get("utm_campaign") ?? undefined,
+            utmTerm: params.get("utm_term") ?? undefined,
+            utmContent: params.get("utm_content") ?? undefined,
+        };
+        const referrer = doc.referrer || undefined;
+        if (!utm.utmSource && !utm.utmMedium && !utm.utmCampaign && !referrer) {
+            return null;
+        }
+        const config = {
+            userId,
+            channel: utm.utmSource || (referrer ? "referral" : "direct"),
+            campaign: utm.utmCampaign,
+            medium: utm.utmMedium,
+            source: utm.utmSource,
+            content: utm.utmContent,
+            term: utm.utmTerm,
+            referrer,
+            landingPage: win.location.pathname,
+        };
+        void this.trackTouchpoint(config);
+        return config;
+    }
+}
+export default Attribution;
+//# sourceMappingURL=attribution.js.map

package/dist/lib/features/analytics/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/attribution.ts"],"names":[],"mappings":"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"}