flowgrid-sdk 1.0.2 → 1.2.0

package/dist/lib/frameworks/react/index.d.ts

@@ -1,48 +1,84 @@
 /**
- * @fileoverview FlowGrid SDK - React Integration
+ * @fileoverview FlowGrid SDK — React Integration
  * @module frameworks/react
  *
  * @description
- * React hooks and context provider for FlowGrid SDK.
- * All hooks are client-side only (use 'use client' in Next.js App Router).
+ * React provider, hooks, and cookie banner component for FlowGrid SDK.
+ * Uses React Context API for state management.
+ *
+ * ## Quick Start
  *
- * @example
  * ```tsx
- * // App.tsx - Wrap your app
- * import { FlowGridProvider } from 'flowgrid-sdk/react';
+ * // app.tsx
+ * import { FlowGridProvider, useFlowGrid, CookieBanner } from 'flowgrid-sdk/react';
+ * import { ConsentManager, FlowGridTransport } from 'flowgrid-sdk';
+ *
+ * const consent = new ConsentManager({
+ *   onChange: (prefs) => {
+ *     FlowGridTransport.setConsent({
+ *       analytics: prefs.analytics,
+ *       marketing: prefs.marketing,
+ *     });
+ *   },
+ * });
  *
  * function App() {
  *   return (
  *     <FlowGridProvider
- *       webId="your-web-id"
+ *       webId="web_abc123"
  *       endpoint="https://api.flowgrid.io"
- *       apiKey="your-api-key"
+ *       apiKey="key_xxx"
  *     >
- *       <YourApp />
+ *       <MyApp />
+ *       <CookieBanner consent={consent} />
  *     </FlowGridProvider>
  *   );
  * }
+ *
+ * function MyComponent() {
+ *   const { trackEvent } = useFlowGrid();
+ *   return <button onClick={() => trackEvent('click', { id: 'cta' })}>Click</button>;
+ * }
+ * ```
+ */
+import { type ReactNode } from 'react';
+import { Activation, TrackFeature, TrackPrompt, Experiment, PageViews, Sessions, Events, Identify, Funnels, Products, CartTracking, Checkout, Purchases } from '../../../index';
+export { CookieBanner } from './CookieBanner';
+export type { CookieBannerProps } from './CookieBanner';
+/**
+ * Configuration for the React FlowGrid provider.
+ *
+ * @example
+ * ```tsx
+ * <FlowGridProvider
+ *   webId="web_abc123"
+ *   endpoint="https://api.flowgrid.io"
+ *   apiKey="key_xxx"
+ *   autoTrackPageViews={true}
+ *   autoTrackSessions={true}
+ *   debug={false}
+ * >
+ *   {children}
+ * </FlowGridProvider>
  * ```
  */
-import React, { type ReactNode } from 'react';
-import { Activation, TrackFeature, TrackPrompt, Experiment, FeatureFlag, PageViews, Sessions, Events, Identify, Funnels, Products, CartTracking, Checkout, Purchases } from '../../../index';
 export interface FlowGridConfig {
     webId: string;
     endpoint: string;
     apiKey: string;
-    /** Auto-track page views (default: true) */
+    visitorId?: string;
     autoTrackPageViews?: boolean;
-    /** Auto-track sessions (default: true) */
     autoTrackSessions?: boolean;
-    /** Enable debug mode (default: false) */
     debug?: boolean;
 }
