flowgrid-sdk 1.0.0

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

@@ -0,0 +1,324 @@
+/**
+ * @fileoverview Ecommerce - Checkout Tracking
+ * @module features/ecommerce/checkout
+ *
+ * @description
+ * Track checkout flow progress, payment attempts, and checkout
+ * optimization opportunities.
+ *
+ * @useCases
+ * - Track checkout step progression
+ * - Identify checkout drop-off points
+ * - Monitor payment success rates
+ * - Analyze shipping method preferences
+ * - Optimize checkout UX
+ *
+ * @metrics
+ * - Checkout initiation rate
+ * - Step completion rates
+ * - Payment success rate
+ * - Checkout abandonment rate
+ * - Average time to complete
+ *
+ * @chartData
+ * - Funnel chart: Checkout steps
+ * - Bar chart: Abandonment by step
+ * - Pie chart: Payment methods
+ * - Line chart: Checkout completions over time
+ *
+ * @example
+ * ```typescript
+ * const checkout = new Checkout(webId, endpoint, apiKey);
+ *
+ * // Begin checkout
+ * await checkout.begin({
+ *   cart: shoppingCart,
+ *   userId: 'user_123'
+ * });
+ *
+ * // Track step progress
+ * await checkout.step({
+ *   step: 'add_payment_info',
+ *   stepNumber: 3,
+ *   cart: shoppingCart
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { Cart, CheckoutStep, ShippingInfo, PaymentInfo, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Configuration for beginning checkout.
+ */
+export interface BeginCheckoutConfig {
+    /** Cart being checked out */
+    cart: Cart;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Configuration for tracking checkout step.
+ */
+export interface CheckoutStepConfig {
+    /** Checkout step */
+    step: CheckoutStep;
+    /** Step number */
+    stepNumber: number;
+    /** Cart state at this step */
+    cart: Cart;
+    /** Option selected at this step (e.g., shipping method) */
+    option?: string;
+    /** User ID */
+    userId?: string;
+}
+/**
+ * Configuration for adding shipping info.
+ */
+export interface AddShippingConfig {
+    /** Cart being checked out */
+    cart: Cart;
+    /** Shipping information */
+    shipping: ShippingInfo;
+    /** User ID */
+    userId?: string;
+}
+/**
+ * Configuration for adding payment info.
+ */
+export interface AddPaymentConfig {
+    /** Cart being checked out */
+    cart: Cart;
+    /** Payment information (non-sensitive) */
+    payment: PaymentInfo;
+    /** User ID */
+    userId?: string;
+}
+/**
+ * Checkout event response from API.
+ */
+export interface CheckoutResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        checkoutId: string;
+        step: string;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Checkout analytics data for charts.
+ */
+export interface CheckoutAnalyticsData {
+    /** Checkout funnel data */
+    funnel: Array<{
+        step: CheckoutStep;
+        stepNumber: number;
+        started: number;
+        completed: number;
+        conversionRate: number;
+        dropOffRate: number;
+        avgTimeToComplete: number;
+    }>;
+    /** Summary metrics */
+    summary: {
+        checkoutsStarted: number;
+        checkoutsCompleted: number;
+        overallConversionRate: number;
+        avgCheckoutTime: number;
+        avgOrderValue: number;
+        abandonmentRate: number;
+    };
+    /** Checkouts over time */
+    timeSeries: TimeSeriesData;
+    /** Shipping methods used */
+    shippingMethods: Array<{
+        method: string;
+        count: number;
+        percentage: number;
+        avgShippingCost: number;
+    }>;
+    /** Payment methods used */
+    paymentMethods: Array<{
+        method: string;
+        count: number;
+        percentage: number;
+        successRate: number;
+    }>;
+    /** Abandonment analysis */
+    abandonmentByStep: Array<{
+        step: CheckoutStep;
+        abandonments: number;
+        percentage: number;
+        avgCartValue: number;
+    }>;
+}
+/**
+ * Checkout - Track checkout flow and payments.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides checkout tracking capabilities including:
+ * - Checkout initiation
+ * - Step-by-step progress
+ * - Shipping info capture
+ * - Payment info capture
+ * - Checkout abandonment
+ *
+ * @example
+ * ```typescript
+ * const checkout = new Checkout(webId, endpoint, apiKey);
+ *
+ * // Start checkout
+ * await checkout.begin({ cart: shoppingCart });
+ *
+ * // Track shipping step
+ * await checkout.addShipping({
+ *   cart: shoppingCart,
+ *   shipping: {
+ *     method: 'express',
+ *     carrier: 'FedEx',
+ *     cost: 9.99
+ *   }
+ * });
+ *
+ * // Track payment step
+ * await checkout.addPayment({
+ *   cart: shoppingCart,
+ *   payment: {
+ *     method: 'credit_card',
+ *     cardBrand: 'Visa'
+ *   }
+ * });
+ * ```
+ */
+export declare class Checkout extends FTRPC {
+    /**
+     * Tracks checkout initiation.
+     *
+     * @param config - Begin checkout configuration
+     * @returns Promise resolving to checkout response
+     *
+     * @example
+     * ```typescript
+     * await checkout.begin({
+     *   cart: {
+     *     cartId: 'cart_123',
+     *     items: cartItems,
+     *     total: 199.99,
+     *     currency: 'USD',
+     *     itemCount: 3
+     *   }
+     * });
+     * ```
+     */
+    begin(config: BeginCheckoutConfig): Promise<CheckoutResponse>;
+    /**
+     * Tracks checkout step progress.
+     *
+     * @param config - Checkout step configuration
+     * @returns Promise resolving to checkout response
+     *
+     * @example
+     * ```typescript
+     * await checkout.step({
+     *   step: 'add_shipping_info',
+     *   stepNumber: 2,
+     *   cart: shoppingCart,
+     *   option: 'express_shipping'
+     * });
+     * ```
+     */
+    step(config: CheckoutStepConfig): Promise<CheckoutResponse>;
+    /**
+     * Tracks adding shipping information.
+     *
+     * @param config - Shipping info configuration
+     * @returns Promise resolving to checkout response
+     *
+     * @example
+     * ```typescript
+     * await checkout.addShipping({
+     *   cart: shoppingCart,
+     *   shipping: {
+     *     method: 'standard',
+     *     carrier: 'USPS',
+     *     cost: 5.99,
+     *     estimatedDelivery: '2026-02-07'
+     *   }
+     * });
+     * ```
+     */
+    addShipping(config: AddShippingConfig): Promise<CheckoutResponse>;
+    /**
+     * Tracks adding payment information.
+     *
+     * @param config - Payment info configuration
+     * @returns Promise resolving to checkout response
+     *
+     * @example
+     * ```typescript
+     * await checkout.addPayment({
+     *   cart: shoppingCart,
+     *   payment: {
+     *     method: 'credit_card',
+     *     provider: 'Stripe',
+     *     cardBrand: 'Mastercard',
+     *     cardLast4: '4242'
+     *   }
+     * });
+     * ```
+     */
+    addPayment(config: AddPaymentConfig): Promise<CheckoutResponse>;
+    /**
+     * Tracks checkout abandonment.
+     *
+     * @param cart - Cart at abandonment
+     * @param step - Last completed step
+     * @param reason - Abandonment reason (if known)
+     * @returns Promise resolving to checkout response
+     */
+    abandon(cart: Cart, step: CheckoutStep, reason?: string): Promise<CheckoutResponse>;
+    /**
+     * Tracks payment attempt (success or failure).
+     *
+     * @param success - Whether payment succeeded
+     * @param cart - Cart being paid for
+     * @param payment - Payment information
+     * @param errorCode - Error code (if failed)
+     * @returns Promise resolving to checkout response
+     */
+    paymentAttempt(success: boolean, cart: Cart, payment: PaymentInfo, errorCode?: string): Promise<CheckoutResponse>;
+    /**
+     * Retrieves checkout analytics data for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to checkout analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await checkout.getAnalytics({
+     *   range: 'last30days'
+     * });
+     *
+     * // Funnel chart
+     * const funnelData = analytics.funnel.map(step => ({
+     *   name: step.step,
+     *   value: step.started,
+     *   conversion: step.conversionRate
+     * }));
+     *
+     * // Pie chart - payment methods
+     * const paymentData = analytics.paymentMethods.map(p => ({
+     *   name: p.method,
+     *   value: p.count
+     * }));
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<CheckoutAnalyticsData>;
+}
+export default Checkout;

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

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Ecommerce features barrel export
+ * @module features/ecommerce
+ */
+export { Products } from './products';
+export { CartTracking } from './cart';
+export { Checkout } from './checkout';
+export { Purchases } from './purchases';
+export { Refunds } from './refunds';
+export { Promotions } from './promotions';
+export { WishlistTracking } from './wishlist';
+export { CustomerLTV } from './ltv';
+export { SearchAnalytics } from './search';
+export { Inventory } from './inventory';
+export { Subscriptions } from './subscriptions';
+export type { ProductViewConfig, ProductImpressionConfig, ProductClickConfig, ProductResponse, ProductAnalyticsData } from './products';
+export type { AddToCartConfig, RemoveFromCartConfig, UpdateCartItemConfig, ViewCartConfig, CartResponse, CartAnalyticsData } from './cart';
+export type { BeginCheckoutConfig, CheckoutStepConfig, AddShippingConfig, AddPaymentConfig, CheckoutResponse, CheckoutAnalyticsData } from './checkout';
+export type { PurchaseConfig, PurchaseResponse, RevenueAnalyticsData, RecentOrdersData } from './purchases';
+export type { RefundConfig, RefundResponse, RefundAnalyticsData } from './refunds';
+export type { PromotionViewConfig, PromotionClickConfig, CouponUsageConfig, PromotionResponse, PromotionAnalyticsData } from './promotions';
+export type { AddToWishlistConfig, RemoveFromWishlistConfig, WishlistResponse, WishlistAnalyticsData } from './wishlist';
+export type { CustomerValueData, AcquisitionCostConfig, LTVResponse, LTVAnalyticsData } from './ltv';
+export type { SearchConfig, SearchClickConfig, SearchResponse, SearchAnalyticsData } from './search';
+export type { StockUpdateConfig, OutOfStockConfig, InventoryResponse, InventoryAnalyticsData } from './inventory';
+export type { SubscriptionStartConfig, SubscriptionChangeConfig, SubscriptionCancelConfig, SubscriptionResponse, SubscriptionAnalyticsData } from './subscriptions';

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

@@ -0,0 +1,221 @@
+/**
+ * @fileoverview Ecommerce - Inventory Tracking
+ * @module features/ecommerce/inventory
+ *
+ * @description
+ * Track inventory-related events for stock management insights
+ * and demand forecasting.
+ *
+ * @useCases
+ * - Track stock level changes
+ * - Monitor out-of-stock events
+ * - Analyze demand patterns
+ * - Track restock events
+ * - Correlate stock with lost sales
+ *
+ * @metrics
+ * - Out-of-stock rate
+ * - Stock turnover
+ * - Demand vs supply
+ * - Lost sales from stockouts
+ * - Restock frequency
+ *
+ * @chartData
+ * - Line chart: Stock levels over time
+ * - Bar chart: Products with low stock
+ * - Alert table: Out-of-stock products
+ * - Heatmap: Demand by product/time
+ *
+ * @example
+ * ```typescript
+ * const inventory = new Inventory(webId, endpoint, apiKey);
+ *
+ * // Track stock update
+ * await inventory.updateStock({
+ *   productId: 'PROD-123',
+ *   previousStock: 50,
+ *   newStock: 45,
+ *   reason: 'sale'
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Stock update configuration.
+ */
+export interface StockUpdateConfig {
+    /** Product ID */
+    productId: string;
+    /** Product name */
+    productName?: string;
+    /** Stock before change */
+    previousStock: number;
+    /** Stock after change */
+    newStock: number;
+    /** Reason for change */
+    reason: 'sale' | 'restock' | 'return' | 'adjustment' | 'damage' | 'transfer';
+    /** Location/warehouse */
+    location?: string;
+}
+/**
+ * Out-of-stock event configuration.
+ */
+export interface OutOfStockConfig {
+    /** Product ID */
+    productId: string;
+    /** Product name */
+    productName?: string;
+    /** Whether there was demand (user tried to buy) */
+    hadDemand: boolean;
+    /** Number of users who viewed while out of stock */
+    viewsWhileOOS?: number;
+    /** Expected restock date */
+    expectedRestock?: string;
+}
+/**
+ * Inventory response from API.
+ */
+export interface InventoryResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        productId: string;
+        tracked: boolean;
+        currentStock: number;
+    };
+    timestamp: string;
+}
+/**
+ * Inventory analytics data.
+ */
+export interface InventoryAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalProducts: number;
+        inStockProducts: number;
+        outOfStockProducts: number;
+        lowStockProducts: number;
+        outOfStockRate: number;
+        avgStockLevel: number;
+        estimatedLostSales: number;
+    };
+    /** Out of stock products */
+    outOfStock: Array<{
+        productId: string;
+        productName: string;
+        daysSinceOOS: number;
+        demandWhileOOS: number;
+        estimatedLostRevenue: number;
+    }>;
+    /** Low stock alerts */
+    lowStock: Array<{
+        productId: string;
+        productName: string;
+        currentStock: number;
+        reorderPoint: number;
+        avgDailySales: number;
+        daysOfStockLeft: number;
+    }>;
+    /** Stock turnover by product */
+    turnover: Array<{
+        productId: string;
+        productName: string;
+        turnoverRate: number;
+        avgStockLevel: number;
+        totalSold: number;
+    }>;
+    /** Stock levels over time */
+    trends: TimeSeriesData;
+}
+/**
+ * Inventory - Track inventory and stock events.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides inventory tracking including:
+ * - Stock level updates
+ * - Out-of-stock events
+ * - Restock tracking
+ * - Lost sales from stockouts
+ * - Demand forecasting data
+ *
+ * @example
+ * ```typescript
+ * const inventory = new Inventory(webId, endpoint, apiKey);
+ *
+ * // Track sale reducing stock
+ * await inventory.updateStock({
+ *   productId: 'SKU-123',
+ *   previousStock: 25,
+ *   newStock: 23,
+ *   reason: 'sale'
+ * });
+ *
+ * // Track out of stock
+ * await inventory.outOfStock({
+ *   productId: 'SKU-456',
+ *   productName: 'Popular Widget',
+ *   hadDemand: true,
+ *   viewsWhileOOS: 150
+ * });
+ * ```
+ */
+export declare class Inventory extends FTRPC {
+    /**
+     * Tracks stock level update.
+     *
+     * @param config - Stock update configuration
+     * @returns Promise resolving to inventory response
+     */
+    updateStock(config: StockUpdateConfig): Promise<InventoryResponse>;
+    /**
+     * Tracks out-of-stock event.
+     *
+     * @param config - Out-of-stock configuration
+     * @returns Promise resolving to inventory response
+     */
+    outOfStock(config: OutOfStockConfig): Promise<InventoryResponse>;
+    /**
+     * Tracks restock event.
+     *
+     * @param productId - Product ID
+     * @param quantity - Quantity restocked
+     * @param newTotal - New total stock
+     * @returns Promise resolving to inventory response
+     */
+    restock(productId: string, quantity: number, newTotal: number): Promise<InventoryResponse>;
+    /**
+     * Tracks back-in-stock notification request.
+     *
+     * @param productId - Product ID
+     * @param userId - User requesting notification
+     * @returns Promise resolving to inventory response
+     */
+    notifyRequest(productId: string, userId?: string): Promise<InventoryResponse>;
+    /**
+     * Gets inventory analytics for dashboards.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to inventory analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await inventory.getAnalytics({
+     *   range: 'last30days'
+     * });
+     *
+     * // Alert table - out of stock
+     * const alerts = analytics.outOfStock;
+     *
+     * // Low stock warnings
+     * const warnings = analytics.lowStock;
+     *
+     * // Lost sales estimate
+     * const lostSales = analytics.summary.estimatedLostSales;
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<InventoryAnalyticsData>;
+}
+export default Inventory;