flowgrid-sdk 1.0.0

package/dist/lib/features/enterprise/support.d.ts

@@ -0,0 +1,329 @@
+/**
+ * @fileoverview Enterprise - Customer Support & Experience Analytics
+ * @module features/enterprise/support
+ *
+ * @description
+ * Link support interactions to retention and conversion metrics.
+ * Track ticket volume, response times, and satisfaction scores.
+ *
+ * @useCases
+ * - Track support ticket volume
+ * - Monitor response and resolution times
+ * - Correlate CSAT/NPS with retention
+ * - Track feature complaints
+ * - Measure support impact on conversion
+ *
+ * @metrics
+ * - Ticket volume
+ * - Average response time
+ * - Average resolution time
+ * - CSAT score
+ * - First contact resolution rate
+ *
+ * @chartData
+ * - Line chart: Ticket volume over time
+ * - Bar chart: Tickets by category
+ * - Distribution: Resolution time
+ * - Correlation: Support vs retention
+ *
+ * @example
+ * ```typescript
+ * const support = new SupportAnalytics(webId, endpoint, apiKey);
+ *
+ * // Track support ticket
+ * await support.trackTicket({
+ *   ticketId: 'ticket_123',
+ *   userId: 'user_456',
+ *   category: 'billing',
+ *   priority: 'high'
+ * });
+ * ```
+ */
+import { EnterpriseFTRPC } from "../../client/enterprise-ftrpc";
+import { DateRangeFilter, TimeSeriesData, TimeGranularity } from "../../types";
+/**
+ * Ticket priority levels.
+ */
+export type TicketPriority = 'low' | 'medium' | 'high' | 'urgent';
+/**
+ * Ticket status.
+ */
+export type TicketStatus = 'open' | 'pending' | 'in_progress' | 'resolved' | 'closed';
+/**
+ * Support channel.
+ */
+export type SupportChannel = 'email' | 'chat' | 'phone' | 'social' | 'self_service' | 'other';
+/**
+ * Ticket creation configuration.
+ */
+export interface TicketConfig {
+    /** Ticket ID */
+    ticketId: string;
+    /** User ID */
+    userId: string;
+    /** Account/company ID */
+    accountId?: string;
+    /** Ticket subject */
+    subject: string;
+    /** Ticket category */
+    category: string;
+    /** Sub-category */
+    subCategory?: string;
+    /** Priority level */
+    priority: TicketPriority;
+    /** Support channel */
+    channel: SupportChannel;
+    /** Related feature (if any) */
+    featureId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Ticket update configuration.
+ */
+export interface TicketUpdateConfig {
+    /** Ticket ID */
+    ticketId: string;
+    /** New status */
+    status: TicketStatus;
+    /** Assigned agent ID */
+    agentId?: string;
+    /** Response time (ms) - first response */
+    responseTimeMs?: number;
+    /** Resolution time (ms) - time to resolve */
+    resolutionTimeMs?: number;
+    /** Number of interactions */
+    interactionCount?: number;
+}
+/**
+ * CSAT tracking configuration.
+ */
+export interface CSATConfig {
+    /** Ticket ID */
+    ticketId: string;
+    /** User ID */
+    userId: string;
+    /** CSAT score (1-5) */
+    score: number;
+    /** Feedback comment */
+    feedback?: string;
+    /** Agent ID */
+    agentId?: string;
+}
+/**
+ * Feature complaint configuration.
+ */
+export interface FeatureComplaintConfig {
+    /** User ID */
+    userId: string;
+    /** Feature ID */
+    featureId: string;
+    /** Complaint type */
+    complaintType: 'bug' | 'usability' | 'missing_feature' | 'performance' | 'other';
+    /** Description */
+    description?: string;
+    /** Severity */
+    severity: 'minor' | 'moderate' | 'major' | 'critical';
+    /** Associated ticket ID */
+    ticketId?: string;
+}
+/**
+ * Support analytics filter.
+ */
+export interface SupportAnalyticsFilter extends DateRangeFilter {
+    /** Filter by category */
+    category?: string;
+    /** Filter by priority */
+    priority?: TicketPriority;
+    /** Filter by channel */
+    channel?: SupportChannel;
+    /** Filter by status */
+    status?: TicketStatus;
+}
+/**
+ * Ticket analytics result.
+ */
+export interface TicketAnalytics {
+    /** Total tickets */
+    totalTickets: number;
+    /** Open tickets */
+    openTickets: number;
+    /** Resolved tickets */
+    resolvedTickets: number;
+    /** Average response time (ms) */
+    avgResponseTimeMs: number;
+    /** Average resolution time (ms) */
+    avgResolutionTimeMs: number;
+    /** First contact resolution rate */
+    fcrRate: number;
+    /** Average CSAT score */
+    avgCSAT: number;
+    /** Tickets by category */
+    byCategory: Array<{
+        category: string;
+        count: number;
+        percentage: number;
+    }>;
+    /** Tickets by priority */
+    byPriority: Array<{
+        priority: TicketPriority;
+        count: number;
+        percentage: number;
+    }>;
+    /** Tickets by channel */
+    byChannel: Array<{
+        channel: SupportChannel;
+        count: number;
+        percentage: number;
+    }>;
+}
+/**
+ * Support impact analysis.
+ */
+export interface SupportImpactAnalysis {
+    /** Correlation with retention */
+    retentionCorrelation: number;
+    /** Correlation with churn */
+    churnCorrelation: number;
+    /** Users with support tickets */
+    usersWithTickets: number;
+    /** Churn rate for users with tickets */
+    ticketUserChurnRate: number;
+    /** Churn rate for users without tickets */
+    noTicketUserChurnRate: number;
+    /** Impact of quick resolution on retention */
+    quickResolutionRetentionLift: number;
+}
+/**
+ * Feature complaint summary.
+ */
+export interface FeatureComplaintSummary {
+    /** Feature ID */
+    featureId: string;
+    /** Feature name */
+    featureName?: string;
+    /** Total complaints */
+    totalComplaints: number;
+    /** By complaint type */
+    byType: Array<{
+        type: string;
+        count: number;
+    }>;
+    /** By severity */
+    bySeverity: Array<{
+        severity: string;
+        count: number;
+    }>;
+    /** Trend direction */
+    trend: 'increasing' | 'stable' | 'decreasing';
+}
+/**
+ * Agent performance.
+ */
+export interface AgentPerformance {
+    agentId: string;
+    agentName?: string;
+    ticketsHandled: number;
+    avgResponseTimeMs: number;
+    avgResolutionTimeMs: number;
+    avgCSAT: number;
+    fcrRate: number;
+}
+/**
+ * Calculate first contact resolution rate.
+ */
+export declare function calculateFCRRate(resolvedFirstContact: number, totalResolved: number): number;
+/**
+ * Calculate average response time.
+ */
+export declare function calculateAvgResponseTime(responseTimes: number[]): number;
+/**
+ * Classify CSAT score.
+ */
+export declare function classifyCSAT(score: number): 'poor' | 'fair' | 'good' | 'excellent';
+/**
+ * Format duration in human-readable format.
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Customer support and experience analytics class.
+ */
+export declare class SupportAnalytics extends EnterpriseFTRPC {
+    /**
+     * Track new support ticket.
+     */
+    trackTicket(config: TicketConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Update ticket status.
+     */
+    updateTicket(config: TicketUpdateConfig): Promise<{
+        updated: boolean;
+    }>;
+    /**
+     * Track ticket response.
+     */
+    trackResponse(ticketId: string, agentId: string, responseTimeMs: number): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track ticket resolution.
+     */
+    trackResolution(ticketId: string, resolutionTimeMs: number, interactionCount: number): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track CSAT score.
+     */
+    trackCSAT(config: CSATConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Track feature complaint.
+     */
+    trackFeatureComplaint(config: FeatureComplaintConfig): Promise<{
+        tracked: boolean;
+    }>;
+    /**
+     * Get ticket analytics.
+     */
+    getAnalytics(filter?: SupportAnalyticsFilter): Promise<TicketAnalytics>;
+    /**
+     * Get support impact analysis.
+     */
+    getSupportImpact(filter?: DateRangeFilter): Promise<SupportImpactAnalysis>;
+    /**
+     * Get feature complaint summary.
+     */
+    getFeatureComplaints(featureId?: string, filter?: DateRangeFilter): Promise<FeatureComplaintSummary[]>;
+    /**
+     * Get agent performance.
+     */
+    getAgentPerformance(agentId?: string, filter?: DateRangeFilter): Promise<AgentPerformance[]>;
+    /**
+     * Get ticket trend.
+     */
+    getTicketTrend(filter?: SupportAnalyticsFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get CSAT trend.
+     */
+    getCSATTrend(filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
+    /**
+     * Get response time distribution.
+     */
+    getResponseTimeDistribution(filter?: DateRangeFilter): Promise<Array<{
+        bucket: string;
+        count: number;
+        percentage: number;
+    }>>;
+    /**
+     * Get user support history.
+     */
+    getUserSupportHistory(userId: string): Promise<{
+        totalTickets: number;
+        avgCSAT: number;
+        categories: string[];
+        lastTicketDate: string;
+    }>;
+}

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

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Framework Integrations Barrel Export
+ * @module frameworks
+ */
+export * as react from './react';
+export * as vue from './vue';
+export * as nextjs from './nextjs';
+export * as nuxt from './nuxt';
+export * as node from './node';

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

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview FlowGrid SDK - Next.js Client Components
+ * @module frameworks/nextjs/client
+ *
+ * @description
+ * Client-side components and hooks for Next.js.
+ * All exports require 'use client' directive.
+ *
+ * @example
+ * ```tsx
+ * // app/providers.tsx
+ * 'use client';
+ * import { FlowGridProvider } from 'flowgrid-sdk/nextjs/client';
+ *
+ * export function Providers({ children }) {
+ *   return (
+ *     <FlowGridProvider
+ *       webId={process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!}
+ *       endpoint={process.env.NEXT_PUBLIC_FLOWGRID_ENDPOINT!}
+ *       apiKey={process.env.NEXT_PUBLIC_FLOWGRID_API_KEY!}
+ *     >
+ *       {children}
+ *     </FlowGridProvider>
+ *   );
+ * }
+ * ```
+ */
+import { 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;
+    autoTrackPageViews?: boolean;
+    autoTrackSessions?: boolean;
+    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 for Next.js App Router.
+ * Use in a Client Component wrapper.
+ *
+ * @example
+ * ```tsx
+ * // app/providers.tsx
+ * 'use client';
+ *
+ * import { FlowGridProvider } from 'flowgrid-sdk/nextjs/client';
+ *
+ * export function Providers({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <FlowGridProvider
+ *       webId={process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!}
+ *       endpoint={process.env.NEXT_PUBLIC_FLOWGRID_ENDPOINT!}
+ *       apiKey={process.env.NEXT_PUBLIC_FLOWGRID_API_KEY!}
+ *     >
+ *       {children}
+ *     </FlowGridProvider>
+ *   );
+ * }
+ *
+ * // app/layout.tsx
+ * import { Providers } from './providers';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <Providers>{children}</Providers>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export declare function FlowGridProvider({ children, webId, endpoint, apiKey, autoTrackPageViews, autoTrackSessions, debug }: FlowGridProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the FlowGrid SDK instance.
+ */
+export declare function useFlowGrid(): FlowGridContextValue;
+/**
+ * Track an event.
+ *
+ * @example
+ * ```tsx
+ * 'use client';
+ *
+ * import { useTrackEvent } from 'flowgrid-sdk/nextjs/client';
+ *
+ * export function FeatureButton() {
+ *   const trackEvent = useTrackEvent();
+ *
+ *   return (
+ *     <button onClick={() => trackEvent('feature_clicked', { id: 'cta' })}>
+ *       Click me
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTrackEvent(): (name: string, properties?: Record<string, unknown>) => Promise<void>;
+/**
+ * Get experiment variant.
+ */
+export declare function useExperiment(experimentId: string, userId: string): {
+    variant: string | null;
+    isLoading: boolean;
+};
+/**
+ * Evaluate a feature flag.
+ */
+export declare function useFeatureFlag(flagKey: string, context?: {
+    userId?: string;
+}): {
+    isEnabled: boolean;
+    isLoading: boolean;
+};
+/**
+ * Identify user.
+ */
+export declare function useIdentify(userId: string | null, traits?: Record<string, unknown>): void;
+/**
+ * Ecommerce hooks.
+ */
+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>;
+    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;
+};
+/**
+ * Component to track page views in App Router.
+ * Add to your root layout.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { PageViewTracker } from 'flowgrid-sdk/nextjs/client';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <body>
+ *         <Providers>
+ *           <PageViewTracker />
+ *           {children}
+ *         </Providers>
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+export declare function PageViewTracker(): null;
+declare const _default: {
+    FlowGridProvider: typeof FlowGridProvider;
+    useFlowGrid: typeof useFlowGrid;
+    useTrackEvent: typeof useTrackEvent;
+    useExperiment: typeof useExperiment;
+    useFeatureFlag: typeof useFeatureFlag;
+    useIdentify: typeof useIdentify;
+    useEcommerce: typeof useEcommerce;
+    PageViewTracker: typeof PageViewTracker;
+};
+export default _default;

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

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview FlowGrid SDK - Next.js Integration
+ * @module frameworks/nextjs
+ *
+ * @description
+ * Next.js integration with proper App Router and Pages Router support.
+ * Includes Server Components, Client Components, and API Route helpers.
+ *
+ * ## File Organization
+ *
+ * ```
+ * flowgrid-sdk/nextjs
+ * ├── client.tsx     - Client components (use 'use client')
+ * ├── server.ts      - Server-side utilities (API routes, Server Components)
+ * └── index.ts       - Main exports
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Client Component
+ * 'use client';
+ * import { FlowGridProvider, useFlowGrid } from 'flowgrid-sdk/nextjs/client';
+ *
+ * // Server-side (API Route or Server Action)
+ * import { flowgrid } from 'flowgrid-sdk/nextjs/server';
+ * ```
+ */
+export * from './client';
+export * from './server';