flowgrid-sdk 1.0.0

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

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview Ecommerce - Subscription & Recurring Revenue
+ * @module features/ecommerce/subscriptions
+ *
+ * @description
+ * Track subscription lifecycle events for SaaS and subscription
+ * ecommerce businesses.
+ *
+ * @useCases
+ * - Track subscription signups
+ * - Monitor subscription changes (upgrades/downgrades)
+ * - Track cancellations and churn
+ * - Calculate MRR/ARR metrics
+ * - Analyze subscription cohorts
+ *
+ * @metrics
+ * - Monthly Recurring Revenue (MRR)
+ * - Annual Recurring Revenue (ARR)
+ * - Churn rate
+ * - Expansion revenue
+ * - Net revenue retention
+ *
+ * @chartData
+ * - Line chart: MRR over time
+ * - Waterfall: MRR movement
+ * - Bar chart: Revenue by plan
+ * - Cohort: Subscription retention
+ *
+ * @example
+ * ```typescript
+ * const subscriptions = new Subscriptions(webId, endpoint, apiKey);
+ *
+ * // Track subscription start
+ * await subscriptions.start({
+ *   subscriptionId: 'sub_123',
+ *   userId: 'user_456',
+ *   plan: 'pro',
+ *   mrr: { amount: 4900, currency: 'USD' },
+ *   billingCycle: 'monthly'
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Subscription start configuration.
+ */
+export interface SubscriptionStartConfig {
+    /** Subscription ID */
+    subscriptionId: string;
+    /** User ID */
+    userId: string;
+    /** Plan name */
+    plan: string;
+    /** Monthly recurring revenue */
+    mrr: MoneyValue;
+    /** Billing cycle */
+    billingCycle: 'monthly' | 'quarterly' | 'yearly';
+    /** Trial period (if applicable) */
+    trialDays?: number;
+    /** Coupon applied */
+    coupon?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Subscription change configuration.
+ */
+export interface SubscriptionChangeConfig {
+    /** Subscription ID */
+    subscriptionId: string;
+    /** User ID */
+    userId: string;
+    /** Previous plan */
+    previousPlan: string;
+    /** New plan */
+    newPlan: string;
+    /** Previous MRR */
+    previousMrr: MoneyValue;
+    /** New MRR */
+    newMrr: MoneyValue;
+    /** Change type */
+    changeType: 'upgrade' | 'downgrade' | 'cross_grade';
+}
+/**
+ * Subscription cancellation configuration.
+ */
+export interface SubscriptionCancelConfig {
+    /** Subscription ID */
+    subscriptionId: string;
+    /** User ID */
+    userId: string;
+    /** Plan being cancelled */
+    plan: string;
+    /** Lost MRR */
+    lostMrr: MoneyValue;
+    /** Cancellation reason */
+    reason?: string;
+    /** Feedback provided */
+    feedback?: string;
+    /** Whether cancelled immediately or at period end */
+    immediate: boolean;
+}
+/**
+ * Subscription response from API.
+ */
+export interface SubscriptionResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        subscriptionId: string;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Subscription analytics data.
+ */
+export interface SubscriptionAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalMrr: MoneyValue;
+        totalArr: MoneyValue;
+        activeSubscriptions: number;
+        newSubscriptions: number;
+        churnedSubscriptions: number;
+        churnRate: number;
+        expansionMrr: MoneyValue;
+        contractionMrr: MoneyValue;
+        netMrrMovement: MoneyValue;
+        netRevenueRetention: number;
+        avgRevenuePerUser: MoneyValue;
+    };
+    /** MRR by plan */
+    byPlan: Array<{
+        plan: string;
+        subscriptions: number;
+        mrr: MoneyValue;
+        percentage: number;
+    }>;
+    /** MRR waterfall */
+    mrrMovement: {
+        startingMrr: MoneyValue;
+        newMrr: MoneyValue;
+        expansionMrr: MoneyValue;
+        contractionMrr: MoneyValue;
+        churnedMrr: MoneyValue;
+        endingMrr: MoneyValue;
+    };
+    /** MRR trend */
+    mrrTrend: TimeSeriesData;
+    /** Churn by reason */
+    churnByReason: Array<{
+        reason: string;
+        count: number;
+        lostMrr: MoneyValue;
+    }>;
+    /** Trial conversion rate */
+    trialMetrics: {
+        trialsStarted: number;
+        trialsConverted: number;
+        conversionRate: number;
+    };
+}
+/**
+ * Subscriptions - Track subscription lifecycle events.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides subscription tracking including:
+ * - Subscription starts (new MRR)
+ * - Plan changes (expansion/contraction)
+ * - Cancellations (churned MRR)
+ * - Renewals
+ * - Trial conversions
+ *
+ * @example
+ * ```typescript
+ * const subscriptions = new Subscriptions(webId, endpoint, apiKey);
+ *
+ * // New subscription
+ * await subscriptions.start({
+ *   subscriptionId: 'sub_abc123',
+ *   userId: 'user_456',
+ *   plan: 'professional',
+ *   mrr: { amount: 9900, currency: 'USD' },
+ *   billingCycle: 'monthly',
+ *   trialDays: 14
+ * });
+ *
+ * // Upgrade
+ * await subscriptions.change({
+ *   subscriptionId: 'sub_abc123',
+ *   userId: 'user_456',
+ *   previousPlan: 'professional',
+ *   newPlan: 'enterprise',
+ *   previousMrr: { amount: 9900, currency: 'USD' },
+ *   newMrr: { amount: 29900, currency: 'USD' },
+ *   changeType: 'upgrade'
+ * });
+ * ```
+ */
+export declare class Subscriptions extends FTRPC {
+    /**
+     * Tracks subscription start.
+     *
+     * @param config - Subscription start configuration
+     * @returns Promise resolving to subscription response
+     */
+    start(config: SubscriptionStartConfig): Promise<SubscriptionResponse>;
+    /**
+     * Tracks subscription plan change.
+     *
+     * @param config - Subscription change configuration
+     * @returns Promise resolving to subscription response
+     */
+    change(config: SubscriptionChangeConfig): Promise<SubscriptionResponse>;
+    /**
+     * Tracks subscription cancellation.
+     *
+     * @param config - Cancellation configuration
+     * @returns Promise resolving to subscription response
+     */
+    cancel(config: SubscriptionCancelConfig): Promise<SubscriptionResponse>;
+    /**
+     * Tracks subscription renewal.
+     *
+     * @param subscriptionId - Subscription ID
+     * @param userId - User ID
+     * @param mrr - Renewed MRR
+     * @returns Promise resolving to subscription response
+     */
+    renew(subscriptionId: string, userId: string, mrr: MoneyValue): Promise<SubscriptionResponse>;
+    /**
+     * Tracks trial conversion to paid.
+     *
+     * @param subscriptionId - Subscription ID
+     * @param userId - User ID
+     * @param plan - Converted to plan
+     * @param mrr - New MRR
+     * @returns Promise resolving to subscription response
+     */
+    trialConverted(subscriptionId: string, userId: string, plan: string, mrr: MoneyValue): Promise<SubscriptionResponse>;
+    /**
+     * Tracks trial expiration without conversion.
+     *
+     * @param subscriptionId - Subscription ID
+     * @param userId - User ID
+     * @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;

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

@@ -0,0 +1,236 @@
+/**
+ * @fileoverview Ecommerce - Wishlist Tracking
+ * @module features/ecommerce/wishlist
+ *
+ * @description
+ * Track wishlist interactions to understand purchase intent
+ * and drive conversions from saved items.
+ *
+ * @useCases
+ * - Track wishlist additions
+ * - Monitor wishlist to cart conversions
+ * - Identify popular wishlist items
+ * - Trigger price drop notifications
+ * - Analyze wishlist behavior patterns
+ *
+ * @metrics
+ * - Wishlist additions
+ * - Wishlist to cart rate
+ * - Wishlist to purchase rate
+ * - Average items per wishlist
+ * - Top wishlisted products
+ *
+ * @chartData
+ * - Bar chart: Top wishlisted products
+ * - Line chart: Wishlist activity over time
+ * - Funnel: Wishlist to purchase conversion
+ * - Table: Wishlist conversion rates by product
+ *
+ * @example
+ * ```typescript
+ * const wishlist = new WishlistTracking(webId, endpoint, apiKey);
+ *
+ * // Add to wishlist
+ * await wishlist.add({
+ *   product: { productId: 'PROD-123', name: 'Widget', price: 49.99, currency: 'USD' },
+ *   wishlistId: 'wl_user123'
+ * });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { Product, Wishlist, DateRangeFilter, TimeSeriesData } from "../../types";
+/**
+ * Configuration for adding to wishlist.
+ */
+export interface AddToWishlistConfig {
+    /** Product being added */
+    product: Product;
+    /** Wishlist ID */
+    wishlistId?: string;
+    /** User ID */
+    userId?: string;
+    /** Source of add */
+    source?: 'product_page' | 'quick_add' | 'list_view' | 'search';
+}
+/**
+ * Configuration for removing from wishlist.
+ */
+export interface RemoveFromWishlistConfig {
+    /** Product being removed */
+    product: Product;
+    /** Wishlist ID */
+    wishlistId?: string;
+    /** User ID */
+    userId?: string;
+    /** Reason for removal */
+    reason?: 'user_action' | 'purchased' | 'moved_to_cart' | 'out_of_stock';
+}
+/**
+ * Wishlist event response from API.
+ */
+export interface WishlistResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        wishlistId: string;
+        productId: string;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Wishlist analytics data for charts.
+ */
+export interface WishlistAnalyticsData {
+    /** Summary metrics */
+    summary: {
+        totalWishlistAdds: number;
+        totalWishlistRemoves: number;
+        activeWishlists: number;
+        avgItemsPerWishlist: number;
+        wishlistToCartRate: number;
+        wishlistToPurchaseRate: number;
+    };
+    /** Top wishlisted products */
+    topProducts: Array<{
+        product: Pick<Product, 'productId' | 'name' | 'category' | 'price'>;
+        wishlistCount: number;
+        conversionToCart: number;
+        conversionToPurchase: number;
+    }>;
+    /** Wishlist activity time series */
+    timeSeries: TimeSeriesData;
+    /** Conversion funnel */
+    conversionFunnel: {
+        wishlisted: number;
+        addedToCart: number;
+        purchased: number;
+        wishlistToCartRate: number;
+        cartToPurchaseRate: number;
+    };
+}
+/**
+ * WishlistTracking - Track wishlist interactions.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides wishlist tracking capabilities including:
+ * - Add to wishlist events
+ * - Remove from wishlist events
+ * - Wishlist views
+ * - Move to cart tracking
+ * - Wishlist sharing
+ *
+ * @example
+ * ```typescript
+ * const wishlist = new WishlistTracking(webId, endpoint, apiKey);
+ *
+ * // Add product to wishlist
+ * await wishlist.add({
+ *   product: {
+ *     productId: 'PROD-001',
+ *     name: 'Designer Bag',
+ *     price: 299.99,
+ *     currency: 'USD'
+ *   },
+ *   source: 'product_page'
+ * });
+ *
+ * // Track wishlist view
+ * await wishlist.view({
+ *   wishlistId: 'wl_user123',
+ *   items: wishlistItems
+ * });
+ * ```
+ */
+export declare class WishlistTracking extends FTRPC {
+    /**
+     * Tracks adding product to wishlist.
+     *
+     * @param config - Add to wishlist configuration
+     * @returns Promise resolving to wishlist response
+     *
+     * @example
+     * ```typescript
+     * await wishlist.add({
+     *   product: {
+     *     productId: 'SKU-789',
+     *     name: 'Premium Sneakers',
+     *     price: 159.99,
+     *     currency: 'USD',
+     *     category: 'Footwear'
+     *   },
+     *   source: 'product_page'
+     * });
+     * ```
+     */
+    add(config: AddToWishlistConfig): Promise<WishlistResponse>;
+    /**
+     * Tracks removing product from wishlist.
+     *
+     * @param config - Remove from wishlist configuration
+     * @returns Promise resolving to wishlist response
+     *
+     * @example
+     * ```typescript
+     * await wishlist.remove({
+     *   product: productToRemove,
+     *   wishlistId: 'wl_user123',
+     *   reason: 'moved_to_cart'
+     * });
+     * ```
+     */
+    remove(config: RemoveFromWishlistConfig): Promise<WishlistResponse>;
+    /**
+     * Tracks wishlist view.
+     *
+     * @param wishlist - Wishlist being viewed
+     * @returns Promise resolving to wishlist response
+     */
+    view(wishlist: Wishlist): Promise<WishlistResponse>;
+    /**
+     * Tracks moving item from wishlist to cart.
+     *
+     * @param product - Product being moved
+     * @param wishlistId - Source wishlist
+     * @returns Promise resolving to wishlist response
+     */
+    moveToCart(product: Product, wishlistId?: string): Promise<WishlistResponse>;
+    /**
+     * Tracks wishlist sharing.
+     *
+     * @param wishlistId - Wishlist being shared
+     * @param method - Share method
+     * @returns Promise resolving to wishlist response
+     */
+    share(wishlistId: string, method: 'email' | 'link' | 'social'): Promise<WishlistResponse>;
+    /**
+     * Retrieves wishlist analytics for dashboards and charts.
+     *
+     * @param filter - Date range filter
+     * @returns Promise resolving to wishlist analytics
+     *
+     * @example
+     * ```typescript
+     * const analytics = await wishlist.getAnalytics({
+     *   range: 'last30days'
+     * });
+     *
+     * // Bar chart - top wishlisted products
+     * const topProducts = analytics.topProducts.map(p => ({
+     *   name: p.product.name,
+     *   value: p.wishlistCount
+     * }));
+     *
+     * // Funnel - wishlist to purchase
+     * const funnel = [
+     *   { name: 'Wishlisted', value: analytics.conversionFunnel.wishlisted },
+     *   { name: 'Added to Cart', value: analytics.conversionFunnel.addedToCart },
+     *   { name: 'Purchased', value: analytics.conversionFunnel.purchased }
+     * ];
+     * ```
+     */
+    getAnalytics(filter?: DateRangeFilter): Promise<WishlistAnalyticsData>;
+}
+export default WishlistTracking;