@sixtynine-digital/cms-tracking

Server-side, first-party event tracking for SIXTYNINE CMS (Pulse analytics).

Events are sent from your backend (Server Action / route handler / middleware) to the CMS. The browser only ever talks to your own origin, so the delivery key never ships to the client, and tracking is GDPR-friendly by design.

npm install @sixtynine-digital/cms-tracking

1. Create a tracker (server-only)

// lib/tracker.ts
import { createTracker } from "@sixtynine-digital/cms-tracking";

export const tracker = createTracker({
  apiKey: process.env.CMS_DELIVERY_KEY!, // a "delivery" key — keep it server-side
  baseUrl: process.env.CMS_BASE_URL!,    // e.g. https://cms.example.com/api/v1
});

2. First-party track route

// app/api/track/route.ts
import { createTrackHandler } from "@sixtynine-digital/cms-tracking/next";
import { tracker } from "@/lib/tracker";

export const POST = createTrackHandler({ tracker });

3. Automatic page views (Next 16)

// proxy.ts
import { NextResponse, type NextRequest, type NextFetchEvent } from "next/server";
import { trackPageView } from "@sixtynine-digital/cms-tracking/next";

export function proxy(request: NextRequest, event: NextFetchEvent) {
  const { pathname } = request.nextUrl;
  if (!pathname.startsWith("/_next") && !pathname.startsWith("/api")) {
    trackPageView(event, request);
  }
  return NextResponse.next();
}

export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };

4. Fire custom events

// app/actions/track.ts
"use server";
import { tracker } from "@/lib/tracker";

export async function trackAddToCart(itemId: string) {
  await tracker.track("add_to_cart", { item_id: itemId, price: 49 });
}

API

• createTracker({ apiKey, baseUrl, debug? }) → Tracker
• tracker.track(eventName, props?, ctx?) — never throws; resolves void.
• tracker.getEventSchema() — fetch the tenant's event catalog (throws on failure).
• createTrackHandler({ tracker }) — a POST handler that always returns 202.
• trackPageView(event, request, { endpoint? }) — fire-and-forget page view.

track and the handler swallow all errors so analytics can never break the host site. Set debug: true to log failures during development.