flowgrid-sdk 1.0.0

package/dist/lib/client/enterprise-ftrpc.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Enterprise SDK Types
+ */
+type EnterpriseType = "engagement" | "cohorts" | "churn" | "monetization" | "multi_path_funnels" | "support" | "acquisition" | "paths" | "alerts" | "security" | "forecasting";
+/**
+ * Enterprise SDK Base Class
+ * - Flowgrid TypeScript Remote Procedure Call for Enterprise Features
+ * - Routes to separate enterprise API endpoints
+ * - Requires enterprise-tier API key
+ *
+ * PRIVACY NOTICE:
+ * This SDK collects event data for analytics purposes. Ensure compliance with
+ * applicable privacy laws (GDPR, CCPA, etc.) when collecting user data.
+ * Do not send personally identifiable information without proper consent.
+ *
+ * ```typescript
+ *  await this.init('eventName', { type: 'engagement', ... });
+ * ```
+ */
+export declare class EnterpriseFTRPC {
+    /**
+     * Web ID for the specific site or application.
+     * Used to identify the event source.
+     */
+    protected webId: string;
+    /**
+     * API endpoint for sending events.
+     * Example: "https://api.flowgrid.com"
+     */
+    protected endpoint: string;
+    /**
+     * Enterprise API Key for authenticating requests.
+     */
+    private apiKey;
+    constructor(webId: string, endpoint: string, apiKey: string);
+    /**
+     * Sends an event to the Enterprise API.
+     * Used internally by subclasses to track enterprise events.
+     *
+     * @param eventName - Name of the event to track.
+     * @param properties - Additional properties to send with the event (must include type).
+     */
+    protected init(eventName: string, properties: Record<string, any> & {
+        type: EnterpriseType;
+    }): Promise<any>;
+    /**
+     * Validates input parameters for security and correctness.
+     */
+    private validateInput;
+}
+export type { EnterpriseType };

package/dist/lib/client/ftrpc.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Base SDK Class
+ * - Flowgrid TypeScript Remote Procedure Call
+ * - Handles common logic for sending events to the API.
+ *
+ * PRIVACY NOTICE:
+ * This SDK collects event data for analytics purposes. Ensure compliance with
+ * applicable privacy laws (GDPR, CCPA, etc.) when collecting user data.
+ * Do not send personally identifiable information without proper consent.
+ *
+ * ```typescript
+ *  await this.init('eventName', { key: 'value' });
+ * ```
+ */
+export declare class FTRPC {
+    /**
+     * Web ID for the specific site or application.
+     * Used to identify the event source.
+     */
+    protected webId: string;
+    /**
+     * API endpoint for sending events.
+     * Example: "https://api.flowgrid.com"
+     */
+    protected endpoint: string;
+    /**
+     * API Key for authenticating requests.
+     */
+    private apiKey;
+    constructor(webId: string, endpoint: string, apiKey: string);
+    /**
+     * Sends an event to the API.
+     * Used internally by subclasses to track events.
+     *
+     * @param eventName - Name of the event to track.
+     * @param properties - Additional properties to send with the event.
+     */
+    protected init<T>(eventName: string, properties?: Record<string, any>, request?: "GET" | "POST" | "PATCH"): Promise<T>;
+    /**
+     * Validates input parameters for security and correctness.
+     */
+    private validateInput;
+}

package/dist/lib/client/modules.d.ts

