Flowgrid SDK

A production-grade, framework-agnostic TypeScript SDK for product analytics, ecommerce, experiments, and enterprise insights — with a single unified entry point that works in any JavaScript environment (Node, browsers, edge runtimes, React, Vue, Next, Nuxt, Svelte, Angular, etc.).

import { FlowGrid } from "flowgrid-sdk";

// One line. Sane defaults. Auto-instruments sessions, page views,
// performance, heatmaps, and attribution out of the box.
const fg = FlowGrid.init({ webId: "wx_123", apiKey: "pk_xxx" });

// Opt in to session replay (rrweb) when you want it:
FlowGrid.init({
  webId: "wx_123",
  apiKey: "pk_xxx",
  user: { userId: "u_1", traits: { plan: "pro" } },
  replay: { sampleRate: 0.25, maskAllInputs: true },
});

await fg.track("signup_completed", { plan: "pro" });
await fg.experiment("checkout_v2", { variant: "B", userId: "u_1" });
await fg.products.view({ productId: "sku_1", name: "T-Shirt", price: 29, currency: "USD" });

Highlights

• One class, every feature — new FlowGrid(...) exposes analytics, ecommerce, experiments, and enterprise modules as lazy properties.
• 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.
• Resilient transport — retry with exponential backoff, sendBeacon fallback, offline localStorage buffering, 10KB payload guard.
• Identity layer — visitor + session lifecycle, SSR-safe, backwards-compatible with track.js cookies.
• Strict TypeScript — strong types for every config and response.

Installation

npm install flowgrid-sdk
# or
pnpm add flowgrid-sdk
# or
yarn add flowgrid-sdk

Requires Node >= 18.12. No peer dependencies.

Quick Start

Unified client (recommended)

import { FlowGrid } from "flowgrid-sdk";

const fg = new FlowGrid(
  "web_123",                       // webId
  "https://core.flow-grid.xyz",     // endpoint
  "key_xxx"                        // apiKey
);

// Analytics
await fg.pageViews.track({ url: "/pricing", title: "Pricing" });
await fg.events.track({ eventName: "cta_click", properties: { id: "hero" } });
await fg.identify.identify({ userId: "u_1", traits: { plan: "pro" } });

// Ecommerce
await fg.cart.addItem({
  product: { productId: "sku_1", name: "Widget", price: 29.99, currency: "USD" },
  quantity: 1,
  cartId: "cart_abc",
});

// Experiments
const variant = await fg.experiments.assign({
  experimentId: "checkout_v2",
  userId: "u_1",
});

// Enterprise
await fg.churn.score({ userId: "u_1" });

Available namespaces on FlowGrid:

| Group | Properties | | ----------- | ----------------------------------------------------------------------------------------------------------------------- | | Core | activation, features, prompts, experiments | | Analytics | pageViews, sessions, events, identify, funnels, retention, attribution, heatmaps, performance, replay | | Ecommerce | products, cart, checkout, purchases, refunds, promotions, wishlist, ltv, search, subscriptions | | Enterprise | engagement, cohorts, churn, monetization, multiPathFunnels, support, acquisition, paths, alerts, security, forecasting |

Direct module imports (tree-shaking)

import { Events, Products } from "flowgrid-sdk";

const events = new Events("web_123", "https://core.flow-grid.xyz", "key_xxx");
await events.track({ eventName: "signup", properties: { plan: "pro" } });

Browser script tag (CMS / no-build)

<script src="https://cdn.flow-grid.xyz/flowgrid.min.js"></script>
<script>
  FlowGrid.init({
    webId: "web_abc123",
    apiKey: "key_xxx",
  });

  FlowGrid.track("signup_clicked", { placement: "hero" });
  FlowGrid.identify("user_123", { plan: "pro" });
  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.

Session Replay

Replay is opt-in and browser-only. It uses rrweb dynamically, records DOM/input/scroll/mouse events, and sends sequenced chunks to core with call=replay_chunk.

const fg = FlowGrid.init({
  webId: "wx_123",
  apiKey: "pk_xxx",
  user: { userId: "u_1" },
  replay: {
    sampleRate: 0.25,
    maskAllInputs: true,
    flushIntervalMs: 5000,
    flushBytes: 512 * 1024,
    onFlush: ({ sessionId, sequence, eventsCount }) => {
      console.debug("replay chunk", sessionId, sequence, eventsCount);
    },
  },
});