+/**
+ * Value provided by the FlowGrid React context.
+ */
 export interface FlowGridContextValue {
     activation: Activation;
     trackFeature: TrackFeature;
     trackPrompt: TrackPrompt;
     experiment: Experiment;
-    featureFlag: FeatureFlag;
     pageViews: PageViews;
     sessions: Sessions;
     events: Events;
@@ -52,148 +88,102 @@ export interface FlowGridContextValue {
     cart: CartTracking;
     checkout: Checkout;
     purchases: Purchases;
+    /** Shorthand: track a custom event. */
     trackEvent: (name: string, properties?: Record<string, unknown>) => Promise<void>;
+    /** Shorthand: identify a user. */
     identifyUser: (userId: string, traits?: Record<string, unknown>) => Promise<void>;
+    /** `true` once the session has started and the SDK is ready. */
     isReady: boolean;
 }
 export interface FlowGridProviderProps extends FlowGridConfig {
     children: ReactNode;
 }
 /**
- * FlowGrid Provider - Wrap your app to enable analytics.
+ * React context provider for FlowGrid SDK.
  *
- * @example
- * ```tsx
- * <FlowGridProvider
- *   webId="web_123"
- *   endpoint="https://api.flowgrid.io"
- *   apiKey="key_abc"
- *   autoTrackPageViews={true}
- * >
- *   <App />
- * </FlowGridProvider>
- * ```
- */
-export declare function FlowGridProvider({ children, webId, endpoint, apiKey, autoTrackPageViews, autoTrackSessions, debug }: FlowGridProviderProps): import("react/jsx-runtime").JSX.Element;
-/**
- * Access the FlowGrid SDK instance.
- * Must be used within FlowGridProvider.
+ * Initialises all SDK modules, auto-tracks sessions and page views,
+ * and provides them to child components via {@link useFlowGrid}.
  *
  * @example
  * ```tsx
- * function MyComponent() {
- *   const { trackEvent, events } = useFlowGrid();
- *
- *   const handleClick = () => {
- *     trackEvent('button_clicked', { buttonId: 'cta' });
- *   };
- *
- *   return <button onClick={handleClick}>Click me</button>;
- * }
- * ```
- */
-export declare function useFlowGrid(): FlowGridContextValue;
-/**
- * Track page views automatically on route changes.
- * Use in your root layout or App component.
+ * import { FlowGridProvider } from 'flowgrid-sdk/react';
  *
- * @example
- * ```tsx
  * function App() {
- *   usePageView(); // Tracks on every route change
- *   return <Routes />;
+ *   return (
+ *     <FlowGridProvider
+ *       webId={process.env.REACT_APP_FLOWGRID_WEB_ID!}
+ *       endpoint={process.env.REACT_APP_FLOWGRID_ENDPOINT!}
+ *       apiKey={process.env.REACT_APP_FLOWGRID_API_KEY!}
+ *     >
+ *       <Routes />
+ *     </FlowGridProvider>
+ *   );
  * }
  * ```
  */
-export declare function usePageView(pageName?: string): void;
+export declare function FlowGridProvider({ children, webId, endpoint, apiKey, visitorId, autoTrackPageViews, autoTrackSessions, debug, }: FlowGridProviderProps): import("react/jsx-runtime").JSX.Element;
 /**
- * Track an event when component mounts.
+ * Access the FlowGrid SDK instance from context.
  *
- * @example
- * ```tsx
- * function PricingPage() {
- *   useTrackEvent('pricing_page_viewed', { source: 'navbar' });
- *   return <PricingContent />;
- * }
- * ```
- */
-export declare function useTrackEvent(eventName: string, properties?: Record<string, unknown>, deps?: React.DependencyList): void;
-/**
- * Get experiment variant for a user.
+ * @throws If used outside a {@link FlowGridProvider}.
  *
  * @example
  * ```tsx
- * function CheckoutPage() {
- *   const { variant, isLoading } = useExperiment('checkout_v2', 'user_123');
- *
- *   if (isLoading) return <Loading />;
+ * import { useFlowGrid } from 'flowgrid-sdk/react';
  *
- *   return variant === 'treatment'
- *     ? <NewCheckout />
- *     : <OldCheckout />;
+ * function Dashboard() {
+ *   const { events, isReady } = useFlowGrid();
+ *   // ...
  * }
  * ```
  */
-export declare function useExperiment(experimentId: string, userId: string): {
-    variant: string | null;
-    isLoading: boolean;
-};
+export declare function useFlowGrid(): FlowGridContextValue;
 /**
- * Evaluate a feature flag.
+ * Get the `trackEvent` helper from context.
  *
  * @example
  * ```tsx
- * function Dashboard() {
- *   const { isEnabled, isLoading } = useFeatureFlag('new_dashboard', {
- *     userId: 'user_123'
- *   });
- *
- *   if (isLoading) return <Loading />;
- *
- *   return isEnabled ? <NewDashboard /> : <OldDashboard />;
- * }
+ * const trackEvent = useTrackEvent();
+ * <button onClick={() => trackEvent('signup_click')}>Sign Up</button>
  * ```
  */
-export declare function useFeatureFlag(flagKey: string, context?: {
-    userId?: string;
-    [key: string]: unknown;
-}): {
-    isEnabled: boolean;
-    isLoading: boolean;
-};
+export declare function useTrackEvent(): (name: string, properties?: Record<string, unknown>) => Promise<void>;
 /**
- * Track user identity.
+ * Identify a user when their ID becomes available.
+ *
+ * @param userId  - User ID (pass `null` when unknown).
+ * @param traits  - Optional user traits.
  *
  * @example
  * ```tsx
- * function ProfilePage({ user }) {
- *   useIdentify(user.id, {
- *     email: user.email,
- *     plan: user.plan
- *   });
+ * import { useIdentify } from 'flowgrid-sdk/react';
  *
- *   return <Profile />;
+ * function Profile({ userId }: { userId: string }) {
+ *   useIdentify(userId, { plan: 'pro' });
+ *   return <div>...</div>;
  * }
  * ```
  */
-export declare function useIdentify(userId: string, traits?: Record<string, unknown>): void;
+export declare function useIdentify(userId: string | null, traits?: Record<string, unknown>): void;
 /**
- * Ecommerce tracking hooks.
+ * Get ecommerce tracking helpers.
  *
  * @example
  * ```tsx
+ * import { useEcommerce } from 'flowgrid-sdk/react';
+ *
  * function ProductPage({ product }) {
  *   const { trackProductView, trackAddToCart } = useEcommerce();
  *
  *   useEffect(() => {
- *     trackProductView(product);
+ *     trackProductView({ id: product.id, name: product.name, price: product.price });
  *   }, [product]);
  *
- *   const handleAddToCart = () => {
- *     trackAddToCart(product, 1);
- *   };
- *
- *   return <button onClick={handleAddToCart}>Add to Cart</button>;
+ *   return (
+ *     <button onClick={() => trackAddToCart({ id: product.id, name: product.name, price: product.price })}>
+ *       Add to Cart
+ *     </button>
+ *   );
  * }
  * ```
  */
@@ -203,7 +193,6 @@ export declare function useEcommerce(): {
         name: string;
         price: number;
         currency?: string;
-        category?: string;
     }) => Promise<void>;
     trackAddToCart: (product: {
         id: string;
@@ -211,35 +200,8 @@ export declare function useEcommerce(): {
         price: number;
         currency?: string;
     }, quantity?: number) => Promise<void>;
-    trackCheckoutStart: (cartItems: Array<{
-        productId: string;
-        name: string;
-        price: number;
-        quantity: number;
-    }>) => Promise<void>;
-    trackPurchase: (orderData: {
-        orderId: string;
-        revenue: number;
-        items: Array<{
-            id: string;
-            name: string;
-            price: number;
-            quantity: number;
-        }>;
-    }) => Promise<void>;
     products: Products;
     cart: CartTracking;
     checkout: Checkout;
     purchases: Purchases;
 };
