flowgrid-sdk 1.1.0 → 1.2.0

package/dist/lib/utils/storage.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview FlowGrid storage utilities.
+ * @module utils/storage
+ *
+ * @description
+ * Reads visitor identity and UTM attribution data from the same
+ * cookie / localStorage / sessionStorage keys used by the FlowGrid
+ * tracking scripts (track.js & flowgrid_oss_client_sdk.js).
+ *
+ * These functions are **read-only** — the tracking scripts remain the
+ * single writer. The SDK only consumes these values.
+ */
+/**
+ * Read a cookie value by name.
+ * Returns `null` when the cookie is absent or document.cookie is unavailable.
+ */
+export declare function getCookie(name: string): string | null;
+/**
+ * Resolve the visitor ID written by track.js / flowgrid_oss_client_sdk.js.
+ *
+ * Storage locations (checked in order):
+ *   1. cookie  `visitor_id`
+ *   2. localStorage `visitor_id`
+ *
+ * Returns `null` when neither source contains a value (e.g. tracking
+ * script hasn't run yet, or running server-side).
+ */
+export declare function getVisitorId(): string | null;
+/**
+ * Resolve the session ID written by track.js.
+ *
+ * Storage: `sessionStorage("session_id")`
+ */
+export declare function getSessionId(): string | null;
+/**
+ * Resolve the web_id written by track.js.
+ *
+ * Storage: `localStorage("web_id")`
+ */
+export declare function getWebId(): string | null;
+export interface FlowGridUTM {
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    utmTerm?: string;
+    utmContent?: string;
+    ref?: string;
+    source?: string;
+    via?: string;
+}
+/**
+ * Read UTM & attribution parameters persisted by
+ * flowgrid_oss_client_sdk.js as `__flowgrid_*` cookies.
+ */
+export declare function getUTM(): FlowGridUTM;
+export interface FlowGridUTMHistoryEntry {
+    timestamp: string;
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_content?: string;
+    utm_term?: string;
+}
+/**
+ * Read the full UTM history array persisted by flowgrid_oss_client_sdk.js.
+ *
+ * Checks localStorage first, then the `utm_history` cookie.
+ */
+export declare function getUTMHistory(): FlowGridUTMHistoryEntry[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowgrid-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A TypeScript SDK for tracking user events, feature usage, experiments, and feature flags with Flowgrid.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -65,6 +65,11 @@
       "types": "./dist/lib/types/index.d.ts",
       "import": "./dist/lib/types/index.mjs",
       "require": "./dist/lib/types/index.js"
+    },
+    "./consent": {
+      "types": "./dist/lib/consent/index.d.ts",
+      "import": "./dist/lib/consent/index.mjs",
+      "require": "./dist/lib/consent/index.js"
     }
   },
   "scripts": {
@@ -72,7 +77,12 @@
     "build:browser": "webpack --config webpack.browser.config.js",
     "build:all": "npm run build && npm run build:browser",
     "build:types": "tsc --emitDeclarationOnly",
-    "test": "echo \"No tests specified\" && exit 0",
+    "test": "npx tsx tests/featureFlags.test.ts && npx tsx tests/core.test.ts && npx tsx tests/analytics.test.ts && npx tsx tests/ecommerce.test.ts && npx tsx tests/enterprise.test.ts",
+    "test:featureFlags": "npx tsx tests/featureFlags.test.ts",
+    "test:core": "npx tsx tests/core.test.ts",
+    "test:analytics": "npx tsx tests/analytics.test.ts",
+    "test:ecommerce": "npx tsx tests/ecommerce.test.ts",
+    "test:enterprise": "npx tsx tests/enterprise.test.ts",
     "lint": "echo \"No linting configured\" && exit 0",
     "prepublishOnly": "npm run build:all"
   },
@@ -128,6 +138,7 @@
     "@types/react": "^18.0.0",
     "react": "^18.3.1",
     "ts-loader": "^9.5.1",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.2",
     "vue": "^3.5.27",
     "webpack": "^5.105.0",

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

