flowgrid-sdk 1.7.7 → 1.7.8

package/README.md

@@ -62,7 +62,54 @@ Requires Node `>= 18.12`. No peer dependencies.
 
 ## Quick Start
 
-### Unified client (recommended)
+FlowGrid is one platform with two runtimes. Initialise **once per runtime** —
+the browser client for everything a visitor does on the page, the server
+client for what happens in your backend — and both feed the same dashboard
+under the same identity:
+
+```ts
+// lib/flowgrid.client.ts — BROWSER: init once, import everywhere client-side
+import { FlowGrid } from "flowgrid-sdk";
+
+export const fg = FlowGrid.init({
+  webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!,   // public site id (wx_…)
+  apiKey: process.env.NEXT_PUBLIC_FLOWGRID_API_KEY!, // public API key
+
+  // Who is this? (optional — identifies up-front so the very first events attribute)
+  user: { userId: "u_1", email: "alice@example.com", name: "Alice" },
+
+  // What gets auto-tracked? engagement + replay are on by default;
+  // pageviews/sessions/heatmaps/performance come from the script tag install.
+  autoTrack: {
+    engagement: true,
+    replay: { sampleRate: 1.0, maskAllInputs: true },
+    passiveIdentity: true, // recognise visitors from forms (PII hashed in-browser)
+  },
+
+  // What is the visitor consenting to? (see “Cookie Consent” below —
+  // pair with renderConsentBanner() for an opt-in banner in one call)
+  consent: { analytics: true, marketing: true },
+});
+```
+
+```ts
+// lib/flowgrid.server.ts — SERVER (Node ≥ 18 / edge): identity, feature usage, revenue, errors
+import { FlowGridServer } from "flowgrid-sdk/server";
+
+export const fgServer = FlowGridServer.init({
+  webId: process.env.NEXT_PUBLIC_FLOWGRID_WEB_ID!, // same site id
+  apiKey: process.env.FLOWGRID_API_KEY!,           // private key — server env only
+});
+```
+
+That's the whole setup. Browser calls (`fg.track`, `fg.identifyUser`,
+`fg.cart.add`, …) and server calls (`fgServer.trackAuth`,
+`fgServer.trackFeature`, `fgServer.trackPurchase`, `fgServer.trackError`, …) speak the same wire
+contract, so a user identified in an OAuth callback on the server and the
+same user clicking around in the browser resolve to **one identity** in the
+dashboard.
+
+### Unified client (browser)
 
 ```ts
 import { FlowGrid } from "flowgrid-sdk";
@@ -202,25 +249,193 @@ to the server-side identity store; the event stream sees hashes.
 
 ## Server-side / Edge Usage
 
-Works in any JavaScript runtime that supports `fetch` — Node, Bun, Deno, Cloudflare Workers, Vercel Edge, etc.
+Use the dedicated **`flowgrid-sdk/server`** entry point on the server. It is a
+Node/edge-safe client (global `fetch` only — no `window`, `document`, or
+storage) scoped to what makes sense off-browser: **identity**, **feature
+usage**, **ecommerce / revenue**, and **API / server error tracking**. It speaks the same wire contract
+as the browser SDK, so events land in the same pipes. Works in Node ≥ 18, Bun,
+Deno, Cloudflare Workers, and Vercel Edge/serverless.
 
 ```ts
