flowgrid-sdk 1.6.7 → 1.6.8

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

@@ -43,6 +43,7 @@
  * ```
  */
 import { FlowGridTransport } from "../../client/transport";
+import { type Teardown } from "../../utils/browser";
 import { UserTraits, MoneyValue, TimeSeriesData } from "../../types";
 /**
  * Configuration for identifying a user.
@@ -55,6 +56,15 @@ export interface IdentifyConfig {
     /** User traits/properties */
     traits?: UserTraits;
 }
+/**
+ * Options for {@link Identify.autoTrackForms} passive identity capture.
+ */
+export interface PassiveIdentityOptions {
+    /** Debounce for `input` events before reading a field (ms, default 800). */
+    debounceMs?: number;
+    /** Extra `path` regex on which NO inputs are captured (replaces the default). */
+    excludePath?: RegExp;
+}
 /**
  * Configuration for aliasing user IDs.
  */
@@ -249,5 +259,22 @@ export declare class Identify extends FlowGridTransport {
      * @returns Promise resolving to reset response
      */
     reset(userId: string): Promise<IdentifyResponse>;
+    /**
+     * Passive identity capture — the browser-side form-field tracker (parity with
+     * `flowgrid.js`'s `setupPassiveIdentityCapture`). Watches inputs (initial scan
+     * + a MutationObserver for fields added by modals/SPAs), classifies each by
+     * name/id/placeholder/autocomplete, hashes PII (SHA-256) before it leaves the
+     * browser, and posts the captured identity to the flowgrid-core identity store
+     * (`POST /api/v1/identity/identify`) so the dashboard can map the anonymous
+     * `visitor_id` to a person — and, with a CRM connected, to a known customer.
+     *
+     * Privacy: requires `analytics` consent; never attaches to password/card/cvv/
+     * ssn/pin fields or anything marked `data-analytics="ignore"` / `.no-track`;
+     * skips sensitive paths (checkout/account-settings/admin). Off by default in
+     * {@link FlowGrid.autoTrack} — enable with `autoTrack({ passiveIdentity: true })`.
+     *
+     * @returns a teardown that detaches every listener (no-op on the server).
+     */
+    autoTrackForms(options?: PassiveIdentityOptions): Teardown;
 }
 export default Identify;

package/dist/lib/features/analytics/identify.js

@@ -46,6 +46,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Identify = void 0;
 const transport_1 = require("../../client/transport");
+const browser_1 = require("../../utils/browser");
 // ============================================================================
 // IDENTIFY CLASS
 // ============================================================================
@@ -211,6 +212,198 @@ class Identify extends transport_1.FlowGridTransport {
             timestamp: new Date().toISOString()
         });
     }
+    /**
+     * Passive identity capture — the browser-side form-field tracker (parity with
+     * `flowgrid.js`'s `setupPassiveIdentityCapture`). Watches inputs (initial scan
+     * + a MutationObserver for fields added by modals/SPAs), classifies each by
+     * name/id/placeholder/autocomplete, hashes PII (SHA-256) before it leaves the
+     * browser, and posts the captured identity to the flowgrid-core identity store
+     * (`POST /api/v1/identity/identify`) so the dashboard can map the anonymous
+     * `visitor_id` to a person — and, with a CRM connected, to a known customer.
+     *
+     * Privacy: requires `analytics` consent; never attaches to password/card/cvv/
+     * ssn/pin fields or anything marked `data-analytics="ignore"` / `.no-track`;
+     * skips sensitive paths (checkout/account-settings/admin). Off by default in
+     * {@link FlowGrid.autoTrack} — enable with `autoTrack({ passiveIdentity: true })`.
+     *
+     * @returns a teardown that detaches every listener (no-op on the server).
+     */
+    autoTrackForms(options = {}) {
+        if (!(0, browser_1.isBrowser)())
+            return () => { };
+        if (!transport_1.FlowGridTransport.hasConsent("analytics"))
+            return () => { };
+        const win = (0, browser_1.getWindow)();
+        const doc = (0, browser_1.getDocument)();
+        const debounceMs = options.debounceMs ?? 800;
+        const EXCLUDED_PATH_RE = options.excludePath ?? /\/(checkout|account\/settings|admin)(\/|$)/i;
+        const BLOCKED_RE = /(password|cardnumber|creditcard|\bcard\b|cvv|cvc|ssn|\bpin\b|securitycode)/i;
+        const SKIP_RE = /(message|comment|note|feedback|search|query)/i;
+        const FIELD_MAP = [
+            { re: /(email|emailaddress)/, trait: "email", pii: true, identify: true },
+            { re: /(phone|tel|mobile|cell)/, trait: "phone", pii: true, identify: false },
+            { re: /(firstname|fname|givenname)/, trait: "firstName", pii: false, identify: false },
+            { re: /(lastname|lname|surname|familyname)/, trait: "lastName", pii: false, identify: false },
+            { re: /(company|organi[sz]ation|businessname)/, trait: "company", pii: false, identify: false },
+            { re: /(streetaddress|addressline|^address$|^street$)/, trait: "address", pii: false, identify: false },
+            { re: /(^city$|town)/, trait: "city", pii: false, identify: false },
+            { re: /(postcode|postalcode|zipcode|^zip$)/, trait: "postcode", pii: false, identify: false },
+            // A single full-name / username field maps to firstName; listed last so
+            // dedicated first/last-name fields win when both exist.
+            { re: /(fullname|^name$|username|yourname|contactname|displayname)/, trait: "firstName", pii: false, identify: false },
+        ];
+        const captured = {};
+        const seen = new WeakSet();
+        const debounceTimers = new WeakMap();
+        const teardowns = [];
+        const fieldEl = (el) => el;
+        const normalize = (el) => [fieldEl(el).name, el.id, el.getAttribute("placeholder"), el.getAttribute("autocomplete")]
+            .filter(Boolean).join(" ").toLowerCase().replace(/[\s_-]/g, "");
+        const isBlocked = (el, key) => {
+            const input = fieldEl(el);
+            if (input.type === "password" || input.type === "hidden")
+                return true;
+            if (el.getAttribute("data-analytics") === "ignore")
+                return true;
+            if (el.classList && el.classList.contains("no-track"))
+                return true;
+            return BLOCKED_RE.test(key);
+        };
+        const classify = (el) => {
+            const key = normalize(el);
+            if (!key)
+                return null;
+            if (isBlocked(el, key))
+                return { blocked: true };
+            if (SKIP_RE.test(key))
+                return null;
+            return FIELD_MAP.find((f) => f.re.test(key)) ?? null;
+        };
+        const sha256hex = async (value) => {
+            try {
+                const enc = new TextEncoder().encode(String(value).trim().toLowerCase());
+                const buf = await win.crypto.subtle.digest("SHA-256", enc);
+                return Array.from(new Uint8Array(buf)).map((b) => b.toString(16).padStart(2, "0")).join("");
+            }
+            catch {
+                return null;
+            }
+        };
+        const resolveVisitorId = () => (this.identityManager ? this.identityManager.getVisitorId() : this.visitorId) || "";
+        const resolveSessionId = () => this.identityManager ? this.identityManager.getSessionId() : null;
+        // Posts the captured identity to the flowgrid-core identity store. Raw email
+        // stays server-side (CRM enrichment + dashboard display); the analytics
+        // event store only ever sees hashes (the `field_captured` mirror below).
+        const sendIdentity = () => {
+            const visitorId = resolveVisitorId();
+            if (!this.webId || !visitorId)
+                return;
+            if (!captured.email && !captured.emailHash && !captured.firstName && !captured.lastName)
+                return;
+            const traits = {
+                email: captured.email ?? null,
+                email_hash: captured.emailHash ?? null,
+                phone_hash: captured.phoneHash ?? null,
+                first_name: captured.firstName ?? null,
+                last_name: captured.lastName ?? null,
+                company: captured.company ?? null,
+                address: captured.address ?? null,
+                city: captured.city ?? null,
+                postcode: captured.postcode ?? null,
+            };
+            const url = `${this.endpoint}/api/v1/identity/identify`;
+            const payload = JSON.stringify({
+                web_id: this.webId,
+                visitor_id: visitorId,
+                session_id: resolveSessionId(),
+                path_name: win.location.pathname,
+                traits,
+            });
+            try {
+                if (typeof navigator !== "undefined" && navigator.sendBeacon &&
+                    navigator.sendBeacon(url, new Blob([payload], { type: "application/json" }))) {
+                    // sent via beacon
+                }
+                else {
+                    void fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: payload, keepalive: true }).catch(() => { });
+                }
+            }
+            catch { /* swallow */ }
+        };
+        const captureField = (el) => {
+            const cls = classify(el);
+            if (!cls || "blocked" in cls)
+                return;
+            const value = (fieldEl(el).value || "").trim();
+            if (!value)
+                return;
+            if (cls.pii) {
+                const toHash = cls.trait === "phone" ? value.replace(/[^\d+]/g, "") : value;
+                void sha256hex(toHash).then((hash) => {
+                    if (cls.trait === "email") {
+                        captured.email = value;
+                        if (hash)
+                            captured.emailHash = hash;
+                    }
+                    else if (cls.trait === "phone" && hash) {
+                        captured.phoneHash = hash;
+                    }
+                    if (cls.identify || captured.email)
+                        sendIdentity();
+                });
+            }
+            else {
+                captured[cls.trait] = value;
+                if (captured.email)
+                    sendIdentity();
+            }
+        };
+        const attach = (el) => {
+            if (seen.has(el))
+                return;
+            const cls = classify(el);
+            if (!cls || "blocked" in cls)
+                return; // never listen to blocked / unknown fields
+            seen.add(el);
+            const onBlur = () => captureField(el);
+            const onInput = () => {
+                clearTimeout(debounceTimers.get(el));
+                debounceTimers.set(el, setTimeout(() => captureField(el), debounceMs));
+            };
+            el.addEventListener("blur", onBlur, { passive: true });
+            el.addEventListener("input", onInput, { passive: true });
+            teardowns.push(() => {
+                el.removeEventListener("blur", onBlur);
+                el.removeEventListener("input", onInput);
+            });
+        };
+        const scanPage = () => {
+            if (EXCLUDED_PATH_RE.test(win.location.pathname))
+                return;
+            doc.querySelectorAll("input, textarea, select").forEach(attach);
+        };
+        scanPage();
+        let mo = null;
+        try {
+            mo = new MutationObserver(() => scanPage());
+            if (doc.body)
+                mo.observe(doc.body, { childList: true, subtree: true });
+        }
+        catch { /* MutationObserver unavailable */ }
+        return () => {
+            if (mo)
+                try {
+                    mo.disconnect();
+                }
+                catch { /* noop */ }
+            for (const t of teardowns) {
+                try {
+                    t();
+                }
+                catch { /* noop */ }
+            }
+        };
+    }
 }
 exports.Identify = Identify;
 exports.default = Identify;

package/dist/lib/features/analytics/identify.js.map

@@ -1 +1 @@
-{"version":3,"file":"identify.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/identify.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;;;AAEH,sDAA2D;AAkG3D,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAa,QAAS,SAAQ,6BAAiB;IAC7C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,KAAK,CAAC,IAAI,CAAC,MAAsB;QAC/B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACtC,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,YAAY,CAAC,MAAc,EAAE,MAAkB;QACnD,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE;YACtC,IAAI,EAAE,eAAe;YACrB,MAAM;YACN,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,KAAK,CAAC,MAAmB;QAC7B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE;YACnC,IAAI,EAAE,OAAO;YACb,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,KAAK,CAAC,MAAmB;QAC7B,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE;YACnC,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,MAAc;QACxB,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE;YACvC,IAAI,EAAE,OAAO;YACb,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CAEF;AAlID,4BAkIC;AAED,kBAAe,QAAQ,CAAC"}
+{"version":3,"file":"identify.js","sourceRoot":"","sources":["../../../../src/lib/features/analytics/identify.ts"],"names":[],"mappings":"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"}

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

@@ -16,7 +16,7 @@ export type { ReplayPrivacyMetadata, SessionReplayDropMetadata, SessionReplayErr
 export type { PageViewConfig, ScrollDepthConfig, TimeOnPageConfig, PageViewResponse, PageAnalyticsData } from './page-views';
 export type { SessionStartConfig, SessionResponse, SessionEndResponse, SessionAnalyticsData, RealTimeSessionData } from './sessions';
 export type { EventTrackConfig, BatchEventConfig, EventResponse, BatchEventResponse, EventAnalyticsData } from './events';
-export type { IdentifyConfig, AliasConfig, GroupConfig, IdentifyResponse, UserAnalyticsData } from './identify';
+export type { IdentifyConfig, AliasConfig, GroupConfig, IdentifyResponse, UserAnalyticsData, PassiveIdentityOptions } from './identify';
 export type { FunnelDefinition, FunnelStepConfig, FunnelStepResponse, FunnelAnalyticsData, FunnelComparisonData } from './funnels';
 export type { ActivityConfig, CohortAnalysisConfig, ActivityResponse, CohortAnalysisData, StickinessData, ChurnAnalysisData } from './retention';
 export type { AttributionModel, TouchpointConfig, ConversionEvent, TouchpointResponse, AttributionReportData } from './attribution';

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

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

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

@@ -39,6 +39,25 @@
  */
 import { FlowGridTransport } from "../../client/transport";
 import { TimeSeriesData } from "../../types";
+/** Lifecycle stage the dashboard's adoption funnel reads (event_subtype). */
+export type FeatureStage = "discovery" | "viewed" | "adoption" | "completed" | "abandonment";
+/** Options for the intelligent one-liner {@link TrackFeature.feature}. */
+export interface SmartFeatureOptions {
+    /** Human label; defaults to a humanised `featureId`. */
+    name?: string;
+    /** Feature category (e.g. "Automation"). */
+    category?: string;
+    /** Mark this interaction as a successful completion of the feature's job. */
+    completed?: boolean;
+    /** Mark this interaction as abandoned (started but gave up). */
+    abandoned?: boolean;
+    /** Distinct days of use before a visitor counts as "adopted" (default 2). */
+    adoptionDays?: number;
+    /** Total uses before a visitor counts as "adopted" (default 5). */
+    adoptionUses?: number;
+    /** Extra properties to attach. */
+    properties?: Record<string, unknown>;
+}
 type FeatureConfigProperties = {
     featureId?: string;
     featureName: string;
@@ -199,4 +218,16 @@ export declare class TrackFeature extends FlowGridTransport {
      */
     trackUsage(config: FeatureUsageConfig): Promise<FeatureResponse>;
 }
+/** Humanises a feature id → display name ("ai-agent-builder" → "Ai Agent Builder"). */
+export declare function humaniseFeatureId(id: string): string;
+/**
+ * Derives the lifecycle stage(s) a single `feature()` call should emit, from
+ * per-visitor local state. Pure of any transport — the caller emits each stage
+ * via `FlowGrid.track("feature_usage", …)`. Persists the updated state.
+ *
+ *  - first-ever use      → ["discovery", "viewed"]
+ *  - subsequent use      → ["viewed"] (+ "adoption" once past the threshold)
+ *  - `{ completed }`     → ["completed"]   `{ abandoned }` → ["abandonment"]
+ */
+export declare function deriveFeatureStages(stateKey: string, opts?: SmartFeatureOptions): FeatureStage[];
 export default TrackFeature;

package/dist/lib/features/core/track-feature.js

@@ -40,7 +40,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TrackFeature = void 0;
+exports.humaniseFeatureId = humaniseFeatureId;
+exports.deriveFeatureStages = deriveFeatureStages;
 const transport_1 = require("../../client/transport");
+const browser_1 = require("../../utils/browser");
 // ============================================================================
 // TRACK FEATURE CLASS
 // ============================================================================
@@ -119,5 +122,69 @@ class TrackFeature extends transport_1.FlowGridTransport {
     }
 }
 exports.TrackFeature = TrackFeature;
+/** Humanises a feature id → display name ("ai-agent-builder" → "Ai Agent Builder"). */
+function humaniseFeatureId(id) {
+    return id
+        .replace(/[-_]+/g, " ")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/\s+/g, " ")
+        .trim()
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+function readSmartState(key) {
+    if (!(0, browser_1.isBrowser)())
+        return null;
+    try {
+        const raw = (0, browser_1.getWindow)().localStorage.getItem(key);
+        if (!raw)
+            return null;
+        const v = JSON.parse(raw);
+        return { uses: Number(v.uses) || 0, days: Array.isArray(v.days) ? v.days : [], adopted: Boolean(v.adopted) };
+    }
+    catch {
+        return null;
+    }
+}
+function writeSmartState(key, state) {
+    if (!(0, browser_1.isBrowser)())
+        return;
+    try {
+        (0, browser_1.getWindow)().localStorage.setItem(key, JSON.stringify(state));
+    }
+    catch {
+        /* storage unavailable — capture still works, just not stage derivation */
+    }
+}
+/**
+ * Derives the lifecycle stage(s) a single `feature()` call should emit, from
+ * per-visitor local state. Pure of any transport — the caller emits each stage
+ * via `FlowGrid.track("feature_usage", …)`. Persists the updated state.
+ *
+ *  - first-ever use      → ["discovery", "viewed"]
+ *  - subsequent use      → ["viewed"] (+ "adoption" once past the threshold)
+ *  - `{ completed }`     → ["completed"]   `{ abandoned }` → ["abandonment"]
+ */
+function deriveFeatureStages(stateKey, opts = {}) {
+    if (opts.completed)
+        return ["completed"];
+    if (opts.abandoned)
+        return ["abandonment"];
+    const today = new Date().toISOString().slice(0, 10);
+    const state = readSmartState(stateKey);
+    if (!state) {
+        writeSmartState(stateKey, { uses: 1, days: [today], adopted: false });
+        return ["discovery", "viewed"];
+    }
+    const stages = ["viewed"];
+    const days = state.days.includes(today) ? state.days : [...state.days, today];
+    const uses = state.uses + 1;
+    let adopted = state.adopted;
+    if (!adopted && (days.length >= (opts.adoptionDays ?? 2) || uses >= (opts.adoptionUses ?? 5))) {
+        stages.push("adoption");
+        adopted = true;
+    }
+    writeSmartState(stateKey, { uses, days, adopted });
+    return stages;
+}
 exports.default = TrackFeature;
 //# sourceMappingURL=track-feature.js.map

package/dist/lib/features/core/track-feature.js.map

@@ -1 +1 @@
-{"version":3,"file":"track-feature.js","sourceRoot":"","sources":["../../../../src/lib/features/core/track-feature.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAEH,sDAA2D;AAgI3D,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,MAAa,YAAa,SAAQ,6BAAiB;IACjD;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,MAAqB;QAChC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,iBAAiB,EAAE;YACxC,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,eAAe;YACxB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,GAAG,MAAM,CAAC,UAAU;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,MAA0B;QACzC,OAAO,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,eAAe,EAAE;YAC1D,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,MAAM,CAAC,MAAM;YACtB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,GAAG,MAAM,CAAC,UAAU;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC,CAAC;IACL,CAAC;CACF;AAxCD,oCAwCC;AAED,kBAAe,YAAY,CAAC"}
+{"version":3,"file":"track-feature.js","sourceRoot":"","sources":["../../../../src/lib/features/core/track-feature.ts"],"names":[],"mappings":"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"}

package/dist/lib/flowgrid.d.ts

@@ -946,6 +946,22 @@ export declare class FlowGrid {
      * ```
      */
     identifyUser(userId: string, traits?: Record<string, unknown>, anonymousId?: string): Promise<import("..").IdentifyResponse>;
