flowgrid-sdk 1.2.0 → 1.3.0

package/dist/lib/features/ecommerce/purchases.js

@@ -0,0 +1,193 @@
+/**
+ * @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 { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// PURCHASES CLASS
+// ============================================================================
+/**
+ * Purchases - Track completed purchases and revenue.
+ *
+ * @extends FlowGridTransport
+ *
+ * @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'
+ * });
+ * ```
+ */
+export class Purchases extends FlowGridTransport {
+    /**
+     * 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'
+     *   }
+     * });
+     * ```
+     */
+    async track(config) {
+        const order = config.order;
+        return await this.init("purchase", {
+            type: "ecommerce",
+            subtype: "purchase",
+            order: {
+                orderId: order.orderId,
+                items: order.items,
+                subtotal: order.subtotal,
+                discountTotal: order.discountTotal,
+                shippingTotal: order.shippingTotal,
+                taxTotal: order.taxTotal,
+                total: order.total,
+                currency: order.currency,
+                shipping: order.shipping,
+                payment: order.payment,
+                coupons: order.coupons,
+                affiliation: order.affiliation
+            },
+            revenue: order.total,
+            itemCount: order.items.reduce((sum, i) => sum + i.quantity, 0),
+            userId: config.userId,
+            sessionId: config.sessionId,
+            attribution: config.attribution,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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
+     */
+    async statusChange(orderId, newStatus, previousStatus) {
+        return await this.init("order_status_change", {
+            type: "ecommerce",
+            subtype: "order_status_change",
+            orderId,
+            newStatus,
+            previousStatus,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks order shipped event.
+     *
+     * @param orderId - Order identifier
+     * @param shipping - Shipping details with tracking
+     * @returns Promise resolving to shipped response
+     */
+    async shipped(orderId, shipping) {
+        return await this.init("order_shipped", {
+            type: "ecommerce",
+            subtype: "order_shipped",
+            orderId,
+            shipping,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks order delivered event.
+     *
+     * @param orderId - Order identifier
+     * @param deliveredAt - Delivery timestamp
+     * @returns Promise resolving to delivered response
+     */
+    async delivered(orderId, deliveredAt) {
+        return await this.init("order_delivered", {
+            type: "ecommerce",
+            subtype: "order_delivered",
+            orderId,
+            deliveredAt: deliveredAt || new Date().toISOString(),
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default Purchases;
+//# sourceMappingURL=purchases.js.map

package/dist/lib/features/ecommerce/purchases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"purchases.js","sourceRoot":"","sources":["../../../../src/lib/features/ecommerce/purchases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA4H3D,+EAA+E;AAC/E,kBAAkB;AAClB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAO,SAAU,SAAQ,iBAAiB;IAC9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,CAAC,KAAK,CAAC,MAAsB;QAChC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAE3B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE;YACjC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE;gBACL,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,aAAa,EAAE,KAAK,CAAC,aAAa;gBAClC,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B;YACD,OAAO,EAAE,KAAK,CAAC,KAAK;YACpB,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC9D,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,GAAG,MAAM,CAAC,UAAU;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAChB,OAAe,EACf,SAA0B,EAC1B,cAAgC;QAEhC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE;YAC5C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,qBAAqB;YAC9B,OAAO;YACP,SAAS;YACT,cAAc;YACd,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,OAAe,EAAE,QAAsB;QACnD,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACtC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,eAAe;YACxB,OAAO;YACP,QAAQ;YACR,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,SAAS,CAAC,OAAe,EAAE,WAAoB;QACnD,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACxC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,iBAAiB;YAC1B,OAAO;YACP,WAAW,EAAE,WAAW,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CAEF;AAED,eAAe,SAAS,CAAC"}

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

@@ -42,7 +42,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { Refund, CartItem, MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
+import { Refund, CartItem, MoneyValue, TimeSeriesData } from "../../types";
 /**
  * Configuration for tracking a refund.
  */
@@ -202,31 +202,5 @@ export declare class Refunds extends FlowGridTransport {
      * @returns Promise resolving to completion response
      */
     complete(refundId: string, processedAmount: number): Promise<RefundResponse>;
-    /**
-     * Retrieves refund analytics for dashboards and charts.
-     *
-     * @param filter - Date range filter
-     * @returns Promise resolving to refund analytics
-     *
-     * @example
-     * ```typescript
-     * const analytics = await refunds.getAnalytics({
-     *   range: 'last30days'
-     * });
-     *
-     * // Bar chart - refunds by reason
-     * const reasonChart = analytics.byReason.map(r => ({
-     *   name: r.reason,
-     *   value: r.count
-     * }));
-     *
-     * // Table - problematic products
-     * const problemProducts = analytics.topRefundedProducts;
-     *
-     * // Revenue impact KPI
-     * const impact = analytics.revenueImpact.refundImpactPercent;
-     * ```
-     */
-    getAnalytics(filter?: DateRangeFilter): Promise<RefundAnalyticsData>;
 }
 export default Refunds;

package/dist/lib/features/ecommerce/refunds.js

@@ -0,0 +1,195 @@
+/**
+ * @fileoverview Ecommerce - Refund Tracking
+ * @module features/ecommerce/refunds
+ *
+ * @description
+ * Track refunds, returns, and order cancellations with
+ * reason analysis and revenue impact.
+ *
+ * @useCases
+ * - Track full and partial refunds
+ * - Analyze refund reasons
+ * - Monitor return rates by product
+ * - Calculate net revenue after refunds
+ * - Identify problematic products
+ *
+ * @metrics
+ * - Total refunds
+ * - Refund rate
+ * - Average refund value
+ * - Refunds by reason
+ * - Net revenue impact
+ *
+ * @chartData
+ * - Bar chart: Refunds by reason
+ * - Line chart: Refund trends
+ * - Table: Products with highest return rates
+ * - KPI: Refund rate vs benchmark
+ *
+ * @example
+ * ```typescript
+ * const refunds = new Refunds(webId, endpoint, apiKey);
+ *
+ * // Track a refund
+ * await refunds.track({
+ *   orderId: 'ORD-12345',
+ *   refundId: 'REF-001',
+ *   amount: 49.99,
+ *   currency: 'USD',
+ *   reason: 'defective',
+ *   isFullRefund: false
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// REFUNDS CLASS
+// ============================================================================
+/**
+ * Refunds - Track refunds and returns.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides refund tracking capabilities including:
+ * - Full refund tracking
+ * - Partial refund tracking
+ * - Refund reason analysis
+ * - Return rate monitoring
+ * - Revenue impact calculation
+ *
+ * @example
+ * ```typescript
+ * const refunds = new Refunds(webId, endpoint, apiKey);
+ *
+ * // Track full refund
+ * await refunds.track({
+ *   orderId: 'ORD-12345',
+ *   refundId: 'REF-001',
+ *   amount: 149.99,
+ *   currency: 'USD',
+ *   reason: 'customer_request',
+ *   isFullRefund: true
+ * });
+ *
+ * // Track partial refund with items
+ * await refunds.track({
+ *   orderId: 'ORD-12345',
+ *   refundId: 'REF-002',
+ *   items: [refundedItem],
+ *   amount: 49.99,
+ *   currency: 'USD',
+ *   reason: 'defective',
+ *   isFullRefund: false
+ * });
+ * ```
+ */
+export class Refunds extends FlowGridTransport {
+    /**
+     * Tracks a refund event.
+     *
+     * @param config - Refund configuration
+     * @returns Promise resolving to refund response
+     *
+     * @example
+     * ```typescript
+     * await refunds.track({
+     *   orderId: 'ORD-98765',
+     *   refundId: 'REF-123',
+     *   items: [
+     *     { productId: 'PROD-1', name: 'Widget', price: 29.99, quantity: 1, lineTotal: 29.99 }
+     *   ],
+     *   amount: 29.99,
+     *   currency: 'USD',
+     *   reason: 'wrong_item',
+     *   isFullRefund: false,
+     *   initiatedBy: 'customer'
+     * });
+     * ```
+     */
+    async track(config) {
+        return await this.init("refund", {
+            type: "ecommerce",
+            subtype: "refund",
+            orderId: config.orderId,
+            refundId: config.refundId,
+            items: config.items,
+            amount: config.amount,
+            currency: config.currency,
+            reason: config.reason,
+            isFullRefund: config.isFullRefund,
+            userId: config.userId,
+            initiatedBy: config.initiatedBy,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks a refund request (before processing).
+     *
+     * @param orderId - Original order ID
+     * @param items - Items requested for refund
+     * @param reason - Refund reason
+     * @returns Promise resolving to request response
+     */
+    async request(orderId, items, reason) {
+        return await this.init("refund_requested", {
+            type: "ecommerce",
+            subtype: "refund_requested",
+            orderId,
+            items,
+            reason,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks refund approval.
+     *
+     * @param refundId - Refund identifier
+     * @param approvedAmount - Approved refund amount
+     * @returns Promise resolving to approval response
+     */
+    async approve(refundId, approvedAmount) {
+        return await this.init("refund_approved", {
+            type: "ecommerce",
+            subtype: "refund_approved",
+            refundId,
+            approvedAmount,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks refund denial.
+     *
+     * @param refundId - Refund identifier
+     * @param denialReason - Reason for denial
+     * @returns Promise resolving to denial response
+     */
+    async deny(refundId, denialReason) {
+        return await this.init("refund_denied", {
+            type: "ecommerce",
+            subtype: "refund_denied",
+            refundId,
+            denialReason,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks refund completion (money returned).
+     *
+     * @param refundId - Refund identifier
+     * @param processedAmount - Amount actually refunded
+     * @returns Promise resolving to completion response
+     */
+    async complete(refundId, processedAmount) {
+        return await this.init("refund_completed", {
+            type: "ecommerce",
+            subtype: "refund_completed",
+            refundId,
+            processedAmount,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default Refunds;
+//# sourceMappingURL=refunds.js.map

package/dist/lib/features/ecommerce/refunds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refunds.js","sourceRoot":"","sources":["../../../../src/lib/features/ecommerce/refunds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAgF3D,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,MAAM,OAAO,OAAQ,SAAQ,iBAAiB;IAC5C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,KAAK,CAAC,MAAoB;QAC9B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC/B,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,QAAQ;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,GAAG,MAAM,CAAC,UAAU;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,CACX,OAAe,EACf,KAAkB,EAClB,MAAe;QAEf,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE;YACzC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,kBAAkB;YAC3B,OAAO;YACP,KAAK;YACL,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,QAAgB,EAAE,cAAsB;QACpD,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACxC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,iBAAiB;YAC1B,QAAQ;YACR,cAAc;YACd,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,QAAgB,EAAE,YAAoB;QAC/C,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACtC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,eAAe;YACxB,QAAQ;YACR,YAAY;YACZ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,QAAgB,EAAE,eAAuB;QACtD,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE;YACzC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,kBAAkB;YAC3B,QAAQ;YACR,eAAe;YACf,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CAEF;AAED,eAAe,OAAO,CAAC"}

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

@@ -39,7 +39,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { Product, DateRangeFilter, TimeSeriesData } from "../../types";
+import { Product, TimeSeriesData } from "../../types";
 /**
  * Search query configuration.
  */
@@ -198,28 +198,5 @@ export declare class SearchAnalytics extends FlowGridTransport {
      * @returns Promise resolving to search response
      */
     trackSuggestion(partialQuery: string, selectedSuggestion: string, suggestionPosition: number): Promise<SearchResponse>;
-    /**
-     * Gets search analytics for dashboards.
-     *
-     * @param filter - Date range filter
-     * @returns Promise resolving to search analytics
-     *
-     * @example
-     * ```typescript
-     * const analytics = await search.getAnalytics({
-     *   range: 'last30days'
-     * });
-     *
-     * // Word cloud data
-     * const wordCloud = analytics.topQueries.map(q => ({
-     *   text: q.query,
-     *   value: q.searches
-     * }));
-     *
-     * // Table - zero result queries to fix
-     * const toFix = analytics.zeroResultQueries;
-     * ```
-     */
-    getAnalytics(filter?: DateRangeFilter): Promise<SearchAnalyticsData>;
 }
 export default SearchAnalytics;

package/dist/lib/features/ecommerce/search.js

@@ -0,0 +1,156 @@
+/**
+ * @fileoverview Ecommerce - Search Analytics
+ * @module features/ecommerce/search
+ *
+ * @description
+ * Track site search behavior to improve product discovery
+ * and conversion from search results.
+ *
+ * @useCases
+ * - Track search queries and results
+ * - Identify zero-result searches
+ * - Measure search-to-purchase conversion
+ * - Analyze popular search terms
+ * - Optimize search suggestions
+ *
+ * @metrics
+ * - Search volume
+ * - Zero-result rate
+ * - Search refinement rate
+ * - Click-through rate from search
+ * - Conversion from search
+ *
+ * @chartData
+ * - Word cloud: Popular search terms
+ * - Bar chart: Top queries
+ * - Table: Zero-result queries
+ * - Funnel: Search to purchase
+ *
+ * @example
+ * ```typescript
+ * const search = new SearchAnalytics(webId, endpoint, apiKey);
+ *
+ * // Track search
+ * await search.track({
+ *   query: 'wireless headphones',
+ *   resultsCount: 42,
+ *   filters: { brand: 'Sony' }
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// SEARCH ANALYTICS CLASS
+// ============================================================================
+/**
+ * SearchAnalytics - Track site search behavior.
+ *
+ * @extends FlowGridTransport
+ *
+ * @description
+ * Provides search analytics including:
+ * - Search query tracking
+ * - Result click tracking
+ * - Zero-result detection
+ * - Search refinement tracking
+ * - Search to conversion analysis
+ *
+ * @example
+ * ```typescript
+ * const search = new SearchAnalytics(webId, endpoint, apiKey);
+ *
+ * // Track search
+ * await search.track({
+ *   query: 'running shoes',
+ *   resultsCount: 156,
+ *   filters: { size: '10', color: 'black' },
+ *   sortBy: 'price_asc'
+ * });
+ *
+ * // Track click from search results
+ * await search.trackClick({
+ *   query: 'running shoes',
+ *   product: clickedProduct,
+ *   position: 3
+ * });
+ * ```
+ */
+export class SearchAnalytics extends FlowGridTransport {
+    /**
+     * Tracks a search query.
+     *
+     * @param config - Search configuration
+     * @returns Promise resolving to search response
+     */
+    async track(config) {
+        return await this.init("site_search", {
+            type: "ecommerce",
+            subtype: "site_search",
+            query: config.query,
+            resultsCount: config.resultsCount,
+            hasResults: config.resultsCount > 0,
+            category: config.category,
+            filters: config.filters,
+            sortBy: config.sortBy,
+            page: config.page || 1,
+            userId: config.userId,
+            sessionId: config.sessionId,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks a click on search result.
+     *
+     * @param config - Search click configuration
+     * @returns Promise resolving to search response
+     */
+    async trackClick(config) {
+        return await this.init("search_result_click", {
+            type: "ecommerce",
+            subtype: "search_result_click",
+            query: config.query,
+            product: config.product,
+            position: config.position,
+            page: config.page || 1,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks search refinement (modifying search).
+     *
+     * @param originalQuery - Original search query
+     * @param refinedQuery - New/refined query
+     * @param refinementType - Type of refinement
+     * @returns Promise resolving to search response
+     */
+    async trackRefinement(originalQuery, refinedQuery, refinementType) {
+        return await this.init("search_refinement", {
+            type: "ecommerce",
+            subtype: "search_refinement",
+            originalQuery,
+            refinedQuery,
+            refinementType,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks autocomplete/suggestion selection.
+     *
+     * @param partialQuery - Partial query typed
+     * @param selectedSuggestion - Suggestion selected
+     * @param suggestionPosition - Position of suggestion
+     * @returns Promise resolving to search response
+     */
+    async trackSuggestion(partialQuery, selectedSuggestion, suggestionPosition) {
+        return await this.init("search_suggestion", {
+            type: "ecommerce",
+            subtype: "search_suggestion",
+            partialQuery,
+            selectedSuggestion,
+            suggestionPosition,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default SearchAnalytics;
+//# sourceMappingURL=search.js.map

package/dist/lib/features/ecommerce/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../../../src/lib/features/ecommerce/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAuG3D,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,eAAgB,SAAQ,iBAAiB;IACpD;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,MAAoB;QAC9B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE;YACpC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,aAAa;YACtB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,UAAU,EAAE,MAAM,CAAC,YAAY,GAAG,CAAC;YACnC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC;YACtB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,MAAyB;QACxC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,qBAAqB,EAAE;YAC5C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,qBAAqB;YAC9B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC;YACtB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,eAAe,CACnB,aAAqB,EACrB,YAAoB,EACpB,cAA+E;QAE/E,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC1C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,mBAAmB;YAC5B,aAAa;YACb,YAAY;YACZ,cAAc;YACd,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,eAAe,CACnB,YAAoB,EACpB,kBAA0B,EAC1B,kBAA0B;QAE1B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC1C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,mBAAmB;YAC5B,YAAY;YACZ,kBAAkB;YAClB,kBAAkB;YAClB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CAEF;AAED,eAAe,eAAe,CAAC"}

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

@@ -41,7 +41,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
+import { MoneyValue, TimeSeriesData } from "../../types";
 /**
  * Subscription start configuration.
  */
@@ -250,32 +250,5 @@ export declare class Subscriptions extends FlowGridTransport {
      * @returns Promise resolving to subscription response
      */
     trialExpired(subscriptionId: string, userId: string): Promise<SubscriptionResponse>;
-    /**
-     * Gets subscription analytics for dashboards.
-     *
-     * @param filter - Date range filter
-     * @returns Promise resolving to subscription analytics
-     *
-     * @example
-     * ```typescript
-     * const analytics = await subscriptions.getAnalytics({
-     *   range: 'thisMonth'
-     * });
-     *
-     * // KPI cards
-     * const kpis = [
-     *   { label: 'MRR', value: analytics.summary.totalMrr.amount },
-     *   { label: 'Churn Rate', value: analytics.summary.churnRate },
-     *   { label: 'NRR', value: analytics.summary.netRevenueRetention }
-     * ];
-     *
-     * // Waterfall chart
-     * const waterfall = analytics.mrrMovement;
-     *
-     * // MRR trend line
-     * const trend = analytics.mrrTrend.data;
-     * ```
-     */
-    getAnalytics(filter?: DateRangeFilter): Promise<SubscriptionAnalyticsData>;
 }
 export default Subscriptions;