flowgrid-sdk 1.6.7 → 1.6.9

package/README.md

@@ -34,6 +34,8 @@ await fg.track("add_to_cart", { productId: "sku_1", name: "T-Shirt", price: 29,
 ## Highlights
 
 - **One class, every feature** — `new FlowGrid(...)` exposes analytics, ecommerce, experiments, and enterprise modules as lazy properties.
+- **Feature usage, explicit** — `fg.track("feature_usage", { featureId, featureName })`. You say what happened; the SDK just sends it.
+- **Passive identity** — opt in with `autoTrack({ passiveIdentity: true })` to recognise anonymous visitors from any form (PII hashed in the browser).
 - **Framework-agnostic** — zero peer dependencies. Works with React, Vue, Next.js, Nuxt, Svelte, Astro, plain Node, Cloudflare Workers, etc.
 - **Tree-shake-friendly** — also export individual modules (`Events`, `Products`, `Experiment`, …) for minimal bundles.
 - **Privacy & consent built-in** — DNT/GPC support, `ConsentManager`, bot filtering.
@@ -73,6 +75,9 @@ const fg = FlowGrid.init({
 // Plain custom events still work.
 await fg.track("cta_click", { id: "hero" }, { userId: "u_1" });
 
+// Feature usage — a plain event.
+fg.track("feature_usage", { featureId: "data_export", featureName: "Data Export" });
+
 // Recognized event names route to the matching feature module.
 await fg.track("feature_used", { featureId: "export", featureName: "Data Export", userId: "u_1" });
 await fg.track("prompt_submitted", { promptId: "p_1", promptType: "chat", userId: "u_1" });
@@ -111,16 +116,19 @@ await events.track({ eventName: "signup", properties: { plan: "pro" } });
 
   FlowGrid.track("signup_clicked", { placement: "hero" });
   FlowGrid.identify("user_123", { plan: "pro" });
+  FlowGrid.track("feature_usage", { featureId: "ai_agent_builder", featureName: "AI Agent Builder" });
   FlowGrid.productView({ productId: "sku_1", name: "T-Shirt", price: 29 });
   FlowGrid.addToCart({ productId: "sku_1", name: "T-Shirt", price: 29 }, 1);
 </script>
 ```
 
 The script-tag API is intentionally small: `init`, `track`, `page`, `identify`,
-`experiment`, `productView`, `addToCart`, `purchase`, consent helpers, and
-`instance()` for the full SDK. `FlowGrid.init()` auto-instruments sessions, page
-views, SPA route changes, scroll depth, time on page, performance, heatmaps,
-and attribution by default; session replay is opt-in with `replay: true`.
+`feature`, `experiment`, `productView`, `addToCart`, `purchase`, `autoTrack`,
+consent helpers (`setConsent` / `hasConsent`), `reset`, and `instance()` for the
+full SDK. `FlowGrid.init()` auto-instruments sessions, page views, SPA route
+changes, scroll depth, time on page, performance, heatmaps, and attribution by
+default; session replay is opt-in with `replay: true`, and passive identity
+capture with `autoTrack({ passiveIdentity: true })`.
 
 ---
 
@@ -163,6 +171,82 @@ Each replay chunk includes the core ingestion fields `web_id`, `visitor_id`, `se
 
 ---
 
+## Feature Usage
+
+Track product feature usage with a plain event — `featureId` and `featureName`
+are the only required props:
+
+```ts
+fg.track("feature_usage", { featureId: "ai_agent_builder", featureName: "AI Agent Builder" });
+
+// Optional: an action ("viewed" | "used" | "completed" | "abandoned"), a category, a known user.
+fg.track("feature_usage", {
+  featureId: "ai_agent_builder",
+  featureName: "AI Agent Builder",
+  action: "completed",
+  category: "automation",
+  userId: "u_1",
+});
+// script tag: FlowGrid.track("feature_usage", { featureId: "ai_agent_builder", featureName: "AI Agent Builder" })
+```
+
+`action` defaults to `"used"`. No `userId` or `category` is required — it works
+for anonymous visitors out of the box (the backend defaults `userId` to the
+visitor and `category` to `"general"`). The event routes through the unified
+`.track()` router, so it shares routing/consent/transport with every other event.
+
+### Helpers
+
+Don't want to hand-write `track("feature_usage", …)` and repeat the id/name?
+Bind a feature once with **`fg.defineFeature`** and call the verb that describes
+what happened — each maps to a lifecycle stage the dashboard funnel understands
+(a *viewed* feature is Discovered, a *used* one is Adopted):
+
+```ts
+const agent = fg.defineFeature("ai-agent-builder", "AI Agent Builder", { category: "automation" });
+
+agent.viewed();                 // action: "viewed"    → Discovered + Viewed
+agent.used({ model: "opus" });  // action: "used"      → Adopted
+agent.completed();              // action: "completed" → Completed
+agent.abandoned();              // action: "abandoned" → Abandonment
+// script tag: FlowGrid.defineFeature("ai-agent-builder", "AI Agent Builder").used()
+```
+
+Each call is a thin, explicit wrapper over `track("feature_usage", …)` — no
+hidden state, no lifecycle guessing; you send exactly the action you name. The
+same verbs exist on `fg.features.viewed/used/completed/abandoned(id, name)` for
+one-off calls, and `fg.features.record(id, name, action)` for a dynamic action.
+
+---
+
+## Passive Identity Capture
+
+Recognise anonymous visitors automatically: when a visitor types their email /
+name / phone into **any** form, FlowGrid classifies the field, hashes PII in the
+browser, and links the identity to their `visitor_id` — so the dashboard shows
+them by name (and, with a CRM connected, matches them to the contact). No
+per-form instrumentation.
+
+It's **opt-in** in the SDK (the `flowgrid.js` snippet runs it by default) and
+requires `analytics` consent:
+
+```ts
+const fg = FlowGrid.init({ webId: "...", apiKey: "..." });
+FlowGrid.setConsent({ analytics: true });
+
+const stop = fg.autoTrack({ passiveIdentity: true });
+// or with options:
+fg.autoTrack({ passiveIdentity: { debounceMs: 800, excludePath: /\/(checkout|admin)/i } });
+```
+
+Never reads `password`/`hidden`/card/cvv/ssn/pin fields, anything marked
+`data-analytics="ignore"` or `.no-track`, free-text (message/comment/search), or
+sensitive paths (`/checkout`, `/account/settings`, `/admin`). Raw email goes only
+to the server-side identity store; the event stream sees hashes. Full guide:
+`vission_manager/docs/PASSIVE_IDENTITY_DEVELOPER_GUIDE.md`.
+
+---
+
 ## Server-side / Edge Usage
 
 Works in any JavaScript runtime that supports `fetch` — Node, Bun, Deno, Cloudflare Workers, Vercel Edge, etc.

package/dist/browser.d.ts

@@ -44,6 +44,7 @@ type BrowserFacade = {
     track: FlowGrid["track"];
     page: FlowGrid["page"];
     identify: FlowGrid["identifyUser"];
+    defineFeature: FlowGrid["defineFeature"];
     experiment: FlowGrid["experiment"];
     productView(product: BrowserProduct, properties?: Record<string, unknown>): ReturnType<FlowGrid["products"]["view"]>;
     addToCart(product: BrowserProduct, quantity?: number, cartId?: string): ReturnType<FlowGrid["cart"]["add"]>;

package/dist/browser.js

@@ -84,6 +84,9 @@ const browserFlowGrid = {
     identify(userId, traits, anonymousId) {
         return getInstance().identifyUser(userId, traits, anonymousId);
     },
+    defineFeature(featureId, featureName, opts) {
+        return getInstance().defineFeature(featureId, featureName, opts);
+    },
     experiment(experimentId, options) {
         return getInstance().experiment(experimentId, options);
     },

package/dist/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}