-// app/api/track/route.ts (Next.js example, but works anywhere)
-import { fg } from "@/lib/utils";
+// lib/flowgrid-server.ts — init once, import anywhere server-side
+import { FlowGridServer } from "flowgrid-sdk/server";
+
+export const fg = FlowGridServer.init({
+  webId: process.env.NEXT_PUBLIC_WEB_ID!,
+  apiKey: process.env.FLOWGRID_API_KEY!, // required on the server
+});
+```
+
+**Identity — auth-level events** (identify a visitor server-side, e.g. in an
+OAuth callback or session endpoint). Pass the browser's visitor id when you
+have the request cookies so server events link to the web session; without it,
+a stable synthetic visitor is derived from the `userId`:
+
+```ts
+import { visitorIdFromCookies } from "flowgrid-sdk/server";
+import { cookies } from "next/headers";
+
+const visitorId = visitorIdFromCookies(await cookies());
+
+await fg.trackAuth(
+  { event: "login", userId: user.id, email: user.email, method: "google" },
+  { visitorId },
+); // identify + login_completed + active_user ping, in one call
+
+// Or the individual operations:
+await fg.identifyUser(user.id, { email: user.email, plan: "pro" }, { visitorId });
+await fg.updateTraits(user.id, { plan: "enterprise" });
+await fg.pingActiveUser(user.id, { email: user.email }); // DAU/WAU/MAU by identity
+await fg.logout(user.id);
+```
+
+**Feature usage** from API routes, jobs, and webhooks:
+
+```ts
+await fg.trackFeature({ featureId: "csv_export", featureName: "CSV Export", userId: user.id });
+
+// Or bind once and use semantic verbs (server twin of fg.defineFeature):
+const teamUpdate = fg.defineFeature("team_update", "Team update", { category: "teams" });
+await teamUpdate.used({ userId: user.id, teamId });
+```
+
+**Ecommerce / revenue** — record purchases, refunds, order lifecycle, and
+subscription MRR events from your **payment webhooks**, where the money is
+actually confirmed. Browser purchase events are structurally lossy (ad
+blockers, closed tabs on the checkout redirect); the server is the
+authoritative source for revenue:
 
-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 });
+```ts
+// Stripe webhook: checkout.session.completed
+await fg.trackPurchase({
+  order: {
+    orderId: session.id,
+    items,                              // CartItem[] — same shape as the browser SDK
+    subtotal, discountTotal: 0, shippingTotal: 0, taxTotal,
+    total: session.amount_total / 100,
+    currency: "USD",
+    payment: { method: "credit_card", provider: "stripe" },
+  },
+  userId: session.client_reference_id,
+});
+
+// charge.refunded — keeps net revenue accurate
+await fg.trackRefund({
+  orderId, refundId: refund.id,
+  amount: refund.amount / 100, currency: "USD",
+  reason: "customer_request", isFullRefund: true, userId,
+});
+
+// Fulfilment webhooks
+await fg.trackOrderStatus(orderId, "processing", "pending", { userId });
+await fg.trackOrderShipped(orderId, { method: "express", cost: 5, trackingNumber });
+await fg.trackOrderDelivered(orderId);
+
+// Subscription / MRR lifecycle — one method, discriminated on `event`:
+await fg.trackSubscription({
+  event: "start", // "change" | "cancel" | "renew" | "trial_converted" | "trial_expired"
+  subscriptionId: sub.id,
+  userId,
+  plan: "professional",
+  mrr: { amount: 9900, currency: "USD" }, // smallest currency unit
+  billingCycle: "monthly",
+  trialDays: 14,
+});
+```
+
+**Revenue attribution** — payment webhooks arrive with no cookies, so the
+visitor/session ids ride through the provider's checkout metadata and come
+back out in the webhook. Two legs:
+
+```ts
+// LEG 1 — checkout creation: embed the ids from the request cookies.
+import { checkoutAttributionFromCookies } from "flowgrid-sdk/server";
+import { cookies } from "next/headers";
+
+// Stripe
+const session = await stripe.checkout.sessions.create({
+  // …
+  metadata: { ...checkoutAttributionFromCookies(await cookies()) },
+});
+
+// Lemon Squeezy
+const checkout = await createCheckout(storeId, variantId, {
+  checkoutData: { custom: { ...checkoutAttributionFromCookies(await cookies()) } },
+});
+
+// (Creating the checkout client-side instead? Use fg.checkoutAttribution()
+//  from the browser SDK — same keys.)
+```
+
+```ts
+// LEG 2 — webhook: read the ids back and attach them to the revenue event.
+import { attributionFromMetadata } from "flowgrid-sdk/server";
+
+// Stripe checkout.session.completed — unwraps `.metadata` automatically
+const { visitorId, sessionId } = attributionFromMetadata(event.data.object);
+
+// Lemon Squeezy order_created — unwraps `.meta.custom_data` automatically
+// const { visitorId, sessionId } = attributionFromMetadata(payload);
+
+await fg.trackPurchase({ order, userId }, { visitorId, sessionId });
+```
+
+With the real `visitorId` + `sessionId` on the purchase, revenue joins the
+visitor's full journey — the session, landing page and UTM campaign that
+earned it — instead of a synthetic server visitor.
+
+**API + server-side error tracking** — errors become `error_event`s with
+route/method/status context; FlowGrid-internal noise is filtered out:
+
+```ts
+try { … } catch (err) {
+  await fg.trackError(err, { route: "/api/teams/edit/[teamId]", method: "PATCH", statusCode: 500, userId });
+  throw err;
 }
