flowgrid-sdk 1.1.0 → 1.2.1

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

@@ -42,7 +42,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { UserTraits, MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Configuration for identifying a user.
@@ -126,7 +126,7 @@ export interface UserAnalyticsData {
 /**
  * Identify - User identification and trait management.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides user identification capabilities including:
@@ -160,7 +160,7 @@ export interface UserAnalyticsData {
  * });
  * ```
  */
-export declare class Identify extends FTRPC {
+export declare class Identify extends FlowGridTransport {
     /**
      * Identifies a user with traits.
      *

package/dist/lib/features/analytics/page-views.d.ts

@@ -46,7 +46,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { TimeSeriesData, DateRangeFilter, PaginationParams } from "../../types";
 /**
  * Configuration for tracking a page view.
@@ -128,7 +128,7 @@ export interface PageAnalyticsData {
 /**
  * PageViews - Track and analyze page view events.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides comprehensive page view tracking with support for:
@@ -161,7 +161,7 @@ export interface PageAnalyticsData {
  * }));
  * ```
  */
-export declare class PageViews extends FTRPC {
+export declare class PageViews extends FlowGridTransport {
     /**
      * Tracks a page view event.
      *

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

@@ -39,7 +39,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Core Web Vitals data.
@@ -190,7 +190,7 @@ export interface PerformanceAnalyticsData {
 /**
  * Performance - Track web performance metrics.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides performance monitoring including:
@@ -219,7 +219,7 @@ export interface PerformanceAnalyticsData {
  * console.log(`Performance Score: ${report.performanceScore}`);
  * ```
  */
-export declare class PerformanceTracking extends FTRPC {
+export declare class PerformanceTracking extends FlowGridTransport {
     /**
      * Tracks Core Web Vitals.
      *

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

@@ -43,7 +43,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { RetentionCohort, UserLifecycleStage, LifecycleMetrics, DateRangeFilter, TimeGranularity, TimeSeriesData } from "../../types";
 /**
  * Configuration for tracking user activity.
@@ -152,7 +152,7 @@ export interface ChurnAnalysisData {
 /**
  * Retention - Track and analyze user retention.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides retention analysis capabilities including:
@@ -182,7 +182,7 @@ export interface ChurnAnalysisData {
  * const heatmapData = analysis.matrix;
  * ```
  */
-export declare class Retention extends FTRPC {
+export declare class Retention extends FlowGridTransport {
     /**
      * Tracks user activity for retention calculation.
      *

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

@@ -43,7 +43,7 @@
  * await sessions.end(session.sessionId);
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { DeviceInfo, GeoLocation, UTMParams, TimeSeriesData, DateRangeFilter, PaginationParams, UserIdentity } from "../../types";
 /**
  * Configuration for starting a new session.
@@ -156,7 +156,7 @@ export interface RealTimeSessionData {
 /**
  * Sessions - Track and analyze user sessions.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides comprehensive session tracking including:
@@ -183,7 +183,7 @@ export interface RealTimeSessionData {
  * console.log(`${realTime.activeSessions} users online`);
  * ```
  */
-export declare class Sessions extends FTRPC {
+export declare class Sessions extends FlowGridTransport {
     /**
      * Starts a new user session.
      *

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

@@ -37,7 +37,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Base configuration for activation events.
@@ -139,7 +139,7 @@ export interface ActivationAnalyticsData {
 /**
  * Activation - Track user activation events.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides activation tracking including:
@@ -170,7 +170,7 @@ export interface ActivationAnalyticsData {
  * });
  * ```
  */
-export declare class Activation extends FTRPC {
+export declare class Activation extends FlowGridTransport {
     /**
      * Creates and tracks an activation event.
      *

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

@@ -37,7 +37,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Configuration for tracking an experiment-related event.
@@ -235,10 +235,31 @@ export interface VariantResponse {
     variantId: string;
     assignedAt: string;
 }
+/**
+ * Local experiment variant definition used by the client-side
+ * assignment engine (ported from sdk.js).
+ */
+export interface ExperimentVariant {
+    /** Variant identifier */
+    id: string;
+    /** Traffic allocation weight */
+    weight: number;
+}
+/**
+ * Lightweight experiment config passed to `initExperiments()`.
+ */
+export interface ExperimentInitConfig {
+    /** Unique experiment identifier */
+    id: string;
+    /** Weighted variant list */
+    variants: ExperimentVariant[];
+    /** Optional properties forwarded to the verify endpoint */
+    properties?: Record<string, unknown>;
+}
 /**
  * Experiment - A/B Testing & Experimentation SDK
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides structured experiment lifecycle management including:
@@ -313,98 +334,93 @@ export interface VariantResponse {
  * const results = await experiment.getResults('checkout_v2');
  * ```
  */
-export declare class Experiment extends FTRPC {
+export declare class Experiment extends FlowGridTransport {
+    /** Verified experiment configs: { [experiment_id]: { variants, properties, verified } } */
+    private experiments;
+    /** Local variant assignments: { [experiment_id]: variant_id } */
+    private assignments;
+    private loadAssignments;
+    private saveAssignments;
+    /**
+     * Inject assignments from server context (SSR/Node).
+     * Use this when assignments were resolved server-side and need to be
+     * available before localStorage is accessible.
+     */
+    injectAssignments(assignments: Record<string, string>): void;
+    /**
+     * Returns all current assignments (for SSR hydration).
+     */
+    getAssignments(): Record<string, string>;
+    private static readonly ANON_ID_KEY;
     /**
-     * Tracks an experiment event.
+     * Returns a stable anonymous ID. Generates a UUID on first call and
+     * persists it in localStorage so the same anonymous visitor always
+     * receives a consistent variant assignment.
+     */
+    private getOrCreateAnonId;
+    /**
+     * Deterministic variant assignment using FNV-1a hash.
+     * Same userId + experimentId always produces the same variant.
+     */
+    private deterministicAssign;
+    private assignVariant;
+    private verifyExperiments;
+    /**
+     * Initialise the client-side experiment engine.
+     *
+     * Verifies experiment configs against the API, assigns variants using
+     * weighted random allocation, and persists assignments in localStorage
+     * under `fg_exp_assignments`.
      *
-     * @param config - Experiment configuration
-     * @returns Promise resolving to experiment response
+     * @param experiments - Array of experiment configs to register
+     */
+    initExperiments(experiments: ExperimentInitConfig[]): Promise<void>;
+    /**
+     * Returns the locally assigned variant for an experiment.
+     *
+     * Reads from the in-memory assignment map (backed by localStorage).
+     * Returns `null` if no assignment exists.
+     */
+    getLocalVariant(experimentId: string): string | null;
+    /**
+     * Track a conversion against the locally assigned variant.
+     *
+     * No-op if the visitor has no assignment for this experiment.
+     */
+    trackLocalConversion(experimentId: string, metricName?: string, metricValue?: number): Promise<void>;
+    /**
+     * @deprecated Use `assign()`, `trackExposure()`, or `trackConversion()` instead.
+     * The generic `track()` method sends events without a subtype, which the
+     * backend handler rejects. It is retained only for backwards compatibility
+     * and will be removed in a future major version.
      */
     track(config: ExperimentConfig): Promise<ExperimentResponse>;
     /**
      * Defines a new experiment.
-     *
-     * @param definition - Experiment definition
-     * @returns Promise resolving to experiment response
      */
     define(definition: ExperimentDefinition): Promise<ExperimentResponse>;
     /**
-   * 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.
-   */
+     * Assigns a user to a variant.
+     */
     assign(config: ExperimentAssignmentConfig): Promise<ExperimentResponse>;
     /**
      * 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 ExperimentResponse
-     *
-     * @statistical_impact
-     * Conversion data directly affects:
-     * - Conversion rate calculations
-     * - Variant improvement %
-     * - Confidence intervals
-     * - Statistical significance evaluation
-    */
+     */
     trackConversion(config: ExperimentConversionConfig): Promise<ExperimentResponse>;
     /**
      * Records that a user was exposed to a variant.
-     *
-     * 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>;
     /**
      * Retrieves statistical results for an experiment.
-     *
-     * 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.
-     *
-     * @param filter - Date range filter
-     * @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
+     * Retrieves the variant assigned to a user for a specific experiment (server-side).
      */
     getVariant(experimentId: string, userId: string): Promise<VariantResponse | null>;
 }

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

@@ -6,9 +6,7 @@ export { Activation } from './activation';
 export { TrackFeature } from './track-feature';
 export { TrackPrompt } from './track-prompt';
 export { Experiment } from './experiment';
-export { FeatureFlag } from './feature-flag';
 export type { ActivationConfig, OnboardingStepConfig, FirstActionConfig, ActivationResponse, ActivationAnalyticsData } from './activation';
 export type { FeatureConfig, FeatureUsageConfig, FeatureDiscoveryConfig, FeatureResponse, FeatureAnalyticsData } from './track-feature';
 export type { PromptConfig, PromptSubmissionConfig, PromptResponseConfig, PromptFeedbackConfig, PromptResponse, PromptAnalyticsData } from './track-prompt';
-export type { ExperimentConfig, ExperimentDefinition, ExperimentAssignmentConfig, ExperimentConversionConfig, ExperimentResponse, ExperimentResultsData, ExperimentAnalyticsData } from './experiment';
-export type { FlagConfig, FlagDefinition, FlagEvaluationConfig, FlagResponse, FlagAnalyticsData, AllFlagsAnalyticsData } from './feature-flag';
+export type { ExperimentConfig, ExperimentDefinition, ExperimentAssignmentConfig, ExperimentConversionConfig, ExperimentResponse, ExperimentResultsData, ExperimentAnalyticsData, ExperimentVariant, ExperimentInitConfig, VariantResponse } from './experiment';

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

@@ -37,7 +37,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { DateRangeFilter, TimeSeriesData } from "../../types";
 type FeatureConfigProperties = {
     featureId?: string;
@@ -145,7 +145,7 @@ export interface FeatureAnalyticsData {
 /**
  * TrackFeature - Track feature usage events.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides feature tracking including:
@@ -176,7 +176,7 @@ export interface FeatureAnalyticsData {
  * });
  * ```
  */
-export declare class TrackFeature extends FTRPC {
+export declare class TrackFeature extends FlowGridTransport {
     /**
      * Records a feature usage event.
      *

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

@@ -39,7 +39,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Base configuration for prompt events.
@@ -158,7 +158,7 @@ export interface PromptAnalyticsData {
 /**
  * TrackPrompt - Track AI prompt interactions.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides prompt tracking including:
@@ -197,7 +197,7 @@ export interface PromptAnalyticsData {
  * });
  * ```
  */
-export declare class TrackPrompt extends FTRPC {
+export declare class TrackPrompt extends FlowGridTransport {
     /**
      * Creates and tracks a prompt event.
      *

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

@@ -38,7 +38,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { Product, Cart, DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Configuration for adding item to cart.
@@ -143,7 +143,7 @@ export interface CartAnalyticsData {
 /**
  * CartTracking - Track shopping cart interactions.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides cart tracking capabilities including:
@@ -175,7 +175,7 @@ export interface CartAnalyticsData {
  * });
  * ```
  */
-export declare class CartTracking extends FTRPC {
+export declare class CartTracking extends FlowGridTransport {
     /**
      * Tracks adding an item to cart.
      *

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

@@ -44,7 +44,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { Cart, CheckoutStep, ShippingInfo, PaymentInfo, DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Configuration for beginning checkout.
@@ -159,7 +159,7 @@ export interface CheckoutAnalyticsData {
 /**
  * Checkout - Track checkout flow and payments.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides checkout tracking capabilities including:
@@ -196,7 +196,7 @@ export interface CheckoutAnalyticsData {
  * });
  * ```
  */
-export declare class Checkout extends FTRPC {
+export declare class Checkout extends FlowGridTransport {
     /**
      * Tracks checkout initiation.
      *

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

@@ -39,7 +39,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Stock update configuration.
@@ -129,7 +129,7 @@ export interface InventoryAnalyticsData {
 /**
  * Inventory - Track inventory and stock events.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides inventory tracking including:
@@ -160,7 +160,7 @@ export interface InventoryAnalyticsData {
  * });
  * ```
  */
-export declare class Inventory extends FTRPC {
+export declare class Inventory extends FlowGridTransport {
     /**
      * Tracks stock level update.
      *

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

@@ -37,7 +37,7 @@
  * const analytics = await ltv.getAnalytics({ range: 'last90days' });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Customer value data.
@@ -139,7 +139,7 @@ export interface LTVAnalyticsData {
 /**
  * CustomerLTV - Calculate and track customer lifetime value.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides LTV tracking capabilities including:
@@ -170,7 +170,7 @@ export interface LTVAnalyticsData {
  * console.log(`LTV:CAC Ratio: ${analytics.summary.ltvCacRatio}`);
  * ```
  */
-export declare class CustomerLTV extends FTRPC {
+export declare class CustomerLTV extends FlowGridTransport {
     /**
      * Gets lifetime value data for a specific customer.
      *

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

@@ -40,7 +40,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { Product, ProductList, ProductPerformance, DateRangeFilter, PaginationParams, TimeSeriesData } from "../../types";
 /**
  * Configuration for tracking a product view.
@@ -124,7 +124,7 @@ export interface ProductAnalyticsData {
 /**
  * Products - Track product interactions.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides product tracking capabilities including:
@@ -158,7 +158,7 @@ export interface ProductAnalyticsData {
  * });
  * ```
  */
-export declare class Products extends FTRPC {
+export declare class Products extends FlowGridTransport {
     /**
      * Tracks a product page view.
      *

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

@@ -45,7 +45,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { Promotion, MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Configuration for tracking promotion view.
@@ -140,7 +140,7 @@ export interface PromotionAnalyticsData {
 /**
  * Promotions - Track promotions and coupons.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides promotion tracking capabilities including:
@@ -170,7 +170,7 @@ export interface PromotionAnalyticsData {
  * });
  * ```
  */
-export declare class Promotions extends FTRPC {
+export declare class Promotions extends FlowGridTransport {
     /**
      * Tracks promotion view/impression.
      *

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

@@ -41,7 +41,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { Order, ShippingInfo, MoneyValue, DateRangeFilter, TimeSeriesData, PaginationParams } from "../../types";
 /**
  * Configuration for tracking a purchase.
@@ -148,7 +148,7 @@ export interface RecentOrdersData {
 /**
  * Purchases - Track completed purchases and revenue.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides purchase tracking capabilities including:
@@ -183,7 +183,7 @@ export interface RecentOrdersData {
  * const revenue = await purchases.getRevenue({ range: 'thisMonth' });
  * ```
  */
-export declare class Purchases extends FTRPC {
+export declare class Purchases extends FlowGridTransport {
     /**
      * Tracks a completed purchase.
      *

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

@@ -41,7 +41,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { Refund, CartItem, MoneyValue, DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Configuration for tracking a refund.
@@ -109,7 +109,7 @@ export interface RefundAnalyticsData {
 /**
  * Refunds - Track refunds and returns.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides refund tracking capabilities including:
@@ -145,7 +145,7 @@ export interface RefundAnalyticsData {
  * });
  * ```
  */
-export declare class Refunds extends FTRPC {
+export declare class Refunds extends FlowGridTransport {
     /**
      * Tracks a refund event.
      *

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

@@ -38,7 +38,7 @@
  * });
  * ```
  */
-import { FTRPC } from "../../client/ftrpc";
+import { FlowGridTransport } from "../../client/transport";
 import { Product, DateRangeFilter, TimeSeriesData } from "../../types";
 /**
  * Search query configuration.
@@ -135,7 +135,7 @@ export interface SearchAnalyticsData {
 /**
  * SearchAnalytics - Track site search behavior.
  *
- * @extends FTRPC
+ * @extends FlowGridTransport
  *
  * @description
  * Provides search analytics including:
@@ -165,7 +165,7 @@ export interface SearchAnalyticsData {
  * });
  * ```
  */
-export declare class SearchAnalytics extends FTRPC {
+export declare class SearchAnalytics extends FlowGridTransport {
     /**
      * Tracks a search query.
      *