@@ -0,0 +1,104 @@
+import { FTRPC } from "./ftrpc";
+type Config = {
+    eventName: string;
+    properties: Record<string, any>;
+};
+type ConfigResponse = {
+    eventName: string;
+    properties: Record<string, any>;
+    response: string | number | boolean;
+};
+/**
+ * Flowgrid SDK
+ * For user activation events (onboarding, signup, etc.)
+ */
+export declare class Activation extends FTRPC {
+    /**
+     * Creates and tracks an activation event (onboarding, signup, etc.)
+     * Adds a "cool" tag to the event for extra flair.
+     *
+     * @param eventName - The name of the activation event to track.
+     * @param properties - Additional properties to send with the event.
+     * @returns A promise resolving to the API response.
+     */
+    create(config: Config): Promise<ConfigResponse>;
+}
+/**
+ * TrackFeature
+ * Effortlessly track feature usage events (button clicks, feature access, etc.)
+ */
+export declare class TrackFeature extends FTRPC {
+    /**
+     * Records a feature usage event with optional custom properties.
+     *
+     * @param eventName - The name of the feature event to track.
+     * @param properties - Additional metadata to include with the event.
+     * @returns A promise resolving to the API response.
+     */
+    create(config: Config): Promise<ConfigResponse>;
+}
+/**
+ * Represents a specialized event tracker for prompt-related events.
+ *
+ * @extends FTRPC
+ */
+export declare class TrackPrompt extends FTRPC {
+    /**
+     * Creates and initializes a new prompt event with the specified name and properties.
+     *
+     * @param eventName - The name of the event to track.
+     * @param properties - Optional additional properties to associate with the event.
+     *   These will be merged with default properties such as `type` and `timestamp`.
+     * @returns A promise that resolves with the result of the initialization.
+     */
+    create(config: Config): Promise<ConfigResponse>;
+}
+/**
+ * AB TESTING
+ * For tracking A/B test experiment events.
+ */
+export declare class Experiment extends FTRPC {
+    /**
+     * Tracks an A/B test experiment event.
+     *
+     * @param experimentName - The name of the experiment.
+     * @param variant - The variant assigned to the user.
+     * @param properties - Additional properties to send with the event.
+     * @returns A promise resolving to the API response.
+     */
+    track(config: Config & {
+        variant: string;
+    }): Promise<ConfigResponse>;
+}
+/**
+ * Binded Experiment
+ * For binding users to specific experiment variants.
+*/
+export declare class BindedExperiment extends FTRPC {
+    /**
+     * Binds a user to a specific experiment variant.
+     *
+     * @param experimentName - The name of the experiment.
+     * @param variant - The variant to bind the user to.
+     * @param properties - Additional properties to send with the binding.
+     * @returns A promise resolving to the API response.
+     */
+    create(config: Config & {
+        variant: string;
+    }): Promise<ConfigResponse>;
+}
+/**
+ * Feature Flags
+ * For evaluating feature flags.
+*/
+export declare class FeatureFlag extends FTRPC {
+    /**
+     * Evaluates a feature flag for a given user.
+     *
+     * @param flagName - The name of the feature flag to evaluate.
+     * @param properties - Additional properties to send with the evaluation.
+     * @returns A promise resolving to the API response.
+     */
+    evaluate(config: Config): Promise<ConfigResponse>;
+}
+export {};

package/dist/lib/features/analytics/attribution.d.ts

@@ -0,0 +1,257 @@
+/**
+ * @fileoverview Product Analytics - Revenue Attribution
+ * @module features/analytics/attribution
+ *
+ * @description
+ * Multi-touch attribution modeling to understand which marketing
+ * channels and touchpoints drive conversions and revenue.
+ *
+ * @useCases
+ * - Track marketing touchpoints across customer journey
+ * - Calculate attribution for conversions
+ * - Compare attribution models (first-touch, last-touch, linear)
+ * - Optimize marketing spend allocation
+ * - Understand channel effectiveness
+ *
+ * @metrics
+ * - Attributed revenue by channel
+ * - Conversion paths
+ * - Assisted conversions
+ * - Time to conversion
+ * - Channel influence score
+ *
+ * @chartData
+ * - Sankey diagram: Customer journey paths
+ * - Bar chart: Revenue by channel
+ * - Table: Attribution comparison by model
+ * - Pie chart: Channel contribution
+ *
+ * @example
+ * ```typescript
+ * const attribution = new Attribution(webId, endpoint, apiKey);
+ *
+ * // Track touchpoint
+ * await attribution.trackTouchpoint({
+ *   userId: 'user_123',
+ *   channel: 'google_ads',
+ *   campaign: 'brand_terms',
+ *   medium: 'cpc'
+ * });
+ *
+ * // Get attribution report
+ * const report = await attribution.getReport({ range: 'last30days' });
+ * ```
+ */
+import { FTRPC } from "../../client/ftrpc";
+import { MoneyValue, DateRangeFilter } from "../../types";
+/**
+ * Attribution model types.
+ */
+export type AttributionModel = 'first_touch' | 'last_touch' | 'linear' | 'time_decay' | 'position_based' | 'data_driven';
+/**
+ * Marketing touchpoint configuration.
+ */
+export interface TouchpointConfig {
+    /** User ID */
+    userId: string;
+    /** Marketing channel */
+    channel: string;
+    /** Campaign name */
+    campaign?: string;
+    /** Traffic medium */
+    medium?: string;
+    /** Traffic source */
+    source?: string;
+    /** Content/creative */
+    content?: string;
+    /** Search term */
+    term?: string;
+    /** Referrer URL */
+    referrer?: string;
+    /** Landing page */
+    landingPage?: string;
+    /** Custom properties */
+    properties?: Record<string, unknown>;
+}
+/**
+ * Conversion event for attribution.
+ */
+export interface ConversionEvent {
+    /** User ID */
+    userId: string;
+    /** Conversion type */
+    conversionType: 'purchase' | 'signup' | 'lead' | 'custom';
+    /** Conversion value */
+    value?: MoneyValue;
+    /** Conversion identifier (e.g., order ID) */
+    conversionId?: string;
+}
+/**
+ * Touchpoint response from API.
+ */
+export interface TouchpointResponse {
+    eventName: string;
+    properties: Record<string, unknown>;
+    response: {
+        touchpointId: string;
+        userId: string;
+        position: number;
+        tracked: boolean;
+    };
+    timestamp: string;
+}
+/**
+ * Attribution report data.
+ */
+export interface AttributionReportData {
+    /** Selected attribution model */
+    model: AttributionModel;
+    /** Attribution by channel */
+    byChannel: Array<{
+        channel: string;
+        conversions: number;
+        attributedRevenue: MoneyValue;
+        assistedConversions: number;
+        avgTouchpoints: number;
+        firstTouchConversions: number;
+        lastTouchConversions: number;
+    }>;
+    /** Top conversion paths */
+    topPaths: Array<{
+        path: string[];
+        conversions: number;
+        revenue: MoneyValue;
+        avgTimeToConvert: number;
+    }>;
+    /** Summary metrics */
+    summary: {
+        totalConversions: number;
+        totalRevenue: MoneyValue;
+        avgTouchpointsPerConversion: number;
+        avgTimeToConversion: number;
+        topChannel: string;
+        topCampaign: string;
+    };
+    /** Model comparison */
+    modelComparison: Array<{
+        model: AttributionModel;
+        channelAttribution: Record<string, number>;
+    }>;
+}
+/**
+ * Attribution - Multi-touch attribution tracking.
+ *
+ * @extends FTRPC
+ *
+ * @description
+ * Provides attribution capabilities including:
+ * - Touchpoint tracking
+ * - Conversion attribution
+ * - Multiple attribution models
+ * - Path analysis
+ * - Channel effectiveness
+ *
+ * @example
+ * ```typescript
+ * const attribution = new Attribution(webId, endpoint, apiKey);
+ *
+ * // Track touchpoints throughout customer journey
+ * await attribution.trackTouchpoint({
+ *   userId: 'user_123',
+ *   channel: 'email',
+ *   campaign: 'welcome_series',
+ *   medium: 'email'
+ * });
+ *
+ * // Record conversion
+ * await attribution.recordConversion({
+ *   userId: 'user_123',
+ *   conversionType: 'purchase',
+ *   value: { amount: 9999, currency: 'USD' },
+ *   conversionId: 'ORD-12345'
+ * });
+ *
+ * // Get attribution report
+ * const report = await attribution.getReport({
+ *   model: 'linear'
+ * });
+ * ```
+ */
+export declare class Attribution extends FTRPC {
+    /**
+     * Tracks a marketing touchpoint.
+     *
+     * @param config - Touchpoint configuration
+     * @returns Promise resolving to touchpoint response
+     *
+     * @example
+     * ```typescript
+     * await attribution.trackTouchpoint({
+     *   userId: 'user_123',
+     *   channel: 'facebook_ads',
+     *   campaign: 'retargeting_cart',
+     *   medium: 'paid_social',
+     *   landingPage: '/products/special-offer'
+     * });
+     * ```
+     */
+    trackTouchpoint(config: TouchpointConfig): Promise<TouchpointResponse>;
+    /**
+     * Records a conversion for attribution.
+     *
+     * @param event - Conversion event
+     * @returns Promise resolving to conversion response
+     *
+     * @example
+     * ```typescript
+     * await attribution.recordConversion({
+     *   userId: 'user_123',
+     *   conversionType: 'purchase',
+     *   value: { amount: 14999, currency: 'USD' },
+     *   conversionId: 'ORD-98765'
+     * });
+     * ```
+     */
+    recordConversion(event: ConversionEvent): Promise<TouchpointResponse>;
+    /**
+     * Gets attribution report with specified model.
+     *
+     * @param options - Report options
+     * @returns Promise resolving to attribution report
+     *
+     * @example
+     * ```typescript
+     * const report = await attribution.getReport({
+     *   model: 'position_based',
+     *   filter: { range: 'last30days' }
+     * });
+     *
+     * // Bar chart - revenue by channel
+     * const channelChart = report.byChannel.map(c => ({
+     *   name: c.channel,
+     *   value: c.attributedRevenue.amount
+     * }));
+     *
+     * // Sankey - top conversion paths
+     * const pathData = report.topPaths;
+     * ```
+     */
+    getReport(options?: {
+        model?: AttributionModel;
+        filter?: DateRangeFilter;
+    }): Promise<AttributionReportData>;
+    /**
+     * Gets user journey/path for a specific user.
+     *
+     * @param userId - User identifier
+     * @returns Promise resolving to user journey data
+     */
+    getUserJourney(userId: string): Promise<{
+        touchpoints: Array<TouchpointConfig & {
+            timestamp: string;
+        }>;
+        conversions: ConversionEvent[];
+        totalValue: MoneyValue;
+    }>;
+}
+export default Attribution;