flowgrid-sdk 1.6.8 → 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,33 +171,51 @@ Each replay chunk includes the core ingestion fields `web_id`, `visitor_id`, `se
 
 ---
 
-## Feature Usage (one-liner)
+## Feature Usage
 
-Track product feature adoption with a **single call** — the SDK derives the whole
-lifecycle so you don't hand-emit each stage:
+Track product feature usage with a plain event — `featureId` and `featureName`
+are the only required props:
 
 ```ts
-fg.feature("ai-agent-builder");                      // auto: discovered → viewed → adopted
-fg.feature("ai-agent-builder", { completed: true }); // finished the job
-fg.feature("ai-agent-builder", { abandoned: true }); // started, gave up
-// script tag: FlowGrid.feature("ai-agent-builder")
+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()
 ```
 
-Per visitor, the SDK records first-ever use as **discovered** (+ viewed),
-subsequent uses as **viewed**, and emits **adopted** once after repeated use
-(default ≥2 distinct days or ≥5 uses; tune via `adoptionDays`/`adoptionUses`).
-Stages map 1:1 to the dashboard's adoption funnel. Display name is humanised from
-the id unless you pass `{ name }`; add `{ category }` to group features.
-
-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"`). Provide them only to attribute usage to a known user / group features.
-
-Each derived stage is emitted through the unified **`.track("feature_usage", …)`**
-router (so it shares routing/consent/transport with every other event). Lifecycle
-state is kept in `localStorage` per visitor; if it's unavailable the call still
-records a `viewed`. The low-level `fg.features.used(id, name, stage)` remains for
-explicit-stage control.
+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.
 
 ---
 

package/dist/browser.d.ts

@@ -44,7 +44,7 @@ type BrowserFacade = {
     track: FlowGrid["track"];
     page: FlowGrid["page"];
     identify: FlowGrid["identifyUser"];
-    feature: FlowGrid["feature"];
+    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,8 +84,8 @@ const browserFlowGrid = {
     identify(userId, traits, anonymousId) {
         return getInstance().identifyUser(userId, traits, anonymousId);
     },
-    feature(featureId, opts) {
-        return getInstance().feature(featureId, opts);
+    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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"}