flowgrid-sdk 1.0.0

package/dist/lib/frameworks/nextjs/server.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @fileoverview FlowGrid SDK - Next.js Server Utilities
+ * @module frameworks/nextjs/server
+ *
+ * @description
+ * Server-side utilities for Next.js API Routes, Server Actions,
+ * and Server Components.
+ *
+ * ⚠️ IMPORTANT: Never expose your API key on the client.
+ * Use environment variables without NEXT_PUBLIC_ prefix for server-only keys.
+ *
+ * @example
+ * ```ts
+ * // app/api/track/route.ts
+ * import { flowgrid } from 'flowgrid-sdk/nextjs/server';
+ *
+ * export async function POST(request: Request) {
+ *   const { event, properties } = await request.json();
+ *   await flowgrid.events.track({ name: event, properties });
+ *   return Response.json({ success: true });
+ * }
+ * ```
+ */
+import { Activation, TrackFeature, TrackPrompt, Experiment, FeatureFlag, PageViews, Sessions, Events, Identify, Funnels, Purchases, Subscriptions, CustomerLTV } from '../../../index';
+export interface ServerFlowGridConfig {
+    webId: string;
+    endpoint: string;
+    apiKey: string;
+}
+export interface ServerFlowGridInstance {
+    activation: Activation;
+    trackFeature: TrackFeature;
+    trackPrompt: TrackPrompt;
+    experiment: Experiment;
+    featureFlag: FeatureFlag;
+    pageViews: PageViews;
+    sessions: Sessions;
+    events: Events;
+    identify: Identify;
+    funnels: Funnels;
+    purchases: Purchases;
+    subscriptions: Subscriptions;
+    customerLTV: CustomerLTV;
+}
+/**
+ * Creates a server-side FlowGrid instance.
+ * Uses environment variables by default.
+ *
+ * @example
+ * ```ts
+ * // lib/flowgrid.ts
+ * import { createServerFlowGrid } from 'flowgrid-sdk/nextjs/server';
+ *
+ * export const flowgrid = createServerFlowGrid({
+ *   webId: process.env.FLOWGRID_WEB_ID!,
+ *   endpoint: process.env.FLOWGRID_ENDPOINT!,
+ *   apiKey: process.env.FLOWGRID_API_KEY!, // Server-only!
+ * });
+ * ```
+ */
+export declare function createServerFlowGrid(config: ServerFlowGridConfig): ServerFlowGridInstance;
+/**
+ * Get or create a singleton server instance.
+ * Uses environment variables.
+ */
+export declare function getServerFlowGrid(): ServerFlowGridInstance;
+export declare const flowgrid: {
+    readonly events: Events;
+    readonly identify: Identify;
+    readonly purchases: Purchases;
+    readonly subscriptions: Subscriptions;
+    readonly experiment: Experiment;
+    readonly featureFlag: FeatureFlag;
+    readonly activation: Activation;
+    readonly trackFeature: TrackFeature;
+    readonly trackPrompt: TrackPrompt;
+    readonly funnels: Funnels;
+    readonly customerLTV: CustomerLTV;
+};
+/**
+ * Track an event from an API route.
+ *
+ * @example
+ * ```ts
+ * // app/api/track/route.ts
+ * import { trackServerEvent } from 'flowgrid-sdk/nextjs/server';
+ *
+ * export async function POST(request: Request) {
+ *   const { event, properties, userId } = await request.json();
+ *
+ *   await trackServerEvent(event, properties, userId);
+ *
+ *   return Response.json({ success: true });
+ * }
+ * ```
+ */
+export declare function trackServerEvent(eventName: string, properties?: Record<string, unknown>, userId?: string): Promise<void>;
+/**
+ * Identify a user from server-side.
+ *
+ * @example
+ * ```ts
+ * // After user signs up
+ * await identifyServerUser(user.id, {
+ *   email: user.email,
+ *   plan: user.plan,
+ *   signupDate: new Date().toISOString()
+ * });
+ * ```
+ */
+export declare function identifyServerUser(userId: string, traits?: Record<string, unknown>): Promise<void>;
+/**
+ * Track a server-side purchase.
+ *
+ * @example
+ * ```ts
+ * // In your payment webhook handler
+ * await trackServerPurchase({
+ *   orderId: 'ORD-123',
+ *   userId: 'user_456',
+ *   revenue: 9999,
+ *   currency: 'USD',
+ *   items: [{ id: 'prod_1', name: 'Widget', price: 4999, quantity: 2 }]
+ * });
+ * ```
+ */
+export declare function trackServerPurchase(order: {
+    orderId: string;
+    userId?: string;
+    revenue: number;
+    currency?: string;
+    items: Array<{
+        id: string;
+        name: string;
+        price: number;
+        quantity: number;
+    }>;
+}): Promise<void>;
+/**
+ * Evaluate a feature flag server-side.
+ *
+ * @example
+ * ```ts
+ * // In a Server Component or API route
+ * const isEnabled = await evaluateServerFlag('new_feature', userId);
+ * ```
+ */
+export declare function evaluateServerFlag(flagKey: string, userId?: string, context?: Record<string, unknown>): Promise<boolean>;
+/**
+ * Get experiment variant server-side.
+ *
+ * @example
+ * ```ts
+ * // In a Server Component
+ * const variant = await getServerExperimentVariant('checkout_v2', userId);
+ * ```
+ */
+export declare function getServerExperimentVariant(experimentId: string, userId: string): Promise<string>;
+/**
+ * Create a tracked server action.
+ *
+ * @example
+ * ```ts
+ * // app/actions.ts
+ * 'use server';
+ * import { createTrackedAction } from 'flowgrid-sdk/nextjs/server';
+ *
+ * export const submitForm = createTrackedAction(
+ *   'form_submitted',
+ *   async (formData: FormData) => {
+ *     // Your action logic
+ *     return { success: true };
+ *   }
+ * );
+ * ```
+ */
+export declare function createTrackedAction<T extends (...args: any[]) => Promise<any>>(eventName: string, action: T, getProperties?: (...args: Parameters<T>) => Record<string, unknown>): T;
+declare const _default: {
+    createServerFlowGrid: typeof createServerFlowGrid;
+    getServerFlowGrid: typeof getServerFlowGrid;
+    flowgrid: {
+        readonly events: Events;
+        readonly identify: Identify;
+        readonly purchases: Purchases;
+        readonly subscriptions: Subscriptions;
+        readonly experiment: Experiment;
+        readonly featureFlag: FeatureFlag;
+        readonly activation: Activation;
+        readonly trackFeature: TrackFeature;
+        readonly trackPrompt: TrackPrompt;
+        readonly funnels: Funnels;
+        readonly customerLTV: CustomerLTV;
+    };
+    trackServerEvent: typeof trackServerEvent;
+    identifyServerUser: typeof identifyServerUser;
+    trackServerPurchase: typeof trackServerPurchase;
+    evaluateServerFlag: typeof evaluateServerFlag;
+    getServerExperimentVariant: typeof getServerExperimentVariant;
+    createTrackedAction: typeof createTrackedAction;
+};
+export default _default;

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

