flowgrid-sdk 1.1.0 → 1.2.1

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

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview FlowGrid Identity Manager.
+ * @module utils/identity
+ *
+ * @description
+ * Owns the visitor/session identity lifecycle.
+ * Writes its own cookies/storage so the SDK can self-bootstrap
+ * without depending on an external tracking script (track.js).
+ *
+ * Backward-compatible: checks for existing track.js `visitor_id`
+ * before falling back to its own `fg_visitor_id` key.
+ */
+export interface IdentityConfig {
+    /** Explicit visitor ID (overrides auto-resolution) */
+    visitorId?: string;
+    /** Cookie domain (defaults to current hostname) */
+    cookieDomain?: string;
+    /** Visitor cookie max-age in days (default: 365) */
+    visitorMaxAgeDays?: number;
+    /** Session timeout in minutes (default: 30) */
+    sessionTimeoutMinutes?: number;
+    /** Storage strategy */
+    storage?: 'cookie' | 'localStorage' | 'memory';
+    /** Server-side cookie reader (e.g. Next.js `cookies()`) */
+    serverCookies?: ServerCookieReader;
+    /** Write to `visitor_id` (track.js compat) instead of `fg_visitor_id` (default true) */
+    compat?: boolean;
+}
+/**
+ * Minimal interface for reading cookies server-side.
+ * Compatible with Next.js `cookies()` and Nuxt `useCookie()`.
+ */
+export interface ServerCookieReader {
+    get(name: string): {
+        value: string;
+    } | string | undefined | null;
+}
+export declare class IdentityManager {
+    private visitorId;
+    private sessionId;
+    private config;
+    /** In-memory store for SSR / Node environments */
+    private memoryStore;
+    constructor(config?: IdentityConfig);
+    /**
+     * Get or create a persistent visitor ID.
+     *
+     * Resolution order:
+     *  1. Explicit config.visitorId
+     *  2. track.js `visitor_id` cookie/localStorage (backward compat)
+     *  3. `fg_visitor_id` cookie
+     *  4. `fg_visitor_id` localStorage
+     *  5. Server cookie reader (if provided)
+     *  6. Generate new UUID v4, persist to cookie + localStorage
+     */
+    getVisitorId(): string;
+    /**
+     * Get or create a session ID.
+     *
+     * - Reads from sessionStorage `fg_session_id`
+     * - If absent or expired (>sessionTimeoutMinutes since last activity), creates new
+     * - Persists to sessionStorage
+     * - Touches timestamp on every call
+     */
+    getSessionId(): string;
+    /**
+     * Update the visitor ID (e.g. after identify() links anonymous → known user).
+     * Persists to cookie + localStorage.
+     */
+    setVisitorId(id: string): void;
+    /** Clear session (e.g. on logout). */
+    clearSession(): void;
+    /** Clear all identity (GDPR). Removes visitor + session + experiment assignments. */
+    clearAll(): void;
+    /** Check if running in a browser environment. */
+    isBrowser(): boolean;
+    /** Returns the primary cookie name based on compat mode */
+    private get visitorCookieName();
+    private resolveVisitorId;
+    private readLocalStorage;
+    private removeLegacyCookie;
+    private persistVisitorId;
+    private getMemorySessionId;
+    private readCookie;
+    private readServerCookie;
+    private writeCookie;
+    private deleteCookie;
+    private generateVisitorId;
+    private generateSessionId;
+    private uuidV4;
+    private randomHex;
+    private detectBrowser;
+}

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.1",
   "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 {};