-declare const _default: {
-    FlowGridProvider: typeof FlowGridProvider;
-    useFlowGrid: typeof useFlowGrid;
-    usePageView: typeof usePageView;
-    useTrackEvent: typeof useTrackEvent;
-    useExperiment: typeof useExperiment;
-    useFeatureFlag: typeof useFeatureFlag;
-    useIdentify: typeof useIdentify;
-    useEcommerce: typeof useEcommerce;
-};
-export default _default;

package/dist/lib/frameworks/vue/CookieBanner.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview FlowGrid Cookie Banner — Vue 3 Component
+ * @module frameworks/vue/CookieBanner
+ *
+ * @description
+ * A customisable cookie consent banner for Vue 3 applications.
+ * Works with the FlowGrid {@link ConsentManager}.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { CookieBanner } from 'flowgrid-sdk/vue';
+ * import { ConsentManager, FlowGridTransport } from 'flowgrid-sdk';
+ *
+ * const consent = new ConsentManager({
+ *   onChange: (prefs) => {
+ *     FlowGridTransport.setConsent({
+ *       analytics: prefs.analytics,
+ *       marketing: prefs.marketing,
+ *     });
+ *   },
+ * });
+ * </script>
+ *
+ * <template>
+ *   <CookieBanner
+ *     :consent="consent"
+ *     :config="{
+ *       title: 'We use cookies',
+ *       description: 'We use cookies to improve your experience.',
+ *       privacyPolicyUrl: '/privacy',
+ *       theme: { position: 'bottom', primaryColor: '#4F46E5' },
+ *     }"
+ *   />
+ * </template>
+ * ```
+ */
+import { type PropType } from 'vue';
+import type { ConsentManager } from '../../consent/manager';
+import type { CookieBannerConfig } from '../../consent/types';
+/**
+ * Vue 3 Cookie Banner component.
+ *
+ * Renders a GDPR-compliant cookie consent banner with accept, reject,
+ * and customise options. Uses the {@link ConsentManager} to persist choices.
+ *
+ * @example
+ * ```vue
+ * <template>
+ *   <CookieBanner
+ *     :consent="consentManager"
+ *     :config="{ title: 'Cookies', theme: { position: 'bottom-right' } }"
+ *     @close="onBannerClosed"
+ *   />
+ * </template>
+ * ```
+ */
+export declare const CookieBanner: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    consent: {
+        type: PropType<ConsentManager>;
+        required: true;
+    };
+    config: {
+        type: PropType<CookieBannerConfig>;
+        default: () => {};
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}> | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "close"[], "close", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    consent: {
+        type: PropType<ConsentManager>;
+        required: true;
+    };
+    config: {
+        type: PropType<CookieBannerConfig>;
+        default: () => {};
+    };
+}>> & Readonly<{
+    onClose?: ((...args: any[]) => any) | undefined;
+}>, {
+    config: CookieBannerConfig;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/lib/frameworks/vue/index.d.ts

@@ -22,11 +22,12 @@
  * ```
  */
 import { type App, type Ref } from 'vue';