+    /**
+     * Intelligent feature-usage one-liner. Call it wherever a feature is used —
+     * the SDK derives the discovered → viewed → adopted lifecycle per visitor
+     * (no need to hand-emit each stage). Pass `{ completed }` / `{ abandoned }`
+     * for terminal stages.
+     *
+     * Emission goes through the unified `.track()` router (`feature_usage`), so it
+     * shares the same routing/consent/transport as every other event.
+     *
+     * @example
+     * ```ts
+     * fg.feature("ai-agent-builder");                       // used (auto stage)
+     * fg.feature("ai-agent-builder", { completed: true });  // finished the job
+     * ```
+     */
+    feature(featureId: string, opts?: import("./features/core/track-feature").SmartFeatureOptions): void;
     /**
      * Track a page view. Auto-detects URL/path/title/referrer in the browser.
      *
@@ -998,6 +1014,7 @@ export declare class FlowGrid {
             idleAfterMs?: number;
             pollMs?: number;
         };
+        passiveIdentity?: boolean | import("./features/analytics/identify").PassiveIdentityOptions;
     }): () => void;
 }
 export default FlowGrid;

package/dist/lib/flowgrid.js

@@ -68,6 +68,7 @@ exports.FlowGrid = void 0;
 const transport_1 = require("./client/transport");
 const identity_1 = require("./utils/identity");
 const core_1 = require("./features/core");
+const track_feature_1 = require("./features/core/track-feature");
 const analytics_1 = require("./features/analytics");
 const ecommerce_1 = require("./features/ecommerce");
 // Import directly from sub-barrels (not the top-level ./tracking barrel) so
@@ -955,6 +956,31 @@ class FlowGrid {
     identifyUser(userId, traits, anonymousId) {
         return this.identify.user(userId, traits, anonymousId);
     }
+    /**
+     * Intelligent feature-usage one-liner. Call it wherever a feature is used —
+     * the SDK derives the discovered → viewed → adopted lifecycle per visitor
+     * (no need to hand-emit each stage). Pass `{ completed }` / `{ abandoned }`
+     * for terminal stages.
+     *
+     * Emission goes through the unified `.track()` router (`feature_usage`), so it
+     * shares the same routing/consent/transport as every other event.
+     *
+     * @example
+     * ```ts
+     * fg.feature("ai-agent-builder");                       // used (auto stage)
+     * fg.feature("ai-agent-builder", { completed: true });  // finished the job
+     * ```
+     */
+    feature(featureId, opts = {}) {
+        const featureName = opts.name ?? (0, track_feature_1.humaniseFeatureId)(featureId);
+        const visitorId = this.identityManager ? this.identityManager.getVisitorId() : (this.visitorId ?? "");
+        const stages = (0, track_feature_1.deriveFeatureStages)(`fg_feat:${visitorId}:${featureId}`, opts);
+        for (const stage of stages) {
+            // Only send what the caller provided — flowgrid-core fills userId
+            // (→ visitor_id) and a default category for anonymous feature usage.
+            this.track("feature_usage", { featureId, featureName, action: stage, ...(opts.category ? { category: opts.category } : {}), ...(opts.properties ?? {}) }, { domain: "feature" });
+        }
+    }
     /**
      * Track a page view. Auto-detects URL/path/title/referrer in the browser.
      *
@@ -1026,6 +1052,12 @@ class FlowGrid {
         if (options.attribution === true && ctx.userId) {
             this.attribution.captureFromUrl(ctx.userId);
         }
+        // Passive identity capture is off by default — the flowgrid.js core script
+        // already runs it for snippet installs; SDK-only sites opt in here.
+        if (options.passiveIdentity === true || (options.passiveIdentity !== false && typeof options.passiveIdentity === "object")) {
+            const piOpts = typeof options.passiveIdentity === "object" ? options.passiveIdentity : {};
+            teardowns.push(this.identify.client.autoTrackForms(piOpts));
+        }
         if (options.replay !== false) {
             const replayOpts = typeof options.replay === "object" ? options.replay : {};
             // start() is async; track its resolved teardown so the outer stop()