flowgrid-sdk 1.2.0 → 1.3.0

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

@@ -0,0 +1,207 @@
+/**
+ * @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 { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// SUBSCRIPTIONS CLASS
+// ============================================================================
+/**
+ * Subscriptions - Track subscription lifecycle events.
+ *
+ * @extends FlowGridTransport
+ *
+ * @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 class Subscriptions extends FlowGridTransport {
+    /**
+     * Tracks subscription start.
+     *
+     * @param config - Subscription start configuration
+     * @returns Promise resolving to subscription response
+     */
+    async start(config) {
+        return await this.init("subscription_start", {
+            type: "ecommerce",
+            subtype: "subscription_start",
+            subscriptionId: config.subscriptionId,
+            userId: config.userId,
+            plan: config.plan,
+            mrr: config.mrr,
+            billingCycle: config.billingCycle,
+            trialDays: config.trialDays,
+            coupon: config.coupon,
+            isTrialing: (config.trialDays || 0) > 0,
+            ...config.properties,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks subscription plan change.
+     *
+     * @param config - Subscription change configuration
+     * @returns Promise resolving to subscription response
+     */
+    async change(config) {
+        const mrrDiff = config.newMrr.amount - config.previousMrr.amount;
+        return await this.init("subscription_change", {
+            type: "ecommerce",
+            subtype: "subscription_change",
+            subscriptionId: config.subscriptionId,
+            userId: config.userId,
+            previousPlan: config.previousPlan,
+            newPlan: config.newPlan,
+            previousMrr: config.previousMrr,
+            newMrr: config.newMrr,
+            mrrChange: mrrDiff,
+            changeType: config.changeType,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks subscription cancellation.
+     *
+     * @param config - Cancellation configuration
+     * @returns Promise resolving to subscription response
+     */
+    async cancel(config) {
+        return await this.init("subscription_cancel", {
+            type: "ecommerce",
+            subtype: "subscription_cancel",
+            subscriptionId: config.subscriptionId,
+            userId: config.userId,
+            plan: config.plan,
+            lostMrr: config.lostMrr,
+            reason: config.reason,
+            feedback: config.feedback,
+            immediate: config.immediate,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks subscription renewal.
+     *
+     * @param subscriptionId - Subscription ID
+     * @param userId - User ID
+     * @param mrr - Renewed MRR
+     * @returns Promise resolving to subscription response
+     */
+    async renew(subscriptionId, userId, mrr) {
+        return await this.init("subscription_renew", {
+            type: "ecommerce",
+            subtype: "subscription_renew",
+            subscriptionId,
+            userId,
+            mrr,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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
+     */
+    async trialConverted(subscriptionId, userId, plan, mrr) {
+        return await this.init("trial_converted", {
+            type: "ecommerce",
+            subtype: "trial_converted",
+            subscriptionId,
+            userId,
+            plan,
+            mrr,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks trial expiration without conversion.
+     *
+     * @param subscriptionId - Subscription ID
+     * @param userId - User ID
+     * @returns Promise resolving to subscription response
+     */
+    async trialExpired(subscriptionId, userId) {
+        return await this.init("trial_expired", {
+            type: "ecommerce",
+            subtype: "trial_expired",
+            subscriptionId,
+            userId,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default Subscriptions;
+//# sourceMappingURL=subscriptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"subscriptions.js","sourceRoot":"","sources":["../../../../src/lib/features/ecommerce/subscriptions.ts"],"names":[],"mappings":"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"}

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

@@ -38,7 +38,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { Product, Wishlist, DateRangeFilter, TimeSeriesData } from "../../types";
+import { Product, Wishlist, TimeSeriesData } from "../../types";
 /**
  * Configuration for adding to wishlist.
  */
@@ -205,32 +205,5 @@ export declare class WishlistTracking extends FlowGridTransport {
      * @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;

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

@@ -0,0 +1,186 @@
+/**
+ * @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 { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// WISHLIST TRACKING CLASS
+// ============================================================================
+/**
+ * WishlistTracking - Track wishlist interactions.
+ *
+ * @extends FlowGridTransport
+ *
+ * @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 class WishlistTracking extends FlowGridTransport {
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    async add(config) {
+        return await this.init("add_to_wishlist", {
+            type: "ecommerce",
+            subtype: "add_to_wishlist",
+            product: config.product,
+            wishlistId: config.wishlistId,
+            userId: config.userId,
+            source: config.source,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * 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'
+     * });
+     * ```
+     */
+    async remove(config) {
+        return await this.init("remove_from_wishlist", {
+            type: "ecommerce",
+            subtype: "remove_from_wishlist",
+            product: config.product,
+            wishlistId: config.wishlistId,
+            userId: config.userId,
+            reason: config.reason || "user_action",
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks wishlist view.
+     *
+     * @param wishlist - Wishlist being viewed
+     * @returns Promise resolving to wishlist response
+     */
+    async view(wishlist) {
+        return await this.init("view_wishlist", {
+            type: "ecommerce",
+            subtype: "view_wishlist",
+            wishlistId: wishlist.wishlistId,
+            itemCount: wishlist.items.length,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks moving item from wishlist to cart.
+     *
+     * @param product - Product being moved
+     * @param wishlistId - Source wishlist
+     * @returns Promise resolving to wishlist response
+     */
+    async moveToCart(product, wishlistId) {
+        return await this.init("wishlist_to_cart", {
+            type: "ecommerce",
+            subtype: "wishlist_to_cart",
+            product,
+            wishlistId,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Tracks wishlist sharing.
+     *
+     * @param wishlistId - Wishlist being shared
+     * @param method - Share method
+     * @returns Promise resolving to wishlist response
+     */
+    async share(wishlistId, method) {
+        return await this.init("share_wishlist", {
+            type: "ecommerce",
+            subtype: "share_wishlist",
+            wishlistId,
+            method,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+export default WishlistTracking;
+//# sourceMappingURL=wishlist.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wishlist.js","sourceRoot":"","sources":["../../../../src/lib/features/ecommerce/wishlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAuF3D,+EAA+E;AAC/E,0BAA0B;AAC1B,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAO,gBAAiB,SAAQ,iBAAiB;IACrD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,GAAG,CAAC,MAA2B;QACnC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACxC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,iBAAiB;YAC1B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,MAAM,CAAC,MAAgC;QAC3C,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,sBAAsB,EAAE;YAC7C,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,sBAAsB;YAC/B,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,aAAa;YACtC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,QAAkB;QAC3B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACtC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,eAAe;YACxB,UAAU,EAAE,QAAQ,CAAC,UAAU;YAC/B,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM;YAChC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAAC,OAAgB,EAAE,UAAmB;QACpD,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE;YACzC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,kBAAkB;YAC3B,OAAO;YACP,UAAU;YACV,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CACT,UAAkB,EAClB,MAAmC;QAEnC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE;YACvC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,gBAAgB;YACzB,UAAU;YACV,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CAEF;AAED,eAAe,gBAAgB,CAAC"}

package/dist/lib/features/enterprise/acquisition.d.ts

@@ -39,7 +39,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
-import { DateRangeFilter, TimeSeriesData, TimeGranularity, MoneyValue, CurrencyCode } from "../../types";
+import { DateRangeFilter, TimeSeriesData, MoneyValue, CurrencyCode } from "../../types";
 /**
  * Acquisition source types.
  */
@@ -252,7 +252,7 @@ export interface AttributionResult {
 /**
  * Acquisition analytics result.
  */
-export interface AcquisitionAnalytics {
+export interface AcquisitionAnalyticType {
     totalAcquisitions: number;
     cac: MoneyValue;
     ltv: MoneyValue;
@@ -315,59 +315,4 @@ export declare class AcquisitionAnalytics extends FlowGridTransport {
     trackCampaignSpend(config: CampaignSpendConfig): Promise<{
         tracked: boolean;
     }>;
-    /**
-     * Get CAC.
-     */
-    getCAC(config?: CACConfig): Promise<CACResult>;
-    /**
-     * Get trial funnel.
-     */
-    getTrialFunnel(config?: TrialFunnelConfig): Promise<TrialFunnelResult>;
-    /**
-     * Get campaign performance.
-     */
-    getCampaignPerformance(campaignId?: string, filter?: DateRangeFilter): Promise<CampaignPerformance[]>;
-    /**
-     * Get attribution analysis.
-     */
-    getAttribution(config: AttributionAnalysisConfig): Promise<AttributionResult>;
-    /**
-     * Get LTV:CAC ratio.
-     */
-    getLTVCACRatio(filter?: DateRangeFilter): Promise<{
-        ltv: MoneyValue;
-        cac: MoneyValue;
-        ratio: number;
-        healthy: boolean;
-    }>;
-    /**
-     * Get acquisition analytics.
-     */
-    getAnalytics(filter?: DateRangeFilter): Promise<AcquisitionAnalytics>;
-    /**
-     * Get acquisition trend.
-     */
-    getAcquisitionTrend(filter?: DateRangeFilter, granularity?: TimeGranularity): Promise<TimeSeriesData>;
-    /**
-     * Get channel effectiveness.
-     */
-    getChannelEffectiveness(filter?: DateRangeFilter): Promise<Array<{
-        channel: AcquisitionSource;
-        acquisitions: number;
-        cac: MoneyValue;
-        ltv: MoneyValue;
-        paybackMonths: number;
-        score: number;
-    }>>;
-    /**
-     * Get cohort-based campaign analysis.
-     */
-    getCohortCampaignAnalysis(campaignId: string, periods: number): Promise<{
-        cohorts: Array<{
-            cohortDate: string;
-            acquisitions: number;
-            retention: number[];
-            ltv: MoneyValue;
-        }>;
-    }>;
 }

package/dist/lib/features/enterprise/acquisition.js

@@ -0,0 +1,166 @@
+/**
+ * @fileoverview Enterprise - Marketing & Acquisition Analytics
+ * @module features/enterprise/acquisition
+ *
+ * @description
+ * Deep attribution and acquisition insights including CAC breakdown,
+ * trial-to-paid funnel tracking, and campaign performance by cohort.
+ *
+ * @useCases
+ * - Track customer acquisition cost by channel
+ * - Monitor trial → paid → upgrade funnel
+ * - Analyze campaign performance
+ * - Multi-touch attribution
+ * - Marketing ROI calculation
+ *
+ * @metrics
+ * - Customer Acquisition Cost (CAC)
+ * - Trial conversion rate
+ * - Paid conversion rate
+ * - Campaign ROI
+ * - Channel effectiveness
+ *
+ * @chartData
+ * - Bar chart: CAC by channel
+ * - Funnel: Trial to paid conversion
+ * - Line chart: Campaign performance
+ * - Pie chart: Acquisition source mix
+ *
+ * @example
+ * ```typescript
+ * const acquisition = new AcquisitionAnalytics(webId, endpoint, apiKey);
+ *
+ * // Track acquisition
+ * await acquisition.trackAcquisition({
+ *   userId: 'user_123',
+ *   source: 'google_ads',
+ *   campaign: 'summer_2026'
+ * });
+ * ```
+ */
+import { FlowGridTransport } from "../../client/transport";
+// ============================================================================
+// HELPER FUNCTIONS
+// ============================================================================
+/**
+ * Calculate CAC.
+ */
+export function calculateCAC(totalSpend, totalAcquisitions, currency) {
+    if (totalAcquisitions === 0) {
+        return { amount: 0, currency };
+    }
+    return {
+        amount: Math.round((totalSpend / totalAcquisitions) * 100) / 100,
+        currency
+    };
+}
+/**
+ * Calculate ROAS (Return on Ad Spend).
+ */
+export function calculateROAS(revenue, spend) {
+    if (spend === 0)
+        return 0;
+    return Math.round((revenue / spend) * 100) / 100;
+}
+/**
+ * Calculate LTV:CAC ratio.
+ */
+export function calculateLTVCACRatio(ltv, cac) {
+    if (cac === 0)
+        return 0;
+    return Math.round((ltv / cac) * 100) / 100;
+}
+/**
+ * Parse UTM parameters from URL.
+ */
+export function parseUTMParams(url) {
+    const params = {};
+    try {
+        const urlObj = new URL(url);
+        const utmKeys = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'];
+        for (const key of utmKeys) {
+            const value = urlObj.searchParams.get(key);
+            if (value) {
+                params[key.replace('utm_', '')] = value;
+            }
+        }
+    }
+    catch {
+        // Invalid URL, return empty object
+    }
+    return params;
+}
+/**
+ * Classify acquisition source from UTM parameters.
+ */
+export function classifySource(utmSource, utmMedium) {
+    if (!utmSource && !utmMedium)
+        return 'direct';
+    const source = utmSource?.toLowerCase() ?? '';
+    const medium = utmMedium?.toLowerCase() ?? '';
+    if (medium.includes('cpc') || medium.includes('paid')) {
+        if (source.includes('facebook') || source.includes('instagram') || source.includes('linkedin')) {
+            return 'paid_social';
+        }
+        return 'paid_search';
+    }
+    if (source.includes('facebook') || source.includes('twitter') || source.includes('linkedin')) {
+        return 'organic_social';
+    }
+    if (medium === 'email')
+        return 'email';
+    if (medium === 'referral')
+        return 'referral';
+    if (medium === 'affiliate')
+        return 'affiliate';
+    return 'organic';
+}
+// ============================================================================
+// MAIN CLASS
+// ============================================================================
+/**
+ * Marketing and acquisition analytics class.
+ */
+export class AcquisitionAnalytics extends FlowGridTransport {
+    /**
+     * Track user acquisition.
+     */
+    async trackAcquisition(config) {
+        return await this.initFeature("acquisition.acquired", {
+            type: "acquisition",
+            ...config,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Track lifecycle transition.
+     */
+    async trackLifecycleTransition(config) {
+        return await this.initFeature("acquisition.lifecycle_transition", {
+            type: "acquisition",
+            ...config,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Create campaign.
+     */
+    async createCampaign(definition) {
+        return await this.initFeature("acquisition.create_campaign", {
+            type: "acquisition",
+            ...definition,
+            timestamp: new Date().toISOString()
+        });
+    }
+    /**
+     * Track campaign spend.
+     */
+    async trackCampaignSpend(config) {
+        return await this.initFeature("acquisition.campaign_spend", {
+            type: "acquisition",
+            ...config,
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+//# sourceMappingURL=acquisition.js.map

package/dist/lib/features/enterprise/acquisition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acquisition.js","sourceRoot":"","sources":["../../../../src/lib/features/enterprise/acquisition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AA8Q3D,+EAA+E;AAC/E,mBAAmB;AACnB,+EAA+E;AAE/E;;GAEG;AACH,MAAM,UAAU,YAAY,CAC1B,UAAkB,EAClB,iBAAyB,EACzB,QAAsB;IAEtB,IAAI,iBAAiB,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC;IACjC,CAAC;IACD,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,iBAAiB,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG;QAChE,QAAQ;KACT,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,KAAa;IAC1D,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW,EAAE,GAAW;IAC3D,IAAI,GAAG,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,OAAO,GAAG,CAAC,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;QACxF,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC3C,IAAI,KAAK,EAAE,CAAC;gBACV,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;YAC1C,CAAC;QACH,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,mCAAmC;IACrC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,SAAkB,EAAE,SAAkB;IACnE,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS;QAAE,OAAO,QAAQ,CAAC;IAE9C,MAAM,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC9C,MAAM,MAAM,GAAG,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAE9C,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtD,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/F,OAAO,aAAa,CAAC;QACvB,CAAC;QACD,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC7F,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED,IAAI,MAAM,KAAK,OAAO;QAAE,OAAO,OAAO,CAAC;IACvC,IAAI,MAAM,KAAK,UAAU;QAAE,OAAO,UAAU,CAAC;IAC7C,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,WAAW,CAAC;IAE/C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;GAEG;AACH,MAAM,OAAO,oBAAqB,SAAQ,iBAAiB;IACzD;;OAEG;IACH,KAAK,CAAC,gBAAgB,CAAC,MAAyB;QAC9C,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,sBAAsB,EAAE;YACpD,IAAI,EAAE,aAAa;YACnB,GAAG,MAAM;YACT,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,wBAAwB,CAC5B,MAAiC;QAEjC,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,kCAAkC,EAAE;YAChE,IAAI,EAAE,aAAa;YACnB,GAAG,MAAM;YACT,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,cAAc,CAAC,UAA8B;QACjD,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,6BAA6B,EAAE;YAC3D,IAAI,EAAE,aAAa;YACnB,GAAG,UAAU;YACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,kBAAkB,CAAC,MAA2B;QAClD,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,4BAA4B,EAAE;YAC1D,IAAI,EAAE,aAAa;YACnB,GAAG,MAAM;YACT,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CAEF"}