fg.replay.identify("u_1");
await fg.replay.flush();
fg.replay.stop();

Manual lifecycle control is available when you do not want init-time recording:

const stop = await fg.replay.start({ sampleRate: 1, maskAllInputs: true });
const status = fg.replay.status();

await fg.replay.flush("manual");
stop();

Each replay chunk includes the core ingestion fields web_id, visitor_id, session_id, sequence, started_at, captured_at, events, plus replay metadata such as page_url, idempotency_key, compression, is_final, privacy, flush_reason, dropped_events, and recorder_version.

Server-side / Edge Usage

Works in any JavaScript runtime that supports fetch — Node, Bun, Deno, Cloudflare Workers, Vercel Edge, etc.

// app/api/track/route.ts (Next.js example, but works anywhere)
import { FlowGrid } from "flowgrid-sdk";

const fg = new FlowGrid("web_123", "https://core.flow-grid.xyz", process.env.FG_API_KEY!);

export async function POST(req: Request) {
  const { userId } = await req.json();
  await fg.events.track({ eventName: "server_event", properties: { userId } });
  return Response.json({ ok: true });
}

For Node-style batch jobs, simply create a FlowGrid instance, fire your tracking calls, and let the process exit — events use sendBeacon/fetch and a localStorage-style buffer for resilience.

Cookie Consent

The SDK ships a framework-agnostic ConsentManager. Render your own banner UI in whatever framework you use, and call into the manager to persist preferences.

import { ConsentManager, FlowGridTransport } from "flowgrid-sdk";

const consent = new ConsentManager({
  cookieDomain: ".example.com",
  cookieExpiry: 365,
  respectDNT: true,
  onChange: (prefs) => {
    FlowGridTransport.setConsent({
      analytics: prefs.analytics,
      marketing: prefs.marketing,
    });
  },
});

consent.acceptAll();
consent.rejectNonEssential();
consent.update({ analytics: true, marketing: false, preferences: true });
consent.hasCategory("analytics"); // boolean
consent.reset();

CookieBannerConfig and CookieBannerTheme types are exported from flowgrid-sdk/consent if you want a typed config object to pass to your own banner component.

You can also gate the transport directly without ConsentManager:

import { FlowGridTransport } from "flowgrid-sdk";

FlowGridTransport.setConsent({ analytics: true, marketing: false });
FlowGridTransport.hasConsent("analytics"); // true

Identity & Storage Helpers

import {
  FlowGrid,
  IdentityManager,
  getVisitorId,
  getSessionId,
  getWebId,
  getUTM,
  getUTMHistory,
} from "flowgrid-sdk";

const identity = new IdentityManager({ cookieDomain: ".example.com" });
const visitorId = identity.getVisitorId();

// Pass to FlowGrid for shared identity across modules
const fg = new FlowGrid(
  "web_123",
  "https://core.flow-grid.xyz",
  "key_xxx",
  visitorId,
  identity
);

Package Exports

| Import path | Description | | -------------------------- | ------------------------------------------------ | | flowgrid-sdk | Unified FlowGrid class + every feature module | | flowgrid-sdk/analytics | Analytics modules only | | flowgrid-sdk/ecommerce | Ecommerce modules only | | flowgrid-sdk/core | Core modules (activation, experiments, prompts) | | flowgrid-sdk/consent | ConsentManager + types | | flowgrid-sdk/types | Shared TypeScript type definitions |

Configuration

The transport accepts an optional FlowGridTransportConfig as its 6th argument:

new FlowGrid(webId, endpoint, apiKey, visitorId, identityManager, {
  botDetection: "block",   // "block" | "tag" | "disabled"
  respectDNT: true,         // honour Do-Not-Track / GPC
  sampleRate: 1.0,          // 0.0 – 1.0
});

Defaults: botDetection: "block", respectDNT: true, sampleRate: 1.0.

Scripts

npm run build          # tsc + webpack production build
npm run build:browser  # browser UMD bundle (flowgrid.min.js)
npm run build:all      # both
npm run build:types    # emit .d.ts only
npm test               # run audit-fixes test suite

Documentation

Full reference: https://flow-grid.xyz/documentation

Contributing

Issues and PRs welcome on GitHub.

License

MIT © Brandon Roulstone