flowgrid-sdk 1.0.0

package/dist/lib/features/ecommerce/ltv.d.ts

@@ -0,0 +1,258 @@
+/**
+ * @fileoverview Ecommerce - Customer Lifetime Value (LTV)
+ * @module features/ecommerce/ltv
+ *
+ * @description
+ * Calculate and track customer lifetime value to understand
+ * customer worth and optimize acquisition costs.
+ *
+ * @useCases
+ * - Calculate customer LTV
+ * - Segment customers by value
+ * - Track LTV trends over time
+ * - Identify high-value customers
+ * - Optimize acquisition spend (LTV:CAC)
+ *
+ * @metrics
+ * - Average LTV
+ * - LTV by cohort
+ * - LTV by segment
+ * - LTV:CAC ratio
+ * - Customer value distribution
+ *
+ * @chartData
+ * - Line chart: LTV by cohort over time
+ * - Bar chart: LTV by segment
+ * - Histogram: Customer value distribution
+ * - KPI: Average LTV, LTV:CAC
+ *
+ * @example
+ * ```typescript
+ * const ltv = new CustomerLTV(webId, endpoint, apiKey);
+ *
+ * // Get customer LTV
+ * const customerValue = await ltv.getCustomerValue('user_123');
+ *
+ * // Get LTV analytics
+ * const analytics = await ltv.getAnalytics({ range: 'last90days' });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Customer value data.
+ */
+export interface CustomerValueData {
+    /** Customer/user ID */
+    userId: string;
+    /** Total revenue from customer */
+    totalRevenue: MoneyValue;
+    /** Number of orders */
+    orderCount: number;
+    /** Average order value */
+    averageOrderValue: MoneyValue;
+    /** Predicted future value */
+    predictedLTV: MoneyValue;
+    /** Customer segment */
+    segment: 'low' | 'medium' | 'high' | 'vip';
+    /** Days since first purchase */
+    customerAge: number;
+    /** Days since last purchase */
+    daysSinceLastPurchase: number;
+    /** Purchase frequency (orders per month) */
+    purchaseFrequency: number;
+}
+/**
+ * Configuration for recording acquisition cost.
+ */
+export interface AcquisitionCostConfig {
+    /** Customer/user ID */
+    userId: string;
+    /** Acquisition cost */
+    cost: MoneyValue;
+    /** Acquisition channel */
+    channel: string;
+    /** Campaign (if applicable) */
+    campaign?: string;
+}
+/**
+ * LTV event response from API.
+ */
+export interface LTVResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        userId: string;
+        ltv: number;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * LTV analytics data for charts.
+ */
+export interface LTVAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        averageLTV: MoneyValue;
+        medianLTV: MoneyValue;
+        totalCustomerValue: MoneyValue;
+        averageCAC: MoneyValue;
+        ltvCacRatio: number;
+        averageOrderValue: MoneyValue;
+        averageOrdersPerCustomer: number;
+    };
+    /** LTV by customer segment */
+    bySegment: Array<{
+        segment: string;
+        customerCount: number;
+        averageLTV: MoneyValue;
+        totalRevenue: MoneyValue;
+        percentageOfCustomers: number;
+        percentageOfRevenue: number;
+    }>;
+    /** LTV by cohort */
+    byCohort: Array<{
+        cohort: string;
+        customerCount: number;
+        averageLTV: MoneyValue;
+        ltvProgression: number[];
+    }>;
+    /** LTV by acquisition channel */
+    byChannel: Array<{
+        channel: string;
+        customers: number;
+        averageLTV: MoneyValue;
+        averageCAC: MoneyValue;
+        ltvCacRatio: number;
+        roi: number;
+    }>;
+    /** LTV distribution */
+    distribution: Array<{
+        range: string;
+        count: number;
+        percentage: number;
+    }>;
+    /** LTV trend over time */
+    trendData: TimeSeriesData;
+}
+/**
+ * CustomerLTV - Calculate and track customer lifetime value.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides LTV tracking capabilities including:
+ * - Customer value calculation
+ * - Acquisition cost tracking
+ * - LTV:CAC ratio analysis
+ * - Customer segmentation by value
+ * - Cohort-based LTV analysis
+ *
+ * @example
+ * ```typescript
+ * const ltv = new CustomerLTV(webId, endpoint, apiKey);
+ *
+ * // Get individual customer value
+ * const value = await ltv.getCustomerValue('user_123');
+ * console.log(`LTV: $${value.totalRevenue.amount / 100}`);
+ *
+ * // Record acquisition cost
+ * await ltv.recordAcquisitionCost({
+ *   userId: 'user_123',
+ *   cost: { amount: 5000, currency: 'USD' },
+ *   channel: 'facebook_ads',
+ *   campaign: 'spring_campaign'
+ * });
+ *
+ * // Get LTV analytics
+ * const analytics = await ltv.getAnalytics();
+ * console.log(`LTV:CAC Ratio: ${analytics.summary.ltvCacRatio}`);
+ * ```
+ */
+export declare class CustomerLTV extends FTRPC {
+    /**
+     * Gets lifetime value data for a specific customer.
+     *
+     * @param userId - Customer/user identifier
+     * @returns Promise resolving to customer value data
+     *
+     * @example
+     * ```typescript
+     * const value = await ltv.getCustomerValue('user_123');
+     *
+     * console.log(`Total Revenue: $${value.totalRevenue.amount / 100}`);
+     * console.log(`Orders: ${value.orderCount}`);
+     * console.log(`Segment: ${value.segment}`);
+     * console.log(`Predicted LTV: $${value.predictedLTV.amount / 100}`);
+     * ```
+     */
+    getCustomerValue(userId: string): Promise<CustomerValueData>;
+    /**
+     * Records customer acquisition cost.
+     *
+     * @param config - Acquisition cost configuration
+     * @returns Promise resolving to LTV response
+     *
+     * @example
+     * ```typescript
+     * await ltv.recordAcquisitionCost({
+     *   userId: 'user_123',
+     *   cost: { amount: 2500, currency: 'USD' }, // $25.00
+     *   channel: 'google_ads',
+     *   campaign: 'brand_terms'
+     * });
+     * ```
+     */
+    recordAcquisitionCost(config: AcquisitionCostConfig): Promise<LTVResponse>;
+    /**
+     * Updates customer segment based on value.
+     *
+     * @param userId - Customer/user identifier
+     * @param segment - New segment
+     * @returns Promise resolving to LTV response
+     */
+    updateSegment(userId: string, segment: 'low' | 'medium' | 'high' | 'vip'): Promise<LTVResponse>;
+    /**
+     * Gets high-value customers.
+     *
+     * @param limit - Number of customers to return
+     * @returns Promise resolving to list of high-value customers
+     */
+    getTopCustomers(limit?: number): Promise<CustomerValueData[]>;
+    /**
+     * Retrieves LTV analytics for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to LTV analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await ltv.getAnalytics({
+     *   range: 'last90days'
+     * });
+     *
+     * // KPI cards
+     * const kpis = [
+     *   { label: 'Avg LTV', value: analytics.summary.averageLTV.amount },
+     *   { label: 'LTV:CAC', value: analytics.summary.ltvCacRatio },
+     *   { label: 'Avg AOV', value: analytics.summary.averageOrderValue.amount }
+     * ];
+     *
+     * // Bar chart - LTV by channel
+     * const channelChart = analytics.byChannel.map(c => ({
+     *   name: c.channel,
+     *   ltv: c.averageLTV.amount,
+     *   cac: c.averageCAC.amount
+     * }));
+     *
+     * // Histogram - value distribution
+     * const distribution = analytics.distribution.map(d => ({
+     *   range: d.range,
+     *   count: d.count
+     * }));
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<LTVAnalyticsData>;
+}
+export default CustomerLTV;

package/dist/lib/features/ecommerce/products.d.ts

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview Ecommerce - Product Tracking
+ * @module features/ecommerce/products
+ *
+ * @description
+ * Track product interactions including views, impressions, clicks,
+ * and product list interactions.
+ *
+ * @useCases
+ * - Track product page views
+ * - Measure product list/search impressions
+ * - Analyze product click-through rates
+ * - Monitor product detail engagement
+ * - Compare product performance
+ *
+ * @metrics
+ * - Product views
+ * - Product impressions
+ * - Click-through rate
+ * - View-to-cart rate
+ * - Revenue per product
+ *
+ * @chartData
+ * - Bar chart: Top products by views
+ * - Line chart: Product views over time
+ * - Table: Product performance comparison
+ * - Scatter: Price vs conversion rate
+ *
+ * @example
+ * ```typescript
+ * const products = new Products(webId, endpoint, apiKey);
+ *
+ * // Track product view
+ * await products.view({
+ *   productId: 'SKU-123',
+ *   name: 'Premium Headphones',
+ *   price: 299.99,
+ *   currency: 'USD',
+ *   category: 'Electronics/Audio'
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { Product, ProductList, ProductPerformance, DateRangeFilter, PaginationParams, TimeSeriesData } from "../../types";
+/**
+ * Configuration for tracking a product view.
+ */
+export interface ProductViewConfig extends Product {
+    /** User ID (if authenticated) */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** How user arrived at product (search, category, recommendation) */
+    source?: 'search' | 'category' | 'recommendation' | 'direct' | 'ad';
+    /** Search query if from search */
+    searchQuery?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Configuration for tracking product impressions.
+ */
+export interface ProductImpressionConfig {
+    /** List information */
+    list: ProductList;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+}
+/**
+ * Configuration for tracking product clicks.
+ */
+export interface ProductClickConfig {
+    /** Product clicked */
+    product: Product;
+    /** List where product was clicked */
+    listId?: string;
+    /** Position in list */
+    position?: number;
+    /** User ID */
+    userId?: string;
+}
+/**
+ * Product event response from API.
+ */
+export interface ProductResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        productId: string;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Product analytics data for charts.
+ */
+export interface ProductAnalyticsData {
+    /** Top products by various metrics */
+    topProducts: {
+        byViews: ProductPerformance[];
+        byRevenue: ProductPerformance[];
+        byConversion: ProductPerformance[];
+    };
+    /** Product views time series */
+    viewsTimeSeries: TimeSeriesData;
+    /** Summary metrics */
+    summary: {
+        totalProductViews: number;
+        uniqueProductsViewed: number;
+        avgViewsPerProduct: number;
+        topCategory: string;
+        topBrand: string;
+    };
+    /** Performance by category */
+    byCategory: Array<{
+        category: string;
+        views: number;
+        revenue: number;
+        conversionRate: number;
+    }>;
+}
+/**
+ * Products - Track product interactions.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides product tracking capabilities including:
+ * - Product page views
+ * - Product list impressions
+ * - Product clicks from lists
+ * - Product detail interactions
+ * - Quick view tracking
+ *
+ * @example
+ * ```typescript
+ * const products = new Products(webId, endpoint, apiKey);
+ *
+ * // Track product page view
+ * await products.view({
+ *   productId: 'PROD-001',
+ *   name: 'Wireless Earbuds',
+ *   price: 79.99,
+ *   currency: 'USD',
+ *   category: 'Electronics/Audio',
+ *   brand: 'AudioTech'
+ * });
+ *
+ * // Track list impressions
+ * await products.impression({
+ *   list: {
+ *     listId: 'search-results',
+ *     listName: 'Search Results',
+ *     products: searchResults
+ *   }
+ * });
+ * ```
+ */
+export declare class Products extends FTRPC {
+    /**
+     * Tracks a product page view.
+     *
+     * @param config - Product view configuration
+     * @returns Promise resolving to product response
+     *
+     * @example
+     * ```typescript
+     * await products.view({
+     *   productId: 'SKU-12345',
+     *   name: 'Premium Widget',
+     *   price: 49.99,
+     *   currency: 'USD',
+     *   category: 'Widgets/Premium',
+     *   brand: 'WidgetCo',
+     *   source: 'search',
+     *   searchQuery: 'premium widget'
+     * });
+     * ```
+     */
+    view(config: ProductViewConfig): Promise<ProductResponse>;
+    /**
+     * Tracks product list impressions.
+     *
+     * @param config - Impression configuration
+     * @returns Promise resolving to impression response
+     *
+     * @example
+     * ```typescript
+     * // Track products shown in search results
+     * await products.impression({
+     *   list: {
+     *     listId: 'search-results',
+     *     listName: 'Search Results',
+     *     products: products.map((p, i) => ({ ...p, position: i + 1 }))
+     *   }
+     * });
+     * ```
+     */
+    impression(config: ProductImpressionConfig): Promise<ProductResponse>;
+    /**
+     * Tracks a product click from a list.
+     *
+     * @param config - Click configuration
+     * @returns Promise resolving to click response
+     *
+     * @example
+     * ```typescript
+     * await products.click({
+     *   product: selectedProduct,
+     *   listId: 'homepage-featured',
+     *   position: 3
+     * });
+     * ```
+     */
+    click(config: ProductClickConfig): Promise<ProductResponse>;
+    /**
+     * Tracks a quick view interaction (modal product view).
+     *
+     * @param product - Product being quick-viewed
+     * @param listId - List where quick view was triggered
+     * @returns Promise resolving to quick view response
+     */
+    quickView(product: Product, listId?: string): Promise<ProductResponse>;
+    /**
+     * Tracks product detail interaction (zoom, read reviews, etc.).
+     *
+     * @param productId - Product identifier
+     * @param action - Interaction type
+     * @param properties - Additional properties
+     * @returns Promise resolving to interaction response
+     */
+    interaction(productId: string, action: 'zoom' | 'read_reviews' | 'size_guide' | 'compare' | 'share' | 'notify_stock', properties?: Record<string, unknown>): Promise<ProductResponse>;
+    /**
+     * Retrieves product analytics data for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @param pagination - Pagination options
+     * @returns Promise resolving to product analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await products.getAnalytics({
+     *   range: 'last30days'
+     * });
+     *
+     * // Bar chart - top products by views
+     * const topByViews = analytics.topProducts.byViews.map(p => ({
+     *   name: p.product.name,
+     *   value: p.views
+     * }));
+     *
+     * // Line chart - views over time
+     * const viewsTrend = analytics.viewsTimeSeries.data;
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter, pagination?: PaginationParams): Promise<ProductAnalyticsData>;
+    /**
+     * Gets performance data for a specific product.
+     *
+     * @param productId - Product identifier
+     * @param filter - Date range filter
+     * @returns Promise resolving to product performance
+     */
+    getProductPerformance(productId: string, filter?: DateRangeFilter): Promise<ProductPerformance>;
+}
+export default Products;