flowgrid-sdk 1.0.0

package/dist/lib/features/core/track-prompt.d.ts

@@ -0,0 +1,247 @@
+/**
+ * @fileoverview Core - Prompt & AI Interaction Tracking
+ * @module features/core/track-prompt
+ *
+ * @description
+ * Track AI prompt interactions, completions, and user feedback
+ * for AI-powered features.
+ *
+ * @useCases
+ * - Track AI prompt submissions
+ * - Monitor response quality
+ * - Measure user satisfaction
+ * - Analyze prompt patterns
+ * - Optimize AI features
+ *
+ * @metrics
+ * - Prompts per user
+ * - Response acceptance rate
+ * - Average response time
+ * - User satisfaction score
+ * - Token usage
+ *
+ * @chartData
+ * - Line chart: Prompts over time
+ * - Bar chart: Prompts by category
+ * - Histogram: Response time distribution
+ * - Gauge: Satisfaction score
+ *
+ * @example
+ * ```typescript
+ * const trackPrompt = new TrackPrompt(webId, endpoint, apiKey);
+ *
+ * await trackPrompt.create({
+ *   eventName: 'ai_completion',
+ *   properties: {
+ *     promptType: 'code_suggestion',
+ *     accepted: true
+ *   }
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Base configuration for prompt events.
+ */
+export interface PromptConfig {
+    /** Event name */
+    eventName: string;
+    /** Event properties */
+    properties: Record<string, unknown>;
+}
+/**
+ * AI prompt submission configuration.
+ */
+export interface PromptSubmissionConfig {
+    /** Prompt ID */
+    promptId: string;
+    /** User ID */
+    userId?: string;
+    /** Prompt text (may be truncated/hashed for privacy) */
+    promptText?: string;
+    /** Prompt category/type */
+    promptType: string;
+    /** Model used */
+    model?: string;
+    /** Input token count */
+    inputTokens?: number;
+    /** Session/conversation ID */
+    conversationId?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * AI response configuration.
+ */
+export interface PromptResponseConfig {
+    /** Prompt ID */
+    promptId: string;
+    /** Response time (ms) */
+    responseTime: number;
+    /** Output token count */
+    outputTokens?: number;
+    /** Whether response completed */
+    completed: boolean;
+    /** Error if any */
+    error?: string;
+    /** Response quality (if auto-detected) */
+    qualityScore?: number;
+}
+/**
+ * User feedback on AI response.
+ */
+export interface PromptFeedbackConfig {
+    /** Prompt ID */
+    promptId: string;
+    /** User ID */
+    userId?: string;
+    /** Feedback type */
+    feedbackType: 'accepted' | 'rejected' | 'edited' | 'thumbs_up' | 'thumbs_down';
+    /** Rating (1-5) */
+    rating?: number;
+    /** User comment */
+    comment?: string;
+}
+/**
+ * Prompt tracking response.
+ */
+export interface PromptResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        tracked: boolean;
+        promptId?: string;
+    };
+    timestamp: string;
+}
+/**
+ * Prompt analytics data.
+ */
+export interface PromptAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalPrompts: number;
+        uniqueUsers: number;
+        avgResponseTime: number;
+        acceptanceRate: number;
+        avgSatisfactionScore: number;
+        totalTokensUsed: number;
+        errorRate: number;
+    };
+    /** Usage by prompt type */
+    byType: Array<{
+        promptType: string;
+        count: number;
+        acceptanceRate: number;
+        avgResponseTime: number;
+        avgTokens: number;
+    }>;
+    /** Usage by model */
+    byModel: Array<{
+        model: string;
+        count: number;
+        avgResponseTime: number;
+        errorRate: number;
+    }>;
+    /** Feedback breakdown */
+    feedback: {
+        accepted: number;
+        rejected: number;
+        edited: number;
+        thumbsUp: number;
+        thumbsDown: number;
+    };
+    /** Trends */
+    trends: TimeSeriesData;
+}
+/**
+ * TrackPrompt - Track AI prompt interactions.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides prompt tracking including:
+ * - Prompt submissions
+ * - Response tracking
+ * - User feedback
+ * - Quality metrics
+ * - Usage analytics
+ *
+ * @example
+ * ```typescript
+ * const trackPrompt = new TrackPrompt(webId, endpoint, apiKey);
+ *
+ * // Track prompt submission
+ * await trackPrompt.trackSubmission({
+ *   promptId: 'prompt_123',
+ *   userId: 'user_456',
+ *   promptType: 'code_completion',
+ *   model: 'gpt-4',
+ *   inputTokens: 150
+ * });
+ *
+ * // Track response
+ * await trackPrompt.trackResponse({
+ *   promptId: 'prompt_123',
+ *   responseTime: 1200,
+ *   outputTokens: 300,
+ *   completed: true
+ * });
+ *
+ * // Track user feedback
+ * await trackPrompt.trackFeedback({
+ *   promptId: 'prompt_123',
+ *   feedbackType: 'accepted',
+ *   rating: 5
+ * });
+ * ```
+ */
+export declare class TrackPrompt extends FTRPC {
+    /**
+     * Creates and tracks a prompt event.
+     *
+     * @param config - Prompt configuration
+     * @returns Promise resolving to prompt response
+     */
+    create(config: PromptConfig): Promise<PromptResponse>;
+    /**
+     * Tracks a prompt submission.
+     *
+     * @param config - Prompt submission configuration
+     * @returns Promise resolving to prompt response
+     */
+    trackSubmission(config: PromptSubmissionConfig): Promise<PromptResponse>;
+    /**
+     * Tracks a prompt response.
+     *
+     * @param config - Prompt response configuration
+     * @returns Promise resolving to prompt response
+     */
+    trackResponse(config: PromptResponseConfig): Promise<PromptResponse>;
+    /**
+     * Tracks user feedback on a prompt response.
+     *
+     * @param config - Prompt feedback configuration
+     * @returns Promise resolving to prompt response
+     */
+    trackFeedback(config: PromptFeedbackConfig): Promise<PromptResponse>;
+    /**
+     * Tracks a conversation/multi-turn prompt session.
+     *
+     * @param conversationId - Conversation ID
+     * @param userId - User ID
+     * @param turnCount - Number of turns
+     * @param totalDuration - Total conversation duration (ms)
+     * @returns Promise resolving to prompt response
+     */
+    trackConversation(conversationId: string, userId: string, turnCount: number, totalDuration: number): Promise<PromptResponse>;
+    /**
+     * Gets prompt analytics for dashboards.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to prompt analytics
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<PromptAnalyticsData>;
+}
+export default TrackPrompt;

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

@@ -0,0 +1,298 @@
+/**
+ * @fileoverview Ecommerce - Cart Tracking
+ * @module features/ecommerce/cart
+ *
+ * @description
+ * Track shopping cart interactions including add/remove items,
+ * cart views, and cart abandonment.
+ *
+ * @useCases
+ * - Track add to cart events
+ * - Monitor cart modifications
+ * - Detect cart abandonment
+ * - Analyze popular cart items
+ * - Measure cart value trends
+ *
+ * @metrics
+ * - Add to cart rate
+ * - Average cart value
+ * - Cart abandonment rate
+ * - Items per cart
+ * - Cart-to-checkout rate
+ *
+ * @chartData
+ * - Line chart: Cart value over time
+ * - Bar chart: Top added products
+ * - Pie chart: Abandonment reasons
+ * - Funnel: Cart to checkout flow
+ *
+ * @example
+ * ```typescript
+ * const cart = new CartTracking(webId, endpoint, apiKey);
+ *
+ * // Track add to cart
+ * await cart.addItem({
+ *   product: { productId: 'SKU-123', name: 'Widget', price: 29.99, currency: 'USD' },
+ *   quantity: 2,
+ *   cartId: 'cart_abc'
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { Product, Cart, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Configuration for adding item to cart.
+ */
+export interface AddToCartConfig {
+    /** Product being added */
+    product: Product;
+    /** Quantity to add */
+    quantity: number;
+    /** Cart identifier */
+    cartId?: string;
+    /** User ID */
+    userId?: string;
+    /** Source of add (product page, quick add, etc.) */
+    source?: 'product_page' | 'quick_add' | 'wishlist' | 'recommendation' | 'reorder';
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Configuration for removing item from cart.
+ */
+export interface RemoveFromCartConfig {
+    /** Product being removed */
+    product: Product;
+    /** Quantity to remove */
+    quantity: number;
+    /** Cart identifier */
+    cartId?: string;
+    /** User ID */
+    userId?: string;
+    /** Reason for removal */
+    reason?: 'user_action' | 'out_of_stock' | 'price_change' | 'auto_expired';
+}
+/**
+ * Configuration for updating cart item.
+ */
+export interface UpdateCartItemConfig {
+    /** Product being updated */
+    product: Product;
+    /** Previous quantity */
+    previousQuantity: number;
+    /** New quantity */
+    newQuantity: number;
+    /** Cart identifier */
+    cartId?: string;
+}
+/**
+ * Configuration for cart view.
+ */
+export interface ViewCartConfig {
+    /** Current cart state */
+    cart: Cart;
+    /** User ID */
+    userId?: string;
+}
+/**
+ * Cart event response from API.
+ */
+export interface CartResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        cartId: string;
+        tracked: boolean;
+        cartValue: number;
+        itemCount: number;
+    };
+    timestamp: string;
+}
+/**
+ * Cart analytics data for charts.
+ */
+export interface CartAnalyticsData {
+    /** Cart metrics summary */
+    summary: {
+        totalAddToCarts: number;
+        totalRemoveFromCarts: number;
+        averageCartValue: number;
+        averageItemsPerCart: number;
+        abandonmentRate: number;
+        cartToCheckoutRate: number;
+    };
+    /** Add to cart trends */
+    addToCartTimeSeries: TimeSeriesData;
+    /** Top products added to cart */
+    topAddedProducts: Array<{
+        product: Pick<Product, 'productId' | 'name' | 'category'>;
+        addCount: number;
+        removeCount: number;
+        netAdds: number;
+    }>;
+    /** Abandonment analysis */
+    abandonment: {
+        rate: number;
+        avgAbandonedValue: number;
+        topAbandonedProducts: Array<{
+            product: Pick<Product, 'productId' | 'name'>;
+            abandonCount: number;
+        }>;
+    };
+}
+/**
+ * CartTracking - Track shopping cart interactions.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides cart tracking capabilities including:
+ * - Add to cart events
+ * - Remove from cart events
+ * - Cart quantity updates
+ * - Cart view tracking
+ * - Cart abandonment detection
+ *
+ * @example
+ * ```typescript
+ * const cart = new CartTracking(webId, endpoint, apiKey);
+ *
+ * // Track add to cart
+ * await cart.addItem({
+ *   product: {
+ *     productId: 'PROD-001',
+ *     name: 'Widget Pro',
+ *     price: 99.99,
+ *     currency: 'USD'
+ *   },
+ *   quantity: 1,
+ *   source: 'product_page'
+ * });
+ *
+ * // Track cart view
+ * await cart.view({
+ *   cart: currentCart
+ * });
+ * ```
+ */
+export declare class CartTracking extends FTRPC {
+    /**
+     * Tracks adding an item to cart.
+     *
+     * @param config - Add to cart configuration
+     * @returns Promise resolving to cart response
+     *
+     * @example
+     * ```typescript
+     * await cart.addItem({
+     *   product: {
+     *     productId: 'SKU-123',
+     *     name: 'Premium Widget',
+     *     price: 49.99,
+     *     currency: 'USD',
+     *     category: 'Widgets'
+     *   },
+     *   quantity: 2,
+     *   source: 'product_page'
+     * });
+     * ```
+     */
+    addItem(config: AddToCartConfig): Promise<CartResponse>;
+    /**
+     * Tracks removing an item from cart.
+     *
+     * @param config - Remove from cart configuration
+     * @returns Promise resolving to cart response
+     *
+     * @example
+     * ```typescript
+     * await cart.removeItem({
+     *   product: productToRemove,
+     *   quantity: 1,
+     *   cartId: 'cart_123',
+     *   reason: 'user_action'
+     * });
+     * ```
+     */
+    removeItem(config: RemoveFromCartConfig): Promise<CartResponse>;
+    /**
+     * Tracks cart item quantity update.
+     *
+     * @param config - Update configuration
+     * @returns Promise resolving to cart response
+     *
+     * @example
+     * ```typescript
+     * await cart.updateItem({
+     *   product: item.product,
+     *   previousQuantity: 1,
+     *   newQuantity: 3,
+     *   cartId: 'cart_123'
+     * });
+     * ```
+     */
+    updateItem(config: UpdateCartItemConfig): Promise<CartResponse>;
+    /**
+     * Tracks a cart view event.
+     *
+     * @param config - View cart configuration
+     * @returns Promise resolving to cart response
+     *
+     * @example
+     * ```typescript
+     * await cart.view({
+     *   cart: {
+     *     cartId: 'cart_123',
+     *     items: cartItems,
+     *     subtotal: 149.97,
+     *     total: 164.97,
+     *     currency: 'USD',
+     *     itemCount: 3
+     *   }
+     * });
+     * ```
+     */
+    view(config: ViewCartConfig): Promise<CartResponse>;
+    /**
+     * Tracks cart abandonment.
+     *
+     * @param cart - Abandoned cart state
+     * @param reason - Abandonment reason (if known)
+     * @returns Promise resolving to cart response
+     */
+    abandon(cart: Cart, reason?: 'exit' | 'timeout' | 'price_too_high' | 'shipping_cost' | 'other'): Promise<CartResponse>;
+    /**
+     * Applies a coupon to the cart.
+     *
+     * @param cartId - Cart identifier
+     * @param couponCode - Coupon code applied
+     * @param success - Whether coupon was valid
+     * @param discount - Discount amount (if successful)
+     * @returns Promise resolving to cart response
+     */
+    applyCoupon(cartId: string, couponCode: string, success: boolean, discount?: number): Promise<CartResponse>;
+    /**
+     * Retrieves cart analytics data for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to cart analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await cart.getAnalytics({
+     *   range: 'last30days'
+     * });
+     *
+     * // Line chart - add to cart over time
+     * const trendData = analytics.addToCartTimeSeries.data;
+     *
+     * // Bar chart - top products added
+     * const topProducts = analytics.topAddedProducts.map(p => ({
+     *   name: p.product.name,
+     *   value: p.addCount
+     * }));
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<CartAnalyticsData>;
+}
+export default CartTracking;