@@ -0,0 +1,265 @@
+/**
+ * @fileoverview FlowGrid SDK - Node.js Integration
+ * @module frameworks/node
+ *
+ * @description
+ * Node.js SDK for server-side event tracking.
+ * Use in Express, Fastify, Hono, or any Node.js backend.
+ *
+ * ⚠️ All operations are server-side. Never expose your API key.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * import { FlowGrid } from 'flowgrid-sdk/node';
+ *
+ * const flowgrid = new FlowGrid({
+ *   webId: process.env.FLOWGRID_WEB_ID!,
+ *   endpoint: process.env.FLOWGRID_ENDPOINT!,
+ *   apiKey: process.env.FLOWGRID_API_KEY!,
+ * });
+ *
+ * // Track event
+ * await flowgrid.track('user_signed_up', { userId: 'user_123' });
+ * ```
+ */
+import { Activation, TrackFeature, TrackPrompt, Experiment, FeatureFlag, Events, Identify, Funnels, Purchases, Refunds, Subscriptions, CustomerLTV, Inventory } from '../../../index';
+export interface FlowGridConfig {
+    webId: string;
+    endpoint: string;
+    apiKey: string;
+    /** Flush events in batches (default: true) */
+    batchEvents?: boolean;
+    /** Batch size before auto-flush (default: 100) */
+    batchSize?: number;
+    /** Flush interval in ms (default: 5000) */
+    flushInterval?: number;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+export interface EventData {
+    name: string;
+    properties?: Record<string, unknown>;
+    userId?: string;
+    timestamp?: string;
+}
+export interface UserTraits {
+    email?: string;
+    name?: string;
+    plan?: string;
+    [key: string]: unknown;
+}
+/**
+ * FlowGrid Node.js SDK.
+ *
+ * @example
+ * ```ts
+ * import { FlowGrid } from 'flowgrid-sdk/node';
+ *
+ * const flowgrid = new FlowGrid({
+ *   webId: process.env.FLOWGRID_WEB_ID!,
+ *   endpoint: process.env.FLOWGRID_ENDPOINT!,
+ *   apiKey: process.env.FLOWGRID_API_KEY!,
+ * });
+ *
+ * // Track events
+ * await flowgrid.track('order_placed', {
+ *   orderId: 'ORD-123',
+ *   userId: 'user_456',
+ *   value: 9999
+ * });
+ *
+ * // Identify users
+ * await flowgrid.identify('user_456', {
+ *   email: 'user@example.com',
+ *   plan: 'pro'
+ * });
+ *
+ * // Flush before shutdown
+ * await flowgrid.flush();
+ * ```
+ */
+export declare class FlowGrid {
+    private config;
+    private eventQueue;
+    private flushTimer;
+    readonly activation: Activation;
+    readonly trackFeature: TrackFeature;
+    readonly trackPrompt: TrackPrompt;
+    readonly experiment: Experiment;
+    readonly featureFlag: FeatureFlag;
+    readonly events: Events;
+    readonly identify: Identify;
+    readonly funnels: Funnels;
+    readonly purchases: Purchases;
+    readonly refunds: Refunds;
+    readonly subscriptions: Subscriptions;
+    readonly customerLTV: CustomerLTV;
+    readonly inventory: Inventory;
+    constructor(config: FlowGridConfig);
+    private log;
+    private startFlushTimer;
+    /**
+     * Track an event.
+     *
+     * @example
+     * ```ts
+     * await flowgrid.track('button_clicked', {
+     *   buttonId: 'cta',
+     *   userId: 'user_123'
+     * });
+     * ```
+     */
+    track(eventName: string, properties?: Record<string, unknown>): Promise<void>;
+    /**
+     * Identify a user with traits.
+     *
+     * @example
+     * ```ts
+     * await flowgrid.identifyUser('user_123', {
+     *   email: 'user@example.com',
+     *   plan: 'pro',
+     *   company: 'Acme Inc'
+     * });
+     * ```
+     */
+    identifyUser(userId: string, traits?: UserTraits): Promise<void>;
+    /**
+     * Alias one user ID to another.
+     *
+     * @example
+     * ```ts
+     * // After user logs in, link anonymous to known ID
+     * await flowgrid.alias('anon_abc123', 'user_456');
+     * ```
+     */
+    alias(previousId: string, newId: string): Promise<void>;
+    /**
+     * Flush all queued events.
+     * Call before process exit.
+     *
+     * @example
+     * ```ts
+     * // Before shutdown
+     * await flowgrid.flush();
+     * process.exit(0);
+     * ```
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown the SDK gracefully.
+     * Flushes remaining events and clears timers.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Track a purchase/order.
+     *
+     * @example
+     * ```ts
+     * await flowgrid.trackPurchase({
+     *   orderId: 'ORD-12345',
+     *   userId: 'user_123',
+     *   revenue: 9999, // in cents
+     *   currency: 'USD',
+     *   items: [
+     *     { id: 'prod_1', name: 'Widget', price: 4999, quantity: 2 }
+     *   ]
+     * });
+     * ```
+     */
+    trackPurchase(order: {
+        orderId: string;
+        userId?: string;
+        revenue: number;
+        currency?: string;
+        items: Array<{
+            id: string;
+            name: string;
+            price: number;
+            quantity: number;
+        }>;
+    }): Promise<void>;
+    /**
+     * Track a refund.
+     */
+    trackRefund(refund: {
+        refundId: string;
+        orderId: string;
+        amount: number;
+        currency: string;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Track a subscription start.
+     */
+    trackSubscriptionStart(sub: {
+        subscriptionId: string;
+        userId: string;
+        plan: string;
+        mrr: number;
+        currency?: string;
+        billingCycle?: 'monthly' | 'quarterly' | 'yearly';
+    }): Promise<void>;
+    /**
+     * Track a subscription cancellation.
+     */
+    trackSubscriptionCancel(sub: {
+        subscriptionId: string;
+        userId: string;
+        plan: string;
+        lostMrr: number;
+        currency?: string;
+        reason?: string;
+    }): Promise<void>;
+    /**
+     * Get experiment variant for a user.
+     */
+    getExperimentVariant(experimentId: string, userId: string): Promise<string>;
+    /**
+     * Evaluate a feature flag.
+     */
+    evaluateFlag(flagKey: string, userId?: string, defaultValue?: boolean): Promise<boolean>;
+}
+/**
+ * Express middleware for automatic request tracking.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { FlowGrid, expressMiddleware } from 'flowgrid-sdk/node';
+ *
+ * const app = express();
+ * const flowgrid = new FlowGrid({ ... });
+ *
+ * app.use(expressMiddleware(flowgrid));
+ * ```
+ */
+export declare function expressMiddleware(flowgrid: FlowGrid): (req: any, res: any, next: any) => Promise<void>;
+/**
+ * Graceful shutdown handler.
+ *
+ * @example
+ * ```ts
+ * import { FlowGrid, gracefulShutdown } from 'flowgrid-sdk/node';
+ *
+ * const flowgrid = new FlowGrid({ ... });
+ * gracefulShutdown(flowgrid);
+ * ```
+ */
+export declare function gracefulShutdown(flowgrid: FlowGrid): void;
+/**
+ * Create a FlowGrid instance.
+ *
+ * @example
+ * ```ts
+ * import { createFlowGrid } from 'flowgrid-sdk/node';
+ *
+ * const flowgrid = createFlowGrid({
+ *   webId: process.env.FLOWGRID_WEB_ID!,
+ *   endpoint: process.env.FLOWGRID_ENDPOINT!,
+ *   apiKey: process.env.FLOWGRID_API_KEY!,
+ * });
+ * ```
+ */
+export declare function createFlowGrid(config: FlowGridConfig): FlowGrid;
+export default FlowGrid;

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

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview FlowGrid SDK - Nuxt 3 Integration
+ * @module frameworks/nuxt
+ *
+ * @description
+ * Nuxt 3 plugin, composables, and server utilities for FlowGrid SDK.
+ * Supports both client-side and server-side tracking.
+ *
+ * ## File Structure
+ *
+ * ```
+ * your-nuxt-app/
+ * ├── plugins/
+ * │   └── flowgrid.client.ts   # Client-only plugin
+ * ├── server/
+ * │   └── utils/
+ * │       └── flowgrid.ts      # Server utilities
+ * └── composables/
+ *     └── useFlowGrid.ts       # Auto-imported composable
+ * ```
+ *
+ * @example
+ * ```ts
+ * // plugins/flowgrid.client.ts
+ * import { FlowGridPlugin } from 'flowgrid-sdk/nuxt';
+ *
+ * export default defineNuxtPlugin((nuxtApp) => {
+ *   nuxtApp.vueApp.use(FlowGridPlugin, {
+ *     webId: useRuntimeConfig().public.flowgridWebId,
+ *     endpoint: useRuntimeConfig().public.flowgridEndpoint,
+ *     apiKey: useRuntimeConfig().public.flowgridApiKey,
+ *   });
+ * });
+ * ```
+ */
+export * from '../vue/index';
+import { type Ref } from 'vue';
+import { Activation, TrackFeature, TrackPrompt, Experiment, FeatureFlag, PageViews, Sessions, Events, Identify, Funnels, Products, CartTracking, Checkout, Purchases, Subscriptions, CustomerLTV } from '../../../index';
+export interface NuxtFlowGridConfig {
+    webId: string;
+    endpoint: string;
+    apiKey: string;
+    autoTrackPageViews?: boolean;
+    autoTrackSessions?: boolean;
+    debug?: boolean;
+}
+/**
+ * Create FlowGrid Nuxt plugin.
+ *
+ * @example
+ * ```ts
+ * // plugins/flowgrid.client.ts
+ * import { createFlowGridPlugin } from 'flowgrid-sdk/nuxt';
+ *
+ * export default defineNuxtPlugin((nuxtApp) => {
+ *   const config = useRuntimeConfig();
+ *
+ *   const flowgrid = createFlowGridPlugin({
+ *     webId: config.public.flowgridWebId,
+ *     endpoint: config.public.flowgridEndpoint,
+ *     apiKey: config.public.flowgridApiKey,
+ *   });
+ *
+ *   return {
+ *     provide: {
+ *       flowgrid
+ *     }
+ *   };
+ * });
+ * ```
+ */
+export declare function createFlowGridPlugin(config: NuxtFlowGridConfig): {
+    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;
+    subscriptions: Subscriptions;
+    customerLTV: CustomerLTV;
+    isReady: Ref<boolean, boolean>;
+    sessionId: Ref<string | null, string | null>;
+};
+/**
+ * Composable for accessing FlowGrid in Nuxt.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * const { $flowgrid } = useNuxtApp();
+ * // Or use the provided composable
+ * const flowgrid = useNuxtFlowGrid();
+ *
+ * const handleClick = () => {
+ *   flowgrid.trackEvent('button_clicked');
+ * };
+ * </script>
+ * ```
+ */
+export declare function useNuxtFlowGrid(): any;
+/**
+ * Composable for route-aware page view tracking.
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * // In your app.vue or layout
+ * useNuxtPageView();
+ * </script>
+ * ```
+ */
+export declare function useNuxtPageView(): void;
+/**
+ * Server-side FlowGrid instance for Nuxt server routes.
+ *
+ * @example
+ * ```ts
+ * // server/utils/flowgrid.ts
+ * import { createServerFlowGrid } from 'flowgrid-sdk/nuxt';
+ *
+ * export const flowgrid = createServerFlowGrid({
+ *   webId: process.env.FLOWGRID_WEB_ID!,
+ *   endpoint: process.env.FLOWGRID_ENDPOINT!,
+ *   apiKey: process.env.FLOWGRID_API_KEY!,
+ * });
+ *
+ * // server/api/track.post.ts
+ * export default defineEventHandler(async (event) => {
+ *   const body = await readBody(event);
+ *   await flowgrid.events.track({ name: body.event, properties: body.properties });
+ *   return { success: true };
+ * });
+ * ```
+ */
+export declare function createServerFlowGrid(config: {
+    webId: string;
+    endpoint: string;
+    apiKey: string;
+}): {
+    activation: Activation;
+    trackFeature: TrackFeature;
+    trackPrompt: TrackPrompt;
+    experiment: Experiment;
+    featureFlag: FeatureFlag;
+    events: Events;
+    identify: Identify;
+    funnels: Funnels;
+    purchases: Purchases;
+    subscriptions: Subscriptions;
+    customerLTV: CustomerLTV;
+};
+/**
+ * Track event from Nuxt server route.
+ */
+export declare function trackNuxtServerEvent(flowgrid: ReturnType<typeof createServerFlowGrid>, eventName: string, properties?: Record<string, unknown>): Promise<void>;
+/**
+ * Wrap a Nuxt event handler with tracking.
+ *
+ * @example
+ * ```ts
+ * // server/api/checkout.post.ts
+ * import { withTracking } from 'flowgrid-sdk/nuxt';
+ *
+ * export default withTracking('checkout_api_called', async (event) => {
+ *   const body = await readBody(event);
+ *   // Your logic
+ *   return { success: true };
+ * });
+ * ```
+ */
+export declare function withTracking<T>(eventName: string, handler: (event: any) => Promise<T>): (event: any) => Promise<T>;
+declare const _default: {
+    createFlowGridPlugin: typeof createFlowGridPlugin;
+    useNuxtFlowGrid: typeof useNuxtFlowGrid;
+    useNuxtPageView: typeof useNuxtPageView;
+    createServerFlowGrid: typeof createServerFlowGrid;
+    trackNuxtServerEvent: typeof trackNuxtServerEvent;
+    withTracking: typeof withTracking;
+};
+export default _default;