flowgrid-sdk 1.0.0

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

@@ -0,0 +1,266 @@
+/**
+ * @fileoverview Ecommerce - Promotion Tracking
+ * @module features/ecommerce/promotions
+ *
+ * @description
+ * Track promotional content, coupon usage, and discount
+ * effectiveness across your ecommerce store.
+ *
+ * @useCases
+ * - Track promotional banner views
+ * - Measure promotion click-through rates
+ * - Analyze coupon usage and effectiveness
+ * - Monitor discount impact on revenue
+ * - Compare promotion performance
+ *
+ * @metrics
+ * - Promotion impressions
+ * - Promotion CTR
+ * - Coupon redemption rate
+ * - Revenue attributed to promotions
+ * - Discount impact on margins
+ *
+ * @chartData
+ * - Bar chart: Top promotions by revenue
+ * - Line chart: Coupon usage over time
+ * - Table: Promotion performance comparison
+ * - Pie chart: Revenue by promotion type
+ *
+ * @example
+ * ```typescript
+ * const promotions = new Promotions(webId, endpoint, apiKey);
+ *
+ * // Track promotion view
+ * await promotions.view({
+ *   promotionId: 'PROMO-SUMMER',
+ *   name: 'Summer Sale 20% Off',
+ *   creative: 'homepage-banner'
+ * });
+ *
+ * // Track coupon usage
+ * await promotions.couponUsed({
+ *   code: 'SAVE20',
+ *   discountValue: 20,
+ *   orderId: 'ORD-123'
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { Promotion, MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Configuration for tracking promotion view.
+ */
+export interface PromotionViewConfig extends Promotion {
+    /** User ID */
+    userId?: string;
+    /** Page where promotion was shown */
+    page?: string;
+}
+/**
+ * Configuration for tracking promotion click.
+ */
+export interface PromotionClickConfig extends Promotion {
+    /** User ID */
+    userId?: string;
+    /** Destination URL */
+    destinationUrl?: string;
+}
+/**
+ * Configuration for tracking coupon usage.
+ */
+export interface CouponUsageConfig {
+    /** Coupon code */
+    code: string;
+    /** Order ID where coupon was applied */
+    orderId: string;
+    /** Discount amount */
+    discountValue: number;
+    /** Discount type */
+    discountType: 'percentage' | 'fixed';
+    /** Order value before discount */
+    orderValueBefore: number;
+    /** Order value after discount */
+    orderValueAfter: number;
+    /** User ID */
+    userId?: string;
+}
+/**
+ * Promotion event response from API.
+ */
+export interface PromotionResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        promotionId: string;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Promotion analytics data for charts.
+ */
+export interface PromotionAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalPromotionViews: number;
+        totalPromotionClicks: number;
+        overallCTR: number;
+        totalCouponsUsed: number;
+        totalDiscountGiven: MoneyValue;
+        revenueFromPromotions: MoneyValue;
+    };
+    /** Top performing promotions */
+    topPromotions: Array<{
+        promotionId: string;
+        name: string;
+        views: number;
+        clicks: number;
+        ctr: number;
+        conversions: number;
+        revenue: number;
+    }>;
+    /** Coupon performance */
+    coupons: Array<{
+        code: string;
+        usageCount: number;
+        totalDiscount: number;
+        avgOrderValue: number;
+        conversionLift: number;
+    }>;
+    /** Promotions over time */
+    timeSeries: TimeSeriesData;
+    /** Revenue impact */
+    revenueImpact: {
+        promotedRevenue: MoneyValue;
+        nonPromotedRevenue: MoneyValue;
+        promotionRevenueShare: number;
+        avgDiscountPercent: number;
+    };
+}
+/**
+ * Promotions - Track promotions and coupons.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides promotion tracking capabilities including:
+ * - Promotion/banner impressions
+ * - Promotion clicks
+ * - Coupon applications
+ * - Coupon success/failure
+ * - Revenue attribution
+ *
+ * @example
+ * ```typescript
+ * const promotions = new Promotions(webId, endpoint, apiKey);
+ *
+ * // Track banner impression
+ * await promotions.view({
+ *   promotionId: 'FLASH-SALE',
+ *   name: 'Flash Sale - 30% Off',
+ *   creative: 'hero-banner',
+ *   position: 'homepage-top'
+ * });
+ *
+ * // Track banner click
+ * await promotions.click({
+ *   promotionId: 'FLASH-SALE',
+ *   name: 'Flash Sale - 30% Off',
+ *   destinationUrl: '/sale'
+ * });
+ * ```
+ */
+export declare class Promotions extends FTRPC {
+    /**
+     * Tracks promotion view/impression.
+     *
+     * @param config - Promotion view configuration
+     * @returns Promise resolving to promotion response
+     *
+     * @example
+     * ```typescript
+     * await promotions.view({
+     *   promotionId: 'SUMMER-2026',
+     *   name: 'Summer Collection Launch',
+     *   creative: 'collection-banner',
+     *   position: 'homepage-hero',
+     *   page: '/home'
+     * });
+     * ```
+     */
+    view(config: PromotionViewConfig): Promise<PromotionResponse>;
+    /**
+     * Tracks promotion click.
+     *
+     * @param config - Promotion click configuration
+     * @returns Promise resolving to promotion response
+     *
+     * @example
+     * ```typescript
+     * await promotions.click({
+     *   promotionId: 'SUMMER-2026',
+     *   name: 'Summer Collection Launch',
+     *   destinationUrl: '/collections/summer-2026'
+     * });
+     * ```
+     */
+    click(config: PromotionClickConfig): Promise<PromotionResponse>;
+    /**
+     * Tracks successful coupon usage.
+     *
+     * @param config - Coupon usage configuration
+     * @returns Promise resolving to coupon response
+     *
+     * @example
+     * ```typescript
+     * await promotions.couponUsed({
+     *   code: 'SAVE20',
+     *   orderId: 'ORD-12345',
+     *   discountValue: 20,
+     *   discountType: 'percentage',
+     *   orderValueBefore: 100,
+     *   orderValueAfter: 80
+     * });
+     * ```
+     */
+    couponUsed(config: CouponUsageConfig): Promise<PromotionResponse>;
+    /**
+     * Tracks coupon application attempt (including failures).
+     *
+     * @param code - Coupon code attempted
+     * @param success - Whether coupon was valid
+     * @param failureReason - Reason for failure (if failed)
+     * @returns Promise resolving to attempt response
+     */
+    couponAttempt(code: string, success: boolean, failureReason?: 'expired' | 'invalid' | 'minimum_not_met' | 'already_used' | 'not_applicable'): Promise<PromotionResponse>;
+    /**
+     * Retrieves promotion analytics for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to promotion analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await promotions.getAnalytics({
+     *   range: 'last30days'
+     * });
+     *
+     * // Bar chart - top promotions
+     * const topPromoChart = analytics.topPromotions.map(p => ({
+     *   name: p.name,
+     *   value: p.revenue
+     * }));
+     *
+     * // Table - coupon performance
+     * const couponTable = analytics.coupons;
+     *
+     * // Pie chart - promoted vs non-promoted revenue
+     * const revenuePie = [
+     *   { name: 'Promoted', value: analytics.revenueImpact.promotedRevenue.amount },
+     *   { name: 'Non-Promoted', value: analytics.revenueImpact.nonPromotedRevenue.amount }
+     * ];
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<PromotionAnalyticsData>;
+}
+export default Promotions;

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

@@ -0,0 +1,287 @@
+/**
+ * @fileoverview Ecommerce - Purchase/Transaction Tracking
+ * @module features/ecommerce/purchases
+ *
+ * @description
+ * Track completed purchases, transactions, and revenue with
+ * full order details and customer information.
+ *
+ * @useCases
+ * - Track completed purchases
+ * - Calculate revenue metrics
+ * - Monitor order values
+ * - Analyze purchase patterns
+ * - Track customer lifetime value
+ *
+ * @metrics
+ * - Total revenue
+ * - Number of orders
+ * - Average order value
+ * - Revenue per customer
+ * - Items per order
+ *
+ * @chartData
+ * - Line chart: Revenue over time
+ * - Bar chart: Revenue by product/category
+ * - KPI cards: Revenue, AOV, Orders
+ * - Table: Recent transactions
+ *
+ * @example
+ * ```typescript
+ * const purchases = new Purchases(webId, endpoint, apiKey);
+ *
+ * // Track a purchase
+ * await purchases.track({
+ *   order: {
+ *     orderId: 'ORD-12345',
+ *     items: orderItems,
+ *     total: 299.99,
+ *     currency: 'USD'
+ *   }
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { Order, ShippingInfo, MoneyValue, DateRangeFilter, TimeSeriesData, PaginationParams } from "../../types";
+/**
+ * Configuration for tracking a purchase.
+ */
+export interface PurchaseConfig {
+    /** Order details */
+    order: Order;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Attribution data */
+    attribution?: {
+        source?: string;
+        medium?: string;
+        campaign?: string;
+        affiliate?: string;
+    };
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Purchase event response from API.
+ */
+export interface PurchaseResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        orderId: string;
+        tracked: boolean;
+        revenue: number;
+        isFirstPurchase: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Revenue analytics data for charts.
+ */
+export interface RevenueAnalyticsData {
+    /** Revenue summary */
+    summary: {
+        totalRevenue: MoneyValue;
+        netRevenue: MoneyValue;
+        totalOrders: number;
+        averageOrderValue: MoneyValue;
+        itemsSold: number;
+        uniqueCustomers: number;
+        repeatPurchaseRate: number;
+    };
+    /** Revenue time series */
+    revenueTimeSeries: TimeSeriesData;
+    /** Orders time series */
+    ordersTimeSeries: TimeSeriesData;
+    /** Revenue by category */
+    byCategory: Array<{
+        category: string;
+        revenue: number;
+        orders: number;
+        percentage: number;
+    }>;
+    /** Revenue by product */
+    byProduct: Array<{
+        productId: string;
+        productName: string;
+        revenue: number;
+        unitsSold: number;
+    }>;
+    /** Revenue by geography */
+    byCountry: Array<{
+        country: string;
+        revenue: number;
+        orders: number;
+    }>;
+    /** Customer segments */
+    customerSegments: Array<{
+        segment: 'new' | 'returning' | 'vip';
+        customers: number;
+        revenue: number;
+        avgOrderValue: number;
+    }>;
+}
+/**
+ * Recent orders data.
+ */
+export interface RecentOrdersData {
+    orders: Array<{
+        orderId: string;
+        total: MoneyValue;
+        itemCount: number;
+        status: string;
+        createdAt: string;
+        customer?: {
+            userId: string;
+            isNew: boolean;
+        };
+    }>;
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        hasMore: boolean;
+    };
+}
+/**
+ * Purchases - Track completed purchases and revenue.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides purchase tracking capabilities including:
+ * - Purchase completion events
+ * - Revenue tracking
+ * - Order details capture
+ * - Customer LTV tracking
+ * - Attribution tracking
+ *
+ * @example
+ * ```typescript
+ * const purchases = new Purchases(webId, endpoint, apiKey);
+ *
+ * // Track completed purchase
+ * await purchases.track({
+ *   order: {
+ *     orderId: 'ORD-12345',
+ *     items: cartItems,
+ *     subtotal: 279.99,
+ *     discountTotal: 30.00,
+ *     shippingTotal: 9.99,
+ *     taxTotal: 26.00,
+ *     total: 285.98,
+ *     currency: 'USD',
+ *     shipping: { method: 'express', cost: 9.99 },
+ *     payment: { method: 'credit_card' }
+ *   },
+ *   userId: 'user_123'
+ * });
+ *
+ * // Get revenue analytics
+ * const revenue = await purchases.getRevenue({ range: 'thisMonth' });
+ * ```
+ */
+export declare class Purchases extends FTRPC {
+    /**
+     * Tracks a completed purchase.
+     *
+     * @param config - Purchase configuration
+     * @returns Promise resolving to purchase response
+     *
+     * @example
+     * ```typescript
+     * await purchases.track({
+     *   order: {
+     *     orderId: 'ORD-98765',
+     *     items: [
+     *       { productId: 'PROD-1', name: 'Widget', price: 29.99, quantity: 2, lineTotal: 59.98 }
+     *     ],
+     *     subtotal: 59.98,
+     *     discountTotal: 0,
+     *     shippingTotal: 5.99,
+     *     taxTotal: 5.40,
+     *     total: 71.37,
+     *     currency: 'USD'
+     *   },
+     *   attribution: {
+     *     source: 'google',
+     *     medium: 'cpc',
+     *     campaign: 'spring_sale'
+     *   }
+     * });
+     * ```
+     */
+    track(config: PurchaseConfig): Promise<PurchaseResponse>;
+    /**
+     * Tracks order status change.
+     *
+     * @param orderId - Order identifier
+     * @param newStatus - New order status
+     * @param previousStatus - Previous status (optional)
+     * @returns Promise resolving to status change response
+     */
+    statusChange(orderId: string, newStatus: Order['status'], previousStatus?: Order['status']): Promise<PurchaseResponse>;
+    /**
+     * Tracks order shipped event.
+     *
+     * @param orderId - Order identifier
+     * @param shipping - Shipping details with tracking
+     * @returns Promise resolving to shipped response
+     */
+    shipped(orderId: string, shipping: ShippingInfo): Promise<PurchaseResponse>;
+    /**
+     * Tracks order delivered event.
+     *
+     * @param orderId - Order identifier
+     * @param deliveredAt - Delivery timestamp
+     * @returns Promise resolving to delivered response
+     */
+    delivered(orderId: string, deliveredAt?: string): Promise<PurchaseResponse>;
+    /**
+     * Retrieves revenue analytics for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to revenue analytics
+     *
+     * @example
+     * ```typescript
+     * const revenue = await purchases.getRevenue({
+     *   range: 'last30days'
+     * });
+     *
+     * // KPI cards
+     * const kpis = [
+     *   { label: 'Revenue', value: revenue.summary.totalRevenue.amount },
+     *   { label: 'Orders', value: revenue.summary.totalOrders },
+     *   { label: 'AOV', value: revenue.summary.averageOrderValue.amount }
+     * ];
+     *
+     * // Revenue chart
+     * const revenueChart = revenue.revenueTimeSeries.data;
+     *
+     * // Category breakdown
+     * const categoryPie = revenue.byCategory.map(c => ({
+     *   name: c.category,
+     *   value: c.revenue
+     * }));
+     * ```
+     */
+    getRevenue(filter?: DateRangeFilter): Promise<RevenueAnalyticsData>;
+    /**
+     * Gets recent orders for display.
+     *
+     * @param pagination - Pagination options
+     * @returns Promise resolving to recent orders
+     */
+    getRecentOrders(pagination?: PaginationParams): Promise<RecentOrdersData>;
+    /**
+     * Gets order details by ID.
+     *
+     * @param orderId - Order identifier
+     * @returns Promise resolving to order details
+     */
+    getOrder(orderId: string): Promise<Order>;
+}
+export default Purchases;