+
+// Or wrap a handler — tracks and rethrows, framework behaviour unchanged:
+export const PATCH = fg.withErrorTracking(handler, { route: "/api/teams/edit/[teamId]", method: "PATCH" });
+
+// Opt-in process-level capture (Node only; observes, never swallows):
+const detach = fg.captureUncaught();
 ```
 
-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.
+Like the browser transport, the server client **never throws** for delivery
+problems — every method resolves `{ ok, status?, reason? }`.
 
 ---
 
 ## Cookie Consent
 
+### What you're asking consent for
+
+When a visitor accepts cookies, this is exactly what each category permits
+FlowGrid to do (this is what the SDK enforces, not aspirational copy — each
+category maps to a hard gate in the transport).
+
+**Default posture: implied consent.** Every category starts granted, and
+tracking runs out of the box — the "declined" behaviour below only applies
+when you've installed a consent gate (`requireExplicitConsent: true` or the
+opt-in banner) and the visitor actively rejects a category:
+
+| Category      | Can the visitor decline? | What it covers |
+| ------------- | ------------------------ | -------------- |
+| `necessary`   | No — always on           | The visitor/session identifiers (`visitor_id` cookie, `fg_session_id`) and the consent cookies themselves (`fg_consent`, `fg_tracking_consent`). Required for the service to function; no behavioural profiling. |
+| `analytics`   | Yes                      | **All event tracking.** Page views, sessions, clicks, forms, searches, feature usage, funnels, performance/Web Vitals, engagement, identity events (`identifyUser`, active-user pings), and **session replay** recordings — plus the device/page context attached to each event (screen size, device type, language, URL, path, title, referrer). Declined → no events leave the browser. |
+| `marketing`   | Yes                      | **Campaign attribution.** The `utm_source/medium/campaign/term/content` and `ref`/`via`/`source` parameters read from the URL and the `__flowgrid_*` landing-page cookies, attached to events as `_utm_*`/`_ref` properties. Declined → events (if analytics is granted) are sent **without** any campaign attribution. |
+| `preferences` | Yes                      | UI preferences your own app stores (locale, theme). FlowGrid itself stores nothing in this category — it exists so your banner can offer it. |
+
+Independent of the banner, visitors sending **Do-Not-Track** or **Global
+Privacy Control** are treated as having declined non-essential tracking by
+default (`respectDNT: true`), and localhost traffic is never tracked unless
+explicitly enabled.
+
+Server-side events (`flowgrid-sdk/server`) are outside the browser consent
+gates by design: they represent your backend's own records (auth events,
+API feature usage, server errors) under your contractual/legitimate-interest
+basis. If you want browser consent to extend to server calls, check your
+stored consent state before calling the server client.
+
 ### No-code (one tag) — recommended
 
 Drop a single element on the page and FlowGrid renders a styled, **opt-in**,
@@ -339,6 +554,7 @@ FlowGridTransport.hasConsent("analytics"); // true
 | `flowgrid-sdk/ecommerce`   | Ecommerce modules only                           |
 | `flowgrid-sdk/core`        | Core modules (activation, experiments, prompts)  |
 | `flowgrid-sdk/consent`     | `ConsentManager` + types                         |
+| `flowgrid-sdk/server`      | `FlowGridServer` — Node/edge tracking (identity, feature usage, revenue, errors) |
 | `flowgrid-sdk/types`       | Shared TypeScript type definitions               |
 
 ---