@forgecart/cli 2.202607091048.0 → 2.202607120419.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgecart/cli",
-  "version": "2.202607091048.0",
+  "version": "2.202607120419.0",
   "type": "module",
   "description": "CLI for scaffolding and operating ForgeCart channel storefronts",
   "bin": {

package/templates/storefront/src/app/layout.tsx

@@ -1,6 +1,7 @@
 import type { Metadata } from 'next';
 import type { ReactNode } from 'react';
 
+import { ForgeAnalytics } from '../components/ForgeAnalytics';
 import { ForgeErrorBeacon } from '../components/ForgeErrorBeacon';
 import { ForgecartDesigner } from '../components/ForgecartDesigner';
 import { Header } from '../components/Header';
@@ -30,6 +31,10 @@ export default async function RootLayout({ children }: { children: ReactNode })
         </CartProvider>
         <ForgecartDesigner />
         <ForgeErrorBeacon />
+        <ForgeAnalytics
+          shopApiUrl={process.env.FORGECART_SHOP_API_URL ?? ''}
+          channelToken={process.env.FORGECART_CHANNEL_TOKEN ?? ''}
+        />
       </body>
     </html>
   );

package/templates/storefront/src/components/ForgeAnalytics.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import { ForgeCartShopClient } from '@forgecart/sdk';
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
+
+/**
+ * Storefront analytics tracker. Renders nothing.
+ *
+ * Emits the marketing events that drive the dashboard's live-visitor count and
+ * realtime map:
+ *
+ *   - `page_view` on the initial load and on every App-Router route change;
+ *   - `heartbeat` every {@link HEARTBEAT_MS} while the tab is VISIBLE (plus one
+ *     immediately on refocus), so an idle-but-open tab stays inside the live
+ *     window. Heartbeats are liveness plumbing only — the backend excludes
+ *     them from every event-counting aggregate.
+ *
+ * Identity needs no code here: the SDK's WebSocket connect mints an anonymous
+ * shop session server-side, captures the returned token, and persists it in
+ * localStorage — so every event from this browser rides one identity, and the
+ * server enriches geo/device from the connection's own IP/UA.
+ *
+ * Two deliberate suppressions:
+ *   - missing config (the pod image pre-renders the template before
+ *     `forgecart init` writes `.env.local`) → the tracker is inert;
+ *   - framed embeds (`window.parent !== window`) → the visual editor's
+ *     artboard preview never counts its own admin as a live visitor. A normal
+ *     top-level tab on the same URL still counts.
+ *
+ * Unlike `ForgeErrorBeacon` there is NO `NODE_ENV` gate — tracking is a
+ * production feature. Every send is fire-and-forget and swallows failures:
+ * analytics must never break the storefront.
+ */
+
+const HEARTBEAT_MS = 60_000;
+/** Minimum spacing between sends of the same signal (StrictMode remounts, rapid refocus). */
+const DEDUP_MS = 30_000;
+
+let client: ForgeCartShopClient | null = null;
+let lastPageView: { path: string; at: number } | null = null;
+let lastHeartbeatAt = 0;
+
+function getClient(shopApiUrl: string, channelToken: string): ForgeCartShopClient {
+  if (!client) {
+    client = new ForgeCartShopClient({ endpoint: shopApiUrl, channelToken });
+  }
+  return client;
+}
+
+async function send(
+  shopApiUrl: string,
+  channelToken: string,
+  eventType: string,
+  properties?: Record<string, unknown>,
+): Promise<void> {
+  try {
+    await getClient(shopApiUrl, channelToken).marketingEvent.shopTrackEvent({
+      input: { eventType, properties },
+    });
+  } catch {
+    // Best-effort by design: a failed send (offline, rate-limited, booting
+    // backend) must never surface in the storefront.
+  }
+}
+
+export function ForgeAnalytics({
+  shopApiUrl,
+  channelToken,
+}: {
+  shopApiUrl: string;
+  channelToken: string;
+}) {
+  const pathname = usePathname();
+
+  // page_view — initial load + every route change.
+  useEffect(() => {
+    if (!shopApiUrl || !channelToken) return;
+    if (window.parent !== window) return;
+    const now = Date.now();
+    if (lastPageView && lastPageView.path === pathname && now - lastPageView.at < DEDUP_MS) {
+      return;
+    }
+    lastPageView = { path: pathname, at: now };
+    void send(shopApiUrl, channelToken, 'page_view', { path: pathname });
+  }, [shopApiUrl, channelToken, pathname]);
+
+  // heartbeat — while visible, plus one on refocus; paused while hidden.
+  useEffect(() => {
+    if (!shopApiUrl || !channelToken) return;
+    if (window.parent !== window) return;
+
+    let interval: ReturnType<typeof setInterval> | null = null;
+
+    const beat = () => {
+      const now = Date.now();
+      if (now - lastHeartbeatAt < DEDUP_MS) return;
+      lastHeartbeatAt = now;
+      void send(shopApiUrl, channelToken, 'heartbeat');
+    };
+    const start = () => {
+      if (interval !== null) return;
+      interval = setInterval(beat, HEARTBEAT_MS);
+    };
+    const stop = () => {
+      if (interval === null) return;
+      clearInterval(interval);
+      interval = null;
+    };
+    const onVisibility = () => {
+      if (document.visibilityState === 'visible') {
+        beat();
+        start();
+      } else {
+        stop();
+      }
+    };
+
+    document.addEventListener('visibilitychange', onVisibility);
+    if (document.visibilityState === 'visible') start();
+    return () => {
+      document.removeEventListener('visibilitychange', onVisibility);
+      stop();
+    };
+  }, [shopApiUrl, channelToken]);
+
+  return null;
+}