flowgrid-sdk 1.0.0

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

@@ -0,0 +1,232 @@
+/**
+ * @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 { FTRPC } from "../../client/ftrpc";
+import { Refund, CartItem, MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Configuration for tracking a refund.
+ */
+export interface RefundConfig extends Refund {
+    /** User ID */
+    userId?: string;
+    /** Initiated by (customer or admin) */
+    initiatedBy?: 'customer' | 'admin' | 'system';
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Refund event response from API.
+ */
+export interface RefundResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        refundId: string;
+        orderId: string;
+        tracked: boolean;
+        refundedAmount: number;
+    };
+    timestamp: string;
+}
+/**
+ * Refund analytics data for charts.
+ */
+export interface RefundAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalRefunds: number;
+        totalRefundValue: MoneyValue;
+        refundRate: number;
+        averageRefundValue: MoneyValue;
+        fullRefundCount: number;
+        partialRefundCount: number;
+    };
+    /** Refunds time series */
+    timeSeries: TimeSeriesData;
+    /** Refunds by reason */
+    byReason: Array<{
+        reason: string;
+        count: number;
+        totalValue: number;
+        percentage: number;
+    }>;
+    /** Products with highest refund rates */
+    topRefundedProducts: Array<{
+        productId: string;
+        productName: string;
+        refundCount: number;
+        refundValue: number;
+        refundRate: number;
+    }>;
+    /** Revenue impact */
+    revenueImpact: {
+        grossRevenue: MoneyValue;
+        refundedAmount: MoneyValue;
+        netRevenue: MoneyValue;
+        refundImpactPercent: number;
+    };
+}
+/**
+ * Refunds - Track refunds and returns.
+ *
+ * @extends FTRPC
+ *
+ * @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 declare class Refunds extends FTRPC {
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    track(config: RefundConfig): Promise<RefundResponse>;
+    /**
+     * 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
+     */
+    request(orderId: string, items?: CartItem[], reason?: string): Promise<RefundResponse>;
+    /**
+     * Tracks refund approval.
+     *
+     * @param refundId - Refund identifier
+     * @param approvedAmount - Approved refund amount
+     * @returns Promise resolving to approval response
+     */
+    approve(refundId: string, approvedAmount: number): Promise<RefundResponse>;
+    /**
+     * Tracks refund denial.
+     *
+     * @param refundId - Refund identifier
+     * @param denialReason - Reason for denial
+     * @returns Promise resolving to denial response
+     */
+    deny(refundId: string, denialReason: string): Promise<RefundResponse>;
+    /**
+     * Tracks refund completion (money returned).
+     *
+     * @param refundId - Refund identifier
+     * @param processedAmount - Amount actually refunded
+     * @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/search.d.ts

@@ -0,0 +1,225 @@
+/**
+ * @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 { FTRPC } from "../../client/ftrpc";
+import { Product, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Search query configuration.
+ */
+export interface SearchConfig {
+    /** Search query */
+    query: string;
+    /** Number of results */
+    resultsCount: number;
+    /** Search category/scope */
+    category?: string;
+    /** Applied filters */
+    filters?: Record<string, string | string[]>;
+    /** Sort order */
+    sortBy?: string;
+    /** Page number */
+    page?: number;
+    /** User ID */
+    userId?: string;
+    /** Session ID */
+    sessionId?: string;
+}
+/**
+ * Search result click configuration.
+ */
+export interface SearchClickConfig {
+    /** Original search query */
+    query: string;
+    /** Product clicked */
+    product: Product;
+    /** Position in results */
+    position: number;
+    /** Results page number */
+    page?: number;
+}
+/**
+ * Search response from API.
+ */
+export interface SearchResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        searchId: string;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Search analytics data.
+ */
+export interface SearchAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalSearches: number;
+        uniqueSearchers: number;
+        zeroResultSearches: number;
+        zeroResultRate: number;
+        avgResultsPerSearch: number;
+        searchToClickRate: number;
+        searchToConversionRate: number;
+    };
+    /** Top search queries */
+    topQueries: Array<{
+        query: string;
+        searches: number;
+        clicks: number;
+        conversions: number;
+        ctr: number;
+        conversionRate: number;
+    }>;
+    /** Zero-result queries */
+    zeroResultQueries: Array<{
+        query: string;
+        occurrences: number;
+        lastSearched: string;
+    }>;
+    /** Popular filters */
+    popularFilters: Array<{
+        filterName: string;
+        filterValue: string;
+        usageCount: number;
+    }>;
+    /** Search trends */
+    trends: TimeSeriesData;
+    /** Search to purchase funnel */
+    funnel: {
+        searches: number;
+        resultsViewed: number;
+        productClicked: number;
+        addedToCart: number;
+        purchased: number;
+    };
+}
+/**
+ * SearchAnalytics - Track site search behavior.
+ *
+ * @extends FTRPC
+ *
+ * @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 declare class SearchAnalytics extends FTRPC {
+    /**
+     * Tracks a search query.
+     *
+     * @param config - Search configuration
+     * @returns Promise resolving to search response
+     */
+    track(config: SearchConfig): Promise<SearchResponse>;
+    /**
+     * Tracks a click on search result.
+     *
+     * @param config - Search click configuration
+     * @returns Promise resolving to search response
+     */
+    trackClick(config: SearchClickConfig): Promise<SearchResponse>;
+    /**
+     * 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
+     */
+    trackRefinement(originalQuery: string, refinedQuery: string, refinementType: 'query_change' | 'add_filter' | 'remove_filter' | 'sort_change'): Promise<SearchResponse>;
+    /**
+     * Tracks autocomplete/suggestion selection.
+     *
+     * @param partialQuery - Partial query typed
+     * @param selectedSuggestion - Suggestion selected
+     * @param suggestionPosition - Position of suggestion
+     * @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;