flowgrid-sdk 1.0.0

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

@@ -0,0 +1,245 @@
+/**
+ * @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).
+ *
+ * @example
+ * ```tsx
+ * // App.tsx - Wrap your app
+ * import { FlowGridProvider } from 'flowgrid-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <FlowGridProvider
+ *       webId="your-web-id"
+ *       endpoint="https://api.flowgrid.io"
+ *       apiKey="your-api-key"
+ *     >
+ *       <YourApp />
+ *     </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) */
+    autoTrackPageViews?: boolean;
+    /** Auto-track sessions (default: true) */
+    autoTrackSessions?: boolean;
+    /** Enable debug mode (default: false) */
+    debug?: boolean;
+}
+export interface FlowGridContextValue {
+    activation: Activation;
+    trackFeature: TrackFeature;
+    trackPrompt: TrackPrompt;
+    experiment: Experiment;
+    featureFlag: FeatureFlag;
+    pageViews: PageViews;
+    sessions: Sessions;
+    events: Events;
+    identify: Identify;
+    funnels: Funnels;
+    products: Products;
+    cart: CartTracking;
+    checkout: Checkout;
+    purchases: Purchases;
+    trackEvent: (name: string, properties?: Record<string, unknown>) => Promise<void>;
+    identifyUser: (userId: string, traits?: Record<string, unknown>) => Promise<void>;
+    isReady: boolean;
+}
+export interface FlowGridProviderProps extends FlowGridConfig {
+    children: ReactNode;
+}
+/**
+ * FlowGrid Provider - Wrap your app to enable analytics.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   usePageView(); // Tracks on every route change
+ *   return <Routes />;
+ * }
+ * ```
+ */
+export declare function usePageView(pageName?: string): void;
+/**
+ * Track an event when component mounts.
+ *
+ * @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.
+ *
+ * @example
+ * ```tsx
+ * function CheckoutPage() {
+ *   const { variant, isLoading } = useExperiment('checkout_v2', 'user_123');
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return variant === 'treatment'
+ *     ? <NewCheckout />
+ *     : <OldCheckout />;
+ * }
+ * ```
+ */
+export declare function useExperiment(experimentId: string, userId: string): {
+    variant: string | null;
+    isLoading: boolean;
+};
+/**
+ * Evaluate a feature flag.
+ *
+ * @example
+ * ```tsx
+ * function Dashboard() {
+ *   const { isEnabled, isLoading } = useFeatureFlag('new_dashboard', {
+ *     userId: 'user_123'
+ *   });
+ *
+ *   if (isLoading) return <Loading />;
+ *
+ *   return isEnabled ? <NewDashboard /> : <OldDashboard />;
+ * }
+ * ```
+ */
+export declare function useFeatureFlag(flagKey: string, context?: {
+    userId?: string;
+    [key: string]: unknown;
+}): {
+    isEnabled: boolean;
+    isLoading: boolean;
+};
+/**
+ * Track user identity.
+ *
+ * @example
+ * ```tsx
+ * function ProfilePage({ user }) {
+ *   useIdentify(user.id, {
+ *     email: user.email,
+ *     plan: user.plan
+ *   });
+ *
+ *   return <Profile />;
+ * }
+ * ```
+ */
+export declare function useIdentify(userId: string, traits?: Record<string, unknown>): void;
+/**
+ * Ecommerce tracking hooks.
+ *
+ * @example
+ * ```tsx
+ * function ProductPage({ product }) {
+ *   const { trackProductView, trackAddToCart } = useEcommerce();
+ *
+ *   useEffect(() => {
+ *     trackProductView(product);
+ *   }, [product]);
+ *
+ *   const handleAddToCart = () => {
+ *     trackAddToCart(product, 1);
+ *   };
+ *
+ *   return <button onClick={handleAddToCart}>Add to Cart</button>;
+ * }
+ * ```
+ */
+export declare function useEcommerce(): {
+    trackProductView: (product: {
+        id: string;
+        name: string;
+        price: number;
+        currency?: string;
+        category?: string;
+    }) => Promise<void>;
+    trackAddToCart: (product: {
+        id: string;
+        name: string;
+        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/index.d.ts

@@ -0,0 +1,275 @@
+/**
+ * @fileoverview FlowGrid SDK - Vue 3 Integration
+ * @module frameworks/vue
+ *
+ * @description
+ * Vue 3 composables and plugin for FlowGrid SDK.
+ * Uses Composition API for reactive state management.
+ *
+ * @example
+ * ```ts
+ * // main.ts
+ * import { createApp } from 'vue';
+ * import { FlowGridPlugin } from 'flowgrid-sdk/vue';
+ *
+ * const app = createApp(App);
+ * app.use(FlowGridPlugin, {
+ *   webId: 'your-web-id',
+ *   endpoint: 'https://api.flowgrid.io',
+ *   apiKey: 'your-api-key'
+ * });
+ * app.mount('#app');
+ * ```
+ */
+import { type App, type Ref } from 'vue';
+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;
+    autoTrackPageViews?: boolean;
+    autoTrackSessions?: boolean;
+    debug?: boolean;
+}
+export interface FlowGridInstance {
+    activation: Activation;
+    trackFeature: TrackFeature;
+    trackPrompt: TrackPrompt;
+    experiment: Experiment;
+    featureFlag: FeatureFlag;
+    pageViews: PageViews;
+    sessions: Sessions;
+    events: Events;
+    identify: Identify;
+    funnels: Funnels;
+    products: Products;
+    cart: CartTracking;
+    checkout: Checkout;
+    purchases: Purchases;
+    isReady: Ref<boolean>;
+    sessionId: Ref<string | null>;
+}
+/**
+ * Vue plugin for FlowGrid SDK.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { FlowGridPlugin } from 'flowgrid-sdk/vue';
+ *
+ * createApp(App)
+ *   .use(FlowGridPlugin, {
+ *     webId: 'web_123',
+ *     endpoint: 'https://api.flowgrid.io',
+ *     apiKey: 'key_abc',
+ *     autoTrackPageViews: true
+ *   })
+ *   .mount('#app');
+ * ```
+ */
+export declare const FlowGridPlugin: {
+    install(app: App, options: FlowGridConfig): void;
+};
+/**
+ * Access the FlowGrid SDK instance.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useFlowGrid } from 'flowgrid-sdk/vue';
+ *
+ * const { events, trackEvent } = useFlowGrid();
+ *
+ * const handleClick = () => {
+ *   trackEvent('button_clicked', { id: 'cta' });
+ * };
+ * </script>
+ * ```
+ */
+export declare function useFlowGrid(): {
+    trackEvent: (name: string, properties?: Record<string, unknown>) => Promise<void>;
+    identifyUser: (userId: string, traits?: Record<string, unknown>) => Promise<void>;
+    activation: Activation;
+    trackFeature: TrackFeature;
+    trackPrompt: TrackPrompt;
+    experiment: Experiment;
+    featureFlag: FeatureFlag;
+    pageViews: PageViews;
+    sessions: Sessions;
+    events: Events;
+    identify: Identify;
+    funnels: Funnels;
+    products: Products;
+    cart: CartTracking;
+    checkout: Checkout;
+    purchases: Purchases;
+    isReady: Ref<boolean>;
+    sessionId: Ref<string | null>;
+};
+/**
+ * Track page views with Vue Router integration.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { usePageView } from 'flowgrid-sdk/vue';
+ * import { useRoute } from 'vue-router';
+ *
+ * const route = useRoute();
+ * usePageView(() => route.path);
+ * </script>
+ * ```
+ */
+export declare function usePageView(pathGetter?: () => string): void;
+/**
+ * Track an event on component mount.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useTrackEvent } from 'flowgrid-sdk/vue';
+ *
+ * useTrackEvent('pricing_page_viewed', { source: 'navbar' });
+ * </script>
+ * ```
+ */
+export declare function useTrackEvent(eventName: string, properties?: Record<string, unknown>): void;
+/**
+ * Use an experiment variant.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useExperiment } from 'flowgrid-sdk/vue';
+ *
+ * const { variant, isLoading } = useExperiment('checkout_v2', 'user_123');
+ * </script>
+ *
+ * <template>
+ *   <NewCheckout v-if="variant === 'treatment'" />
+ *   <OldCheckout v-else />
+ * </template>
+ * ```
+ */
+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.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useIdentify } from 'flowgrid-sdk/vue';
+ *
+ * const props = defineProps<{ userId: string; email: string }>();
+ *
+ * useIdentify(() => props.userId, () => ({ email: props.email }));
+ * </script>
+ * ```
+ */
+export declare function useIdentify(userIdGetter: () => string | null, traitsGetter?: () => Record<string, unknown>): void;
+/**
+ * Ecommerce composable.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useEcommerce } from 'flowgrid-sdk/vue';
+ *
+ * const { trackProductView, trackAddToCart } = useEcommerce();
+ *
+ * onMounted(() => {
+ *   trackProductView(product);
+ * });
+ * </script>
+ * ```
+ */
+export declare function useEcommerce(): {
+    trackProductView: (product: {
+        id: string;
+        name: string;
+        price: number;
+        currency?: string;
+    }) => Promise<void>;
+    trackAddToCart: (product: {
+        id: string;
+        name: string;
+        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;
+};
+/**
+ * Vue Router plugin for automatic page view tracking.
+ *
+ * @example
+ * ```ts
+ * import { createRouter } from 'vue-router';
+ * import { createRouterPlugin } from 'flowgrid-sdk/vue';
+ *
+ * const router = createRouter({ ... });
+ * router.afterEach(createRouterPlugin());
+ * ```
+ */
+export declare function createRouterPlugin(): (to: {
+    path: string;
+    name?: string;
+}, from: {
+    path: string;
+}) => void;
+declare const _default: {
+    FlowGridPlugin: {
+        install(app: App, options: FlowGridConfig): void;
+    };
+    useFlowGrid: typeof useFlowGrid;
+    usePageView: typeof usePageView;
+    useTrackEvent: typeof useTrackEvent;
+    useExperiment: typeof useExperiment;
+    useFeatureFlag: typeof useFeatureFlag;
+    useIdentify: typeof useIdentify;
+    useEcommerce: typeof useEcommerce;
+    createRouterPlugin: typeof createRouterPlugin;
+};
+export default _default;