-import { Activation, TrackFeature, TrackPrompt, Experiment, FeatureFlag, PageViews, Sessions, Events, Identify, Funnels, Products, CartTracking, Checkout, Purchases } from '../../../index';
+import { Activation, TrackFeature, TrackPrompt, Experiment, PageViews, Sessions, Events, Identify, Funnels, Products, CartTracking, Checkout, Purchases } from '../../../index';
 export interface FlowGridConfig {
     webId: string;
     endpoint: string;
     apiKey: string;
+    visitorId?: string;
     autoTrackPageViews?: boolean;
     autoTrackSessions?: boolean;
     debug?: boolean;
@@ -36,7 +37,6 @@ export interface FlowGridInstance {
     trackFeature: TrackFeature;
     trackPrompt: TrackPrompt;
     experiment: Experiment;
-    featureFlag: FeatureFlag;
     pageViews: PageViews;
     sessions: Sessions;
     events: Events;
@@ -93,7 +93,6 @@ export declare function useFlowGrid(): {
     trackFeature: TrackFeature;
     trackPrompt: TrackPrompt;
     experiment: Experiment;
-    featureFlag: FeatureFlag;
     pageViews: PageViews;
     sessions: Sessions;
     events: Events;
@@ -155,27 +154,6 @@ export declare function useExperiment(experimentId: string, userId: string): {
     variant: Ref<string | null, string | null>;
     isLoading: Ref<boolean, boolean>;
 };
-/**
- * Evaluate a feature flag.
- *
- * @example
- * ```vue
- * <script setup>
- * import { useFeatureFlag } from 'flowgrid-sdk/vue';
- *
- * const { isEnabled, isLoading } = useFeatureFlag('new_dashboard');
- * </script>
- *
- * <template>
- *   <NewDashboard v-if="isEnabled" />
- *   <OldDashboard v-else />
- * </template>
- * ```
- */
-export declare function useFeatureFlag(flagKey: string, userId?: string): {
-    isEnabled: Ref<boolean, boolean>;
-    isLoading: Ref<boolean, boolean>;
-};
 /**
  * Identify a user.
  *
@@ -259,6 +237,7 @@ export declare function createRouterPlugin(): (to: {
 }, from: {
     path: string;
 }) => void;
+export { CookieBanner } from './CookieBanner';
 declare const _default: {
     FlowGridPlugin: {
         install(app: App, options: FlowGridConfig): void;
@@ -267,9 +246,33 @@ declare const _default: {
     usePageView: typeof usePageView;
     useTrackEvent: typeof useTrackEvent;
     useExperiment: typeof useExperiment;
-    useFeatureFlag: typeof useFeatureFlag;
     useIdentify: typeof useIdentify;
     useEcommerce: typeof useEcommerce;
     createRouterPlugin: typeof createRouterPlugin;
+    CookieBanner: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+        consent: {
+            type: import("vue").PropType<import("../../consent/manager").ConsentManager>;
+            required: true;
+        };
+        config: {
+            type: import("vue").PropType<import("../../consent/types").CookieBannerConfig>;
+            default: () => {};
+        };
+    }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+        [key: string]: any;
+    }> | null, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "close"[], "close", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+        consent: {
+            type: import("vue").PropType<import("../../consent/manager").ConsentManager>;
+            required: true;
+        };
+        config: {
+            type: import("vue").PropType<import("../../consent/types").CookieBannerConfig>;
+            default: () => {};
+        };
+    }>> & Readonly<{
+        onClose?: ((...args: any[]) => any) | undefined;
+    }>, {
+        config: import("../../consent/types").CookieBannerConfig;
+    }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 };
 export default _default;

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

@@ -340,6 +340,68 @@ export interface RealTimeMetrics {
         count: number;
     }>;
 }
+/**
+ * Granularity for active user queries.
+ */
+export type ActiveUserGranularity = 'day' | 'week' | 'month';
+/**
+ * Configuration for querying active users.
+ */
+export interface ActiveUsersConfig {
+    /** Time granularity for the query */
+    granularity: ActiveUserGranularity;
+    /** Start date (ISO string) */
+    dateFrom?: string;
+    /** End date (ISO string) */
+    dateTo?: string;
+    /** Optional cohort/segment filter */
+    segment?: string;
+}
+/**
+ * A single period within an active users response.
+ */
+export interface ActiveUserPeriod {
+    /** Period label (e.g. '2026-04-15', '2026-W16', '2026-04') */
+    period: string;
+    /** Active users in this period */
+    activeUsers: number;
+    /** Active users in previous equivalent period */
+    previousPeriod?: number;
+    /** Percent change from previous period */
+    changePercent?: number;
+}
+/**
+ * Response from an active users query.
+ */
+export interface ActiveUsersResponse {
+    /** Granularity used */
+    granularity: ActiveUserGranularity;
+    /** Per-period active user counts */
+    periods: ActiveUserPeriod[];
+    /** Total unique active users across all periods */
+    total: number;
+    /** Overall trend direction */
+    trend: 'increasing' | 'stable' | 'decreasing';
+}
+/**
+ * DAU/WAU/MAU ratios (stickiness metrics).
+ */
+export interface ActiveUserRatios {
+    /** Daily active users */
+    dau: number;
+    /** Weekly active users */
+    wau: number;
+    /** Monthly active users */
+    mau: number;
+    /** DAU / WAU ratio */
+    dauWauRatio: number;
+    /** DAU / MAU ratio */
+    dauMauRatio: number;
+    /** WAU / MAU ratio */
+    wauMauRatio: number;
+    /** Timestamp of computation */
+    timestamp: string;
+}
 /**
  * User lifecycle stage.
  */

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

@@ -8,6 +8,8 @@
 export interface BaseConfig {
     /** The name of the event to track */
     eventName: string;
+    /** Optional visitor ID override; falls back to instance-level visitorId */
+    visitorId?: string;
     /** Additional properties to send with the event */
     properties?: Record<string, unknown>;
 }

package/dist/lib/utils/identity.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview FlowGrid Identity Manager.
+ * @module utils/identity
+ *
+ * @description
+ * Owns the visitor/session identity lifecycle.
+ * Writes its own cookies/storage so the SDK can self-bootstrap
+ * without depending on an external tracking script (track.js).
+ *
+ * Backward-compatible: checks for existing track.js `visitor_id`
+ * before falling back to its own `fg_visitor_id` key.
+ */
+export interface IdentityConfig {
+    /** Explicit visitor ID (overrides auto-resolution) */
+    visitorId?: string;
+    /** Cookie domain (defaults to current hostname) */
+    cookieDomain?: string;
+    /** Visitor cookie max-age in days (default: 365) */
+    visitorMaxAgeDays?: number;
+    /** Session timeout in minutes (default: 30) */
+    sessionTimeoutMinutes?: number;
+    /** Storage strategy */
+    storage?: 'cookie' | 'localStorage' | 'memory';
+    /** Server-side cookie reader (e.g. Next.js `cookies()`) */
+    serverCookies?: ServerCookieReader;
+    /** Write to `visitor_id` (track.js compat) instead of `fg_visitor_id` (default true) */
+    compat?: boolean;
+}
+/**
+ * Minimal interface for reading cookies server-side.
+ * Compatible with Next.js `cookies()` and Nuxt `useCookie()`.
+ */
+export interface ServerCookieReader {
+    get(name: string): {
+        value: string;
+    } | string | undefined | null;
+}
+export declare class IdentityManager {
+    private visitorId;
+    private sessionId;
+    private config;
+    /** In-memory store for SSR / Node environments */
+    private memoryStore;
+    constructor(config?: IdentityConfig);
+    /**
+     * Get or create a persistent visitor ID.
+     *
+     * Resolution order:
+     *  1. Explicit config.visitorId
+     *  2. track.js `visitor_id` cookie/localStorage (backward compat)
+     *  3. `fg_visitor_id` cookie
+     *  4. `fg_visitor_id` localStorage
+     *  5. Server cookie reader (if provided)
+     *  6. Generate new UUID v4, persist to cookie + localStorage
+     */
+    getVisitorId(): string;
+    /**
+     * Get or create a session ID.
+     *
+     * - Reads from sessionStorage `fg_session_id`
+     * - If absent or expired (>sessionTimeoutMinutes since last activity), creates new
+     * - Persists to sessionStorage
+     * - Touches timestamp on every call
+     */
+    getSessionId(): string;
+    /**
+     * Update the visitor ID (e.g. after identify() links anonymous → known user).
+     * Persists to cookie + localStorage.
+     */
+    setVisitorId(id: string): void;
+    /** Clear session (e.g. on logout). */
+    clearSession(): void;
+    /** Clear all identity (GDPR). Removes visitor + session + experiment assignments. */
+    clearAll(): void;
+    /** Check if running in a browser environment. */
+    isBrowser(): boolean;
+    /** Returns the primary cookie name based on compat mode */
+    private get visitorCookieName();
+    private resolveVisitorId;
+    private readLocalStorage;
+    private removeLegacyCookie;
+    private persistVisitorId;
+    private getMemorySessionId;
+    private readCookie;
+    private readServerCookie;
+    private writeCookie;
+    private deleteCookie;
+    private generateVisitorId;
+    private generateSessionId;
+    private uuidV4;
+    private randomHex;
+    private detectBrowser;
+}