@@ -1,51 +0,0 @@
-/**
- * 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

@@ -1,132 +0,0 @@
-/**
- * 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' });
- * ```
- */
-/**
- * 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 {
-    /**
-     * Unique Web ID identifying the site or application.
-     * Used by the backend to associate incoming events.
-     */
-    protected webId: string;
-    /**
-     * Base API endpoint.
-     * Example values:
-     * - "api.flowgrid.com"
-     * - "https://api.flowgrid.com"
-     *
-     * Protocol is normalized automatically.
-     */
-    protected endpoint: string;
-    /**
-     * 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);
-    /**
-     * Core RPC transport method.
-     *
-     * @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.
-     */
-    private executeRequest;
-    /**
-     * 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/client/modules.d.ts

@@ -1,104 +0,0 @@
-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/core/feature-flag.d.ts

@@ -1,249 +0,0 @@
-/**
- * @fileoverview Core - Feature Flags
- * @module features/core/feature-flag
- *
- * @description
- * Track feature flag evaluations and usage to understand
- * rollout progress and flag performance.
- *
- * @useCases
- * - Track flag evaluations
- * - Monitor rollout progress
- * - Analyze flag impact
- * - Debug flag configurations
- * - Measure gradual rollouts
- *
- * @metrics
- * - Evaluations per flag
- * - Unique users per variant
- * - Rollout percentage
- * - Error rate
- * - Flag age
- *
- * @chartData
- * - Pie chart: Users by variant
- * - Line chart: Evaluations over time
- * - Table: Active flags summary
- * - Bar chart: Top evaluated flags
- *
- * @example
- * ```typescript
- * const featureFlag = new FeatureFlag(webId, endpoint, apiKey);
- *
- * await featureFlag.evaluate({
- *   eventName: 'new_dashboard',
- *   properties: { userId: 'user_123', result: true }
- * });
- * ```
- */
-import { FTRPC } from "../../client/ftrpc";
-import { TimeSeriesData } from "../../types";
-/**
- * Base feature flag configuration.
- */
-export interface FlagConfig {
-    /** Flag name/event */
-    eventName: string;
-    /** Evaluation properties */
-    properties: Record<string, unknown>;
-}
-/**
- * Feature flag definition.
- */
-export interface FlagDefinition {
-    /** Flag key */
-    flagKey: string;
-    /** Flag name */
-    name: string;
-    /** Description */
-    description?: string;
-    /** Flag type */
-    type: 'boolean' | 'string' | 'number' | 'json';
-    /** Default value */
-    defaultValue: boolean | string | number | Record<string, unknown>;
-    /** Variants (for multivariate flags) */
-    variants?: Array<{
-        key: string;
-        value: boolean | string | number | Record<string, unknown>;
-        weight?: number;
-    }>;
-    /** Targeting rules */
-    targeting?: {
-        rules: Array<{
-            attribute: string;
-            operator: 'equals' | 'contains' | 'in' | 'gt' | 'lt';
-            value: unknown;
-            variant: string;
-        }>;
-    };
-    /** Rollout percentage (0-100) */
-    rolloutPercentage?: number;
-}
-/**
- * Flag evaluation configuration.
- */
-export interface FlagEvaluationConfig {
-    /** Flag key */
-    flagKey: string;
-    /** User ID */
-    userId?: string;
-    /** Evaluation context */
-    context?: Record<string, unknown>;
-    /** Evaluated variant/value */
-    result: boolean | string | number | Record<string, unknown>;
-    /** Reason for evaluation result */
-    reason?: 'default' | 'targeting' | 'rollout' | 'override' | 'error';
-    /** Evaluation duration (ms) */
-    duration?: number;
-}
-/**
- * Feature flag response.
- */
-export interface FlagResponse {
-    eventName: string;
-    properties: Record<string, unknown>;
-    response: {
-        tracked: boolean;
-        flagKey?: string;
-    };
-    timestamp: string;
-}
-/**
- * Single flag analytics.
- */
-export interface FlagAnalyticsData {
-    /** Flag info */
-    flag: {
-        flagKey: string;
-        name: string;
-        type: string;
-        status: 'active' | 'inactive' | 'archived';
-        createdAt: string;
-        lastModified: string;
-    };
-    /** Evaluation stats */
-    evaluations: {
-        total: number;
-        uniqueUsers: number;
-        avgDuration: number;
-        errorRate: number;
-    };
-    /** Results by variant */
-    byVariant: Array<{
-        variant: string;
-        evaluations: number;
-        uniqueUsers: number;
-        percentage: number;
-    }>;
-    /** Results by reason */
-    byReason: Record<string, number>;
-    /** Trends */
-    trends: TimeSeriesData;
-}
-/**
- * All flags analytics.
- */
-export interface AllFlagsAnalyticsData {
-    /** Summary */
-    summary: {
-        totalFlags: number;
-        activeFlags: number;
-        totalEvaluations: number;
-        uniqueUsers: number;
-        avgEvaluationsPerUser: number;
-    };
-    /** Top flags by evaluations */
-    topFlags: Array<{
-        flagKey: string;
-        name: string;
-        evaluations: number;
-        uniqueUsers: number;
-        rolloutPercentage: number;
-    }>;
-    /** Stale flags (not evaluated recently) */
-    staleFlags: Array<{
-        flagKey: string;
-        name: string;
-        lastEvaluated: string;
-        daysSinceEvaluation: number;
-    }>;
-    /** Flags by status */
-    byStatus: {
-        active: number;
-        inactive: number;
-        archived: number;
-    };
-}
-/**
- * FeatureFlag - Track feature flag evaluations.
- *
- * @extends FTRPC
- *
- * @description
- * Provides feature flag tracking including:
- * - Flag evaluations
- * - Rollout monitoring
- * - Flag definitions
- * - Usage analytics
- * - Stale flag detection
- *
- * @example
- * ```typescript
- * const featureFlag = new FeatureFlag(webId, endpoint, apiKey);
- *
- * // Track evaluation
- * await featureFlag.trackEvaluation({
- *   flagKey: 'new_checkout',
- *   userId: 'user_123',
- *   result: true,
- *   reason: 'rollout'
- * });
- *
- * // Get flag analytics
- * const analytics = await featureFlag.getFlagAnalytics('new_checkout');
- * console.log(`${analytics.evaluations.total} evaluations`);
- * ```
- */
-export declare class FeatureFlag extends FTRPC {
-    /**
-     * Evaluates and tracks a feature flag.
-     *
-     * @param config - Flag configuration
-     * @returns Promise resolving to flag response
-     */
-    evaluate(config: FlagConfig): Promise<FlagResponse>;
-    /**
-     * Tracks a flag evaluation with details.
-     *
-     * @param config - Flag evaluation configuration
-     * @returns Promise resolving to flag response
-     */
-    trackEvaluation(config: FlagEvaluationConfig): Promise<FlagResponse>;
-    /**
-     * Defines/updates a feature flag.
-     *
-     * @param definition - Flag definition
-     * @returns Promise resolving to flag response
-     */
-    define(definition: FlagDefinition): Promise<FlagResponse>;
-    /**
-     * Tracks flag status change (enable/disable).
-     *
-     * @param flagKey - Flag key
-     * @param enabled - Whether flag is enabled
-     * @param changedBy - User who made the change
-     * @returns Promise resolving to flag response
-     */
-    trackStatusChange(flagKey: string, enabled: boolean, changedBy?: string): Promise<FlagResponse>;
-    /**
-     * Tracks rollout percentage change.
-     *
-     * @param flagKey - Flag key
-     * @param previousPercentage - Previous rollout %
-     * @param newPercentage - New rollout %
-     * @param changedBy - User who made the change
-     * @returns Promise resolving to flag response
-     */
-    trackRolloutChange(flagKey: string, previousPercentage: number, newPercentage: number, changedBy?: string): Promise<FlagResponse>;
-}
-export default FeatureFlag;

package/dist/lib/utils/functions.d.ts

@@ -1 +0,0 @@
-export declare function _0x7777(): string;