flowgrid-sdk 1.0.1 → 1.1.0

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

@@ -12,32 +12,121 @@
  *  await this.init('eventName', { key: 'value' });
  * ```
  */
+/**
+ * FTRPC - Core transport layer for Flowgrid SDK.
+ *
+ * @description
+ * Provides a secure, validated RPC-style transport layer used by all SDK modules.
+ * Handles:
+ * - Input validation
+ * - Payload size enforcement
+ * - Timeout handling
+ * - Retry logic (network failures only)
+ * - Authorization headers
+ *
+ * This class is designed to be extended by higher-level modules
+ * (e.g., FeatureFlag, Analytics, Experiments).
+ *
+ * @example
+ * ```ts
+ * const client = new FTRPC("web_123", "api.flowgrid.com", "sk_live_xxx");
+ * ```
+ */
 export declare class FTRPC {
     /**
-     * Web ID for the specific site or application.
-     * Used to identify the event source.
+     * Unique Web ID identifying the site or application.
+     * Used by the backend to associate incoming events.
      */
     protected webId: string;
     /**
-     * API endpoint for sending events.
-     * Example: "https://api.flowgrid.com"
+     * Base API endpoint.
+     * Example values:
+     * - "api.flowgrid.com"
+     * - "https://api.flowgrid.com"
+     *
+     * Protocol is normalized automatically.
      */
     protected endpoint: string;
     /**
-     * API Key for authenticating requests.
+     * Private API key used for authenticating requests.
+     * Sent as a Bearer token in the Authorization header.
      */
     private apiKey;
+    /**
+     * Maximum allowed payload size (in bytes).
+     * Prevents oversized event submissions.
+     */
+    private static readonly MAX_PAYLOAD_SIZE;
+    /**
+     * Maximum time (ms) before request is aborted.
+     */
+    private static readonly TIMEOUT_MS;
+    /**
+     * Maximum retry attempts for network-level failures.
+     * Does NOT retry HTTP 4xx/5xx responses.
+     */
+    private static readonly MAX_RETRIES;
+    /**
+     * Creates a new FTRPC transport instance.
+     *
+     * @param webId - Unique identifier for the web property.
+     * @param endpoint - API base endpoint.
+     * @param apiKey - Private API key for authentication.
+     *
+     * @throws {Error} If required parameters are missing.
+     */
     constructor(webId: string, endpoint: string, apiKey: string);
     /**
-     * Sends an event to the API.
-     * Used internally by subclasses to track events.
+     * Core RPC transport method.
      *
-     * @param eventName - Name of the event to track.
-     * @param properties - Additional properties to send with the event.
+     * @template T Expected JSON response type.
+     *
+     * @param eventName - Logical event or function name.
+     * @param properties - Arbitrary event payload properties.
+     * @param method - HTTP method ("GET", "POST", "PATCH").
+     *
+     * @returns Promise resolving to typed response.
+     *
+     * @remarks
+     * - GET requests are treated as read-only operations.
+     * - POST/PATCH requests may mutate backend state.
+     * - Retries occur only for network failures or timeouts.
+     */
+    protected init<T>(eventName: string, properties?: Record<string, any>, method?: "GET" | "POST" | "PATCH"): Promise<T>;
+    /**
+     * Executes HTTP request with timeout and retry handling.
+     *
+     * @template T Expected response type.
+     *
+     * @param url - Fully constructed request URL.
+     * @param method - HTTP method.
+     * @param body - Optional JSON body (POST/PATCH only).
+     *
+     * @throws {Error} On timeout, network failure, or non-OK HTTP status.
      */
-    protected init<T>(eventName: string, properties?: Record<string, any>, request?: "GET" | "POST" | "PATCH"): Promise<T>;
+    private executeRequest;
     /**
-     * Validates input parameters for security and correctness.
+     * Validates event name and payload.
+     *
+     * @param eventName - Event identifier.
+     * @param properties - Associated event properties.
+     *
+     * @throws {Error} If validation fails.
      */
     private validateInput;
+    /**
+     * Normalizes endpoint input.
+     * Ensures protocol is present and removes trailing slashes.
+     *
+     * @param endpoint - Raw endpoint string.
+     * @returns Normalized endpoint URL.
+     */
+    private normalizeEndpoint;
+    /**
+     * Safely reads response text without throwing.
+     *
+     * @param res - Fetch Response object.
+     * @returns Response text or empty string.
+     */
+    private safeRead;
 }

package/dist/lib/features/core/experiment.d.ts

@@ -40,114 +40,156 @@
 import { FTRPC } from "../../client/ftrpc";
 import { DateRangeFilter, TimeSeriesData } from "../../types";
 /**
- * Base experiment configuration.
+ * Configuration for tracking an experiment-related event.
+ *
+ * Used when sending a generic experiment event with a specific variant
+ * and associated properties.
  */
 export interface ExperimentConfig {
-    /** Experiment/event name */
+    /** Logical experiment event name */
     eventName: string;
-    /** Assigned variant */
+    /** Variant identifier associated with this event */
     variant: string;
-    /** Event properties */
+    /** Additional contextual event data */
     properties: Record<string, unknown>;
 }
 /**
- * Experiment definition.
+ * Defines the structure and metadata of an experiment.
+ *
+ * Used when creating or updating an experiment configuration.
  */
 export interface ExperimentDefinition {
-    /** Experiment ID */
+    /** Unique identifier for the experiment */
     experimentId: string;
-    /** Experiment name */
+    /** Human-readable experiment name */
     name: string;
-    /** Description */
+    /** Optional description of experiment purpose */
     description?: string;
-    /** Variants */
+    /** Variants participating in the experiment */
     variants: Array<{
+        /** Unique identifier for the variant */
         variantId: string;
+        /** Human-readable variant name */
         name: string;
+        /** Traffic allocation weight (relative distribution) */
         weight: number;
     }>;
-    /** Target audience (optional) */
+    /**
+     * Optional audience configuration.
+     * Allows limiting exposure by percentage and/or filter conditions.
+     */
     audience?: {
+        /** Percentage of total traffic eligible (0–100) */
         percentage: number;
+        /** Attribute-based targeting filters */
         filters?: Record<string, unknown>;
     };
-    /** Primary metric */
+    /** Primary metric used to evaluate experiment success */
     primaryMetric: string;
-    /** Secondary metrics */
+    /** Optional secondary metrics */
     secondaryMetrics?: string[];
-    /** Start date */
+    /** Optional ISO start date */
     startDate?: string;
-    /** End date */
+    /** Optional ISO end date */
     endDate?: string;
 }
 /**
- * Experiment assignment configuration.
+ * Configuration for assigning a user to a specific experiment variant.
+ *
+ * Represents an explicit assignment event.
  */
 export interface ExperimentAssignmentConfig {
-    /** Experiment ID */
+    /** Experiment identifier */
     experimentId: string;
-    /** User ID */
+    /** Unique user identifier */
     userId: string;
-    /** Assigned variant ID */
+    /** Assigned variant identifier */
     variantId: string;
-    /** Assignment source */
+    /**
+     * Assignment origin:
+     * - random: weighted allocation
+     * - targeted: rule-based assignment
+     * - override: manual or forced assignment
+     */
     source?: 'random' | 'targeted' | 'override';
 }
 /**
- * Experiment conversion configuration.
+ * Configuration for recording a conversion event within an experiment.
+ *
+ * Used to attribute metric changes to a specific variant.
  */
 export interface ExperimentConversionConfig {
-    /** Experiment ID */
+    /** Experiment identifier */
     experimentId: string;
-    /** User ID */
+    /** Unique user identifier */
     userId: string;
-    /** Variant ID */
+    /** Variant associated with the user */
     variantId: string;
-    /** Metric name */
+    /** Metric name being recorded */
     metricName: string;
-    /** Metric value */
+    /** Numeric metric value */
     value: number;
 }
 /**
- * Experiment tracking response.
+ * Standardized response returned from experiment tracking operations.
+ *
+ * Ensures consistent structure across assignment, exposure,
+ * definition, and conversion events.
  */
 export interface ExperimentResponse {
+    /** Event name associated with the request */
     eventName: string;
+    /** Properties sent with the event */
     properties: Record<string, unknown>;
+    /** Server acknowledgment metadata */
     response: {
+        /** Indicates whether the event was successfully recorded */
         tracked: boolean;
+        /** Optional experiment identifier */
         experimentId?: string;
+        /** Optional variant identifier */
         variantId?: string;
     };
+    /** ISO timestamp of the recorded event */
     timestamp: string;
 }
 /**
- * Experiment results data.
+ * Aggregated results for a single experiment.
+ *
+ * Represents computed performance metrics per variant.
  */
 export interface ExperimentResultsData {
-    /** Experiment info */
+    /** Experiment metadata */
     experiment: {
         experimentId: string;
         name: string;
         status: 'running' | 'paused' | 'completed';
         startDate: string;
+        /** Duration in days */
         duration: number;
     };
-    /** Results by variant */
+    /** Variant-level performance metrics */
     variants: Array<{
         variantId: string;
         name: string;
+        /** Total participants assigned */
         participants: number;
+        /** Total recorded conversions */
         conversions: number;
+        /** conversions / participants */
         conversionRate: number;
+        /** Relative improvement compared to baseline */
         improvement: number;
+        /** Statistical confidence level (0–1 or percentage depending on backend) */
         confidence: number;
+        /** Indicates highest performing variant */
         isWinner: boolean;
+        /** Indicates whether statistical threshold is met */
         isStatisticallySignificant: boolean;
     }>;
-    /** Metric trends */
+    /** Time-series metric trends per metric name */
     trends: Record<string, TimeSeriesData>;
-    /** Recommendation */
+    /** System-generated recommendation */
     recommendation: {
         action: 'ship_winner' | 'continue' | 'stop' | 'needs_more_data';
         winningVariant?: string;
@@ -156,10 +198,12 @@ export interface ExperimentResultsData {
     };
 }
 /**
- * All experiments analytics.
+ * Aggregated analytics across all experiments.
+ *
+ * Provides high-level performance and activity overview.
  */
 export interface ExperimentAnalyticsData {
-    /** Summary */
+    /** Platform-wide experiment summary */
     summary: {
         totalExperiments: number;
         activeExperiments: number;
@@ -167,7 +211,7 @@ export interface ExperimentAnalyticsData {
         avgExperimentDuration: number;
         winRate: number;
     };
-    /** Active experiments */
+    /** Currently active experiments */
     active: Array<{
         experimentId: string;
         name: string;
@@ -176,7 +220,7 @@ export interface ExperimentAnalyticsData {
         leadingVariant: string;
         confidence: number;
     }>;
-    /** Recent results */
+    /** Recently completed experiments */
     recentResults: Array<{
         experimentId: string;
         name: string;
@@ -185,24 +229,57 @@ export interface ExperimentAnalyticsData {
         completedDate: string;
     }>;
 }
+export interface VariantResponse {
+    experimentId: string;
+    userId?: string;
+    variantId: string;
+    assignedAt: string;
+}
 /**
- * Experiment - Track A/B tests and experiments.
+ * Experiment - A/B Testing & Experimentation SDK
  *
  * @extends FTRPC
  *
  * @description
- * Provides experiment tracking including:
+ * Provides structured experiment lifecycle management including:
  * - Experiment definition
- * - Variant assignment
+ * - Deterministic or server-based variant assignment
+ * - Exposure tracking
  * - Conversion tracking
- * - Results analysis
- * - Statistical significance
+ * - Statistical results & analysis
+ *
+ * This class enforces correct HTTP semantics:
+ *
+ * Exposure and conversion events are strictly POST to preserve:
+ * - Statistical validity
+ * - Unique participant counting
+ * - Accurate conversion attribution
+ * - Idempotent replay safety
+ *
+ * @lifecycle
+ * 1. Define experiment
+ * 2. Assign user to variant
+ * 3. Track exposure (when user actually sees variant)
+ * 4. Track conversions (primary/secondary metrics)
+ * 5. Query results & statistical analysis
+ *
+ * @statistical_model
+ * - Variant-level sample sizes tracked independently
+ * - Conversion rates calculated per variant
+ * - Confidence intervals computed server-side
+ * - Statistical significance evaluated against control
+ *
+ * @guarantees
+ * - Assignment is explicitly recorded
+ * - Exposure tracking is immutable
+ * - Conversion events are attributable to assigned variant
+ * - Results queries never mutate experiment state
  *
  * @example
  * ```typescript
  * const experiment = new Experiment(webId, endpoint, apiKey);
  *
- * // Define experiment
+ * // 1. Define experiment
  * await experiment.define({
  *   experimentId: 'checkout_v2',
  *   name: 'Simplified Checkout',
@@ -213,14 +290,17 @@ export interface ExperimentAnalyticsData {
  *   primaryMetric: 'checkout_completed'
  * });
  *
- * // Assign user to variant
+ * // 2. Assign user
  * await experiment.assign({
  *   experimentId: 'checkout_v2',
  *   userId: 'user_123',
  *   variantId: 'treatment'
  * });
  *
- * // Track conversion
+ * // 3. Track exposure
+ * await experiment.trackExposure('checkout_v2', 'user_123', 'treatment');
+ *
+ * // 4. Track conversion
  * await experiment.trackConversion({
  *   experimentId: 'checkout_v2',
  *   userId: 'user_123',
@@ -228,6 +308,9 @@ export interface ExperimentAnalyticsData {
  *   metricName: 'checkout_completed',
  *   value: 1
  * });
+ *
+ * // 5. Fetch results
+ * const results = await experiment.getResults('checkout_v2');
  * ```
  */
 export declare class Experiment extends FTRPC {
@@ -246,34 +329,68 @@ export declare class Experiment extends FTRPC {
      */
     define(definition: ExperimentDefinition): Promise<ExperimentResponse>;
     /**
-     * Assigns a user to an experiment variant.
-     *
-     * @param config - Assignment configuration
-     * @returns Promise resolving to experiment response
-     */
+   * Assigns a user to a variant.
+    *
+    * This operation records assignment.
+    * Assignment should occur before exposure tracking.
+    *
+    * @param config - Assignment configuration
+    * @returns Promise resolving to ExperimentResponse
+    *
+    * @notes
+    * - Assignment does not imply exposure.
+    * - Exposure must be tracked separately when the variant is rendered.
+   */
     assign(config: ExperimentAssignmentConfig): Promise<ExperimentResponse>;
     /**
-     * Tracks a conversion for an experiment.
+     * Records a conversion event for an experiment.
+     *
+     * Conversion events are attributed to the user's assigned variant.
+     * Supports primary and secondary metrics.
      *
      * @param config - Conversion configuration
-     * @returns Promise resolving to experiment response
-     */
+     * @returns Promise resolving to ExperimentResponse
+     *
+     * @statistical_impact
+     * Conversion data directly affects:
+     * - Conversion rate calculations
+     * - Variant improvement %
+     * - Confidence intervals
+     * - Statistical significance evaluation
+    */
     trackConversion(config: ExperimentConversionConfig): Promise<ExperimentResponse>;
     /**
-     * Tracks user exposure to an experiment.
+     * Records that a user was exposed to a variant.
      *
-     * @param experimentId - Experiment ID
-     * @param userId - User ID
-     * @param variantId - Variant ID
-     * @returns Promise resolving to experiment response
-     */
+     * Exposure tracking is required for valid experiment analysis.
+     * This ensures participants are counted correctly.
+     *
+     * @param experimentId - Experiment identifier
+     * @param userId - Unique user identifier
+     * @param variantId - Assigned variant identifier
+     * @returns Promise resolving to ExperimentResponse
+     *
+     * @important
+     * Exposure must only be tracked once per user per experiment.
+     * Duplicate exposures may inflate participant counts.
+    */
     trackExposure(experimentId: string, userId: string, variantId: string): Promise<ExperimentResponse>;
     /**
-     * Gets results for a specific experiment.
+     * Retrieves statistical results for an experiment.
      *
-     * @param experimentId - Experiment ID
-     * @returns Promise resolving to experiment results
-     */
+     * No experiment state is modified.
+     *
+     * @param experimentId - Experiment identifier
+     * @returns Promise resolving to ExperimentResultsData
+     *
+     * @returns_data
+     * - Variant performance metrics
+     * - Conversion rates
+     * - Improvement vs control
+     * - Statistical significance flags
+     * - Confidence levels
+     * - Recommendation engine output
+    */
     getResults(experimentId: string): Promise<ExperimentResultsData>;
     /**
      * Gets experiment analytics overview.
@@ -282,5 +399,13 @@ export declare class Experiment extends FTRPC {
      * @returns Promise resolving to experiment analytics
      */
     getAnalytics(filter?: DateRangeFilter): Promise<ExperimentAnalyticsData>;
+    /**
+     * Retrieves the variant assigned to a user for a specific experiment.
+     *
+     * @param experimentId - Experiment identifier
+     * @param userId - Unique user identifier
+     * @returns Promise resolving to VariantResponse, or null if no variant is assigned
+     */
+    getVariant(experimentId: string, userId: string): Promise<VariantResponse | null>;
 }
 export default Experiment;

package/dist/lib/features/core/feature-flag.d.ts

@@ -37,7 +37,7 @@
  * ```
  */
 import { FTRPC } from "../../client/ftrpc";
-import { DateRangeFilter, TimeSeriesData } from "../../types";
+import { TimeSeriesData } from "../../types";
 /**
  * Base feature flag configuration.
  */
@@ -245,20 +245,5 @@ export declare class FeatureFlag extends FTRPC {
      * @returns Promise resolving to flag response
      */
     trackRolloutChange(flagKey: string, previousPercentage: number, newPercentage: number, changedBy?: string): Promise<FlagResponse>;
-    /**
-     * Gets analytics for a specific flag.
-     *
-     * @param flagKey - Flag key
-     * @param filter - Date range filter
-     * @returns Promise resolving to flag analytics
-     */
-    getFlagAnalytics(flagKey: string, filter?: DateRangeFilter): Promise<FlagAnalyticsData>;
-    /**
-     * Gets analytics for all flags.
-     *
-     * @param filter - Date range filter
-     * @returns Promise resolving to all flags analytics
-     */
-    getAnalytics(filter?: DateRangeFilter): Promise<AllFlagsAnalyticsData>;
 }
 export default FeatureFlag;

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

@@ -31,21 +31,30 @@
  * const trackFeature = new TrackFeature(webId, endpoint, apiKey);
  *
  * await trackFeature.create({
- *   eventName: 'export_report',
- *   properties: { format: 'csv', rowCount: 1000 }
+ *   userId: 'user_123',
+ *   action: 'export_report',
+ *   properties: { featureName: 'export_report', featureId: 'export_report_001' }
  * });
  * ```
  */
 import { FTRPC } from "../../client/ftrpc";
 import { DateRangeFilter, TimeSeriesData } from "../../types";
+type FeatureConfigProperties = {
+    featureId?: string;
+    featureName: string;
+    metadata?: Record<string, unknown>;
+};
 /**
  * Base configuration for feature tracking.
  */
 export interface FeatureConfig {
-    /** Event/feature name */
-    eventName: string;
+    /** Feature tracking properties */
+    action: string;
+    /** Feature category */
+    category?: string;
+    userId: string;
     /** Event properties */
-    properties: Record<string, unknown>;
+    properties: FeatureConfigProperties;
 }
 /**
  * Detailed feature usage configuration.
@@ -77,7 +86,7 @@ export interface FeatureDiscoveryConfig {
     /** User ID */
     userId: string;
     /** How feature was discovered */
-    discoveryMethod: 'organic' | 'tooltip' | 'announcement' | 'search' | 'onboarding' | 'recommendation';
+    discoveryMethod: 'organic' | 'tooltip' | 'announcement' | 'search' | 'onboarding' | 'recommendation' | string;
     /** Whether user engaged with feature */
     engaged: boolean;
 }
@@ -143,8 +152,6 @@ export interface FeatureAnalyticsData {
  * - Generic feature events
  * - Detailed usage tracking
  * - Feature discovery tracking
- * - Adoption analytics
- * - Engagement metrics
  *
  * @example
  * ```typescript
@@ -152,8 +159,9 @@ export interface FeatureAnalyticsData {
  *
  * // Simple feature tracking
  * await trackFeature.create({
- *   eventName: 'dark_mode_enabled',
- *   properties: { userId: 'user_123' }
+ *   userId: 'user_123',
+ *   action: 'dark_mode_enabled',
+ *   properties: { featureName: 'dark_mode' }
  * });
  *
  * // Detailed feature usage
@@ -183,32 +191,6 @@ export declare class TrackFeature extends FTRPC {
      * @returns Promise resolving to feature response
      */
     trackUsage(config: FeatureUsageConfig): Promise<FeatureResponse>;
-    /**
-     * Tracks feature discovery.
-     *
-     * @param config - Feature discovery configuration
-     * @returns Promise resolving to feature response
-     */
-    trackDiscovery(config: FeatureDiscoveryConfig): Promise<FeatureResponse>;
-    /**
-     * Tracks feature adoption (first-time use).
-     *
-     * @param featureId - Feature identifier
-     * @param userId - User ID
-     * @param source - How user found feature
-     * @returns Promise resolving to feature response
-     */
-    trackAdoption(featureId: string, userId: string, source?: string): Promise<FeatureResponse>;
-    /**
-     * Tracks feature abandonment.
-     *
-     * @param featureId - Feature identifier
-     * @param userId - User ID
-     * @param reason - Abandonment reason
-     * @param timeSpent - Time spent before abandoning (ms)
-     * @returns Promise resolving to feature response
-     */
-    trackAbandonment(featureId: string, userId: string, reason?: string, timeSpent?: number): Promise<FeatureResponse>;
     /**
      * Gets feature analytics for dashboards.
      *

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

@@ -266,7 +266,7 @@ export declare class Checkout extends FTRPC {
      *   cart: shoppingCart,
      *   payment: {
      *     method: 'credit_card',
-     *     provider: 'Stripe',
+     *     provider: 'stripe',
      *     cardBrand: 'Mastercard',
      *     cardLast4: '4242'
      *   }