@mitchdesigns/tracking 1.2.4 → 1.3.0

package/bin/cli.mjs

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// @mitchdesigns/tracking installer
+// Usage: pnpm dlx @mitchdesigns/tracking init [options]
+//
+// Scaffolds everything needed to use the tracking package in a Next.js project:
+//   - installs the package
+//   - .env.example tracking vars
+//   - transpilePackages entry in next.config.*
+//   - src/app/api/meta/capi/route.ts
+//   - src/components/meta/MetaEventTemplates.tsx
+//
+// Options:
+//   --dry-run        show what would change, write nothing
+//   --yes, -y        skip the install step's confirmation
+//   --no-install     don't run the package manager install
+//   --pm <pnpm|npm|yarn>   force a package manager (default: auto-detect)
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG = "@mitchdesigns/tracking";
+const TEMPLATES = path.join(__dirname, "..", "templates");
+
+// ---- args -----------------------------------------------------------------
+const argv = process.argv.slice(2);
+const cmd = argv.find((a) => !a.startsWith("-")) ?? "init";
+const has = (f) => argv.includes(f);
+const flagVal = (f) => {
+  const i = argv.indexOf(f);
+  return i !== -1 ? argv[i + 1] : undefined;
+};
+const DRY = has("--dry-run");
+const YES = has("--yes") || has("-y");
+const NO_INSTALL = has("--no-install");
+
+// ---- tiny logger ----------------------------------------------------------
+const c = {
+  g: (s) => `\x1b[32m${s}\x1b[0m`,
+  y: (s) => `\x1b[33m${s}\x1b[0m`,
+  r: (s) => `\x1b[31m${s}\x1b[0m`,
+  d: (s) => `\x1b[2m${s}\x1b[0m`,
+  b: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+const done = (m) => console.log(`  ${c.g("✔")} ${m}`);
+const skip = (m) => console.log(`  ${c.d("•")} ${c.d(m)}`);
+const warn = (m) => console.log(`  ${c.y("!")} ${m}`);
+const note = (m) => console.log(`  ${c.d("→")} ${c.d(m)}`);
+
+const root = process.cwd();
+
+function write(rel, contents, { merge } = {}) {
+  const abs = path.join(root, rel);
+  if (fs.existsSync(abs)) {
+    const existing = fs.readFileSync(abs, "utf8");
+    if (merge) {
+      const merged = merge(existing);
+      if (merged == null) return skip(`${rel} already configured`);
+      if (DRY) return warn(`would update ${rel}`);
+      fs.writeFileSync(abs, merged);
+      return done(`updated ${rel}`);
+    }
+    return skip(`${rel} exists — left untouched`);
+  }
+  if (DRY) return warn(`would create ${rel}`);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, contents);
+  done(`created ${rel}`);
+}
+
+function detectPM() {
+  const forced = flagVal("--pm");
+  if (forced) return forced;
+  if (fs.existsSync(path.join(root, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(root, "yarn.lock"))) return "yarn";
+  if (fs.existsSync(path.join(root, "package-lock.json"))) return "npm";
+  return "pnpm";
+}
+
+function srcPrefix() {
+  // honor src/ vs app/ at repo root
+  return fs.existsSync(path.join(root, "src")) ? "src" : "";
+}
+
+// ---- steps ----------------------------------------------------------------
+
+function checkProject() {
+  if (!fs.existsSync(path.join(root, "package.json"))) {
+    console.error(c.r(`No package.json in ${root}. Run this from your project root.`));
+    process.exit(1);
+  }
+}
+
+function installPackage(pm) {
+  if (NO_INSTALL) return skip("skipped install (--no-install)");
+  const cmds = {
+    pnpm: `pnpm add ${PKG}`,
+    npm: `npm install ${PKG}`,
+    yarn: `yarn add ${PKG}`,
+  };
+  const command = cmds[pm] ?? cmds.pnpm;
+  if (DRY) return warn(`would run: ${command}`);
+  console.log(`  ${c.d("$")} ${command}`);
+  try {
+    execSync(command, { stdio: "inherit", cwd: root });
+    done(`installed ${PKG}`);
+  } catch {
+    warn(`install failed — run \`${command}\` manually`);
+  }
+}
+
+function ensureEnv() {
+  const stub = fs.readFileSync(path.join(TEMPLATES, "env.example"), "utf8");
+  write(".env.example", stub, {
+    merge: (existing) =>
+      existing.includes("NEXT_PUBLIC_META_PIXEL_ID") ? null : `${existing.trimEnd()}\n\n${stub}`,
+  });
+}
+
+function patchNextConfig() {
+  const candidates = ["next.config.mjs", "next.config.js", "next.config.ts"];
+  const file = candidates.find((f) => fs.existsSync(path.join(root, f)));
+  if (!file) {
+    warn("no next.config.* found — add transpilePackages manually:");
+    note(`transpilePackages: ["${PKG}"]`);
+    return;
+  }
+  const abs = path.join(root, file);
+  let src = fs.readFileSync(abs, "utf8");
+
+  if (src.includes(PKG)) return skip(`${file} already lists ${PKG}`);
+
+  if (/transpilePackages\s*:\s*\[/.test(src)) {
+    // append to the existing array
+    src = src.replace(/transpilePackages\s*:\s*\[/, (m) => `${m}"${PKG}", `);
+  } else {
+    // insert a new key into the first config object literal
+    const m = src.match(/(\b(?:const|let|var)\s+\w+\s*(?::[^=]+)?=\s*\{)/);
+    if (!m) {
+      warn(`couldn't auto-edit ${file} — add transpilePackages manually:`);
+      note(`transpilePackages: ["${PKG}"],`);
+      return;
+    }
+    src = src.replace(m[0], `${m[0]}\n  transpilePackages: ["${PKG}"],`);
+  }
+  if (DRY) return warn(`would update ${file}`);
+  fs.writeFileSync(abs, src);
+  done(`added transpilePackages to ${file}`);
+}
+
+function scaffoldFiles() {
+  const sp = srcPrefix();
+  const routeDir = path.join(sp, "app", "api", "meta", "capi");
+  write(
+    path.join(routeDir, "route.ts"),
+    fs.readFileSync(path.join(TEMPLATES, "capi-route.ts"), "utf8"),
+  );
+  write(
+    path.join(sp, "components", "meta", "MetaEventTemplates.tsx"),
+    fs.readFileSync(path.join(TEMPLATES, "MetaEventTemplates.tsx"), "utf8"),
+  );
+}
+
+function finalNotes() {
+  console.log("");
+  console.log(c.b("Almost done — two manual steps:"));
+  console.log("");
+  console.log(`  1. Fill in your IDs/tokens in ${c.b(".env")} (see .env.example).`);
+  console.log(`  2. Mount the pixel in your root layout (inside <body>):`);
+  console.log(
+    c.d(
+      [
+        ``,
+        `     import { MetaPixel } from "${PKG}";`,
+        `     import { Suspense } from "react";`,
+        ``,
+        `     {process.env.NODE_ENV === "production" &&`,
+        `       process.env.NEXT_PUBLIC_META_PIXEL_ID && (`,
+        `         <Suspense><MetaPixel /></Suspense>`,
+        `     )}`,
+        ``,
+      ].join("\n"),
+    ),
+  );
+  console.log(c.d(`  MetaEventTemplates.tsx takes user/cart/products as props — wire them to your own store/auth where you render each component.`));
+  console.log("");
+  console.log(c.g("Tracking is wired up. 🎯"));
+}
+
+// ---- run ------------------------------------------------------------------
+if (cmd !== "init") {
+  console.log(`Unknown command "${cmd}". Usage: ${PKG} init [--dry-run] [--yes] [--no-install] [--pm <pm>]`);
+  process.exit(1);
+}
+
+console.log(c.b(`\n${PKG} → installing into ${path.basename(root)}\n`));
+if (DRY) warn("dry run — no files will be written\n");
+
+checkProject();
+const pm = detectPM();
+note(`package manager: ${pm}`);
+installPackage(pm);
+ensureEnv();
+patchNextConfig();
+scaffoldFiles();
+finalNotes();

package/package.json

@@ -1,13 +1,22 @@
 {
   "name": "@mitchdesigns/tracking",
-  "version": "1.2.4",
-  "description": "Tracking package for Next.js — Meta Pixel, Meta CAPI, and Google Tag Manager hooks and components",
+  "version": "1.3.0",
+  "description": "Meta Pixel + CAPI + GTM tracking for Next.js, with a one-command project installer.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ojja/titans-tracking.git"
+  },
   "license": "UNLICENSED",
-  "files": [
-    "src"
-  ],
   "main": "./src/index.ts",
   "types": "./src/index.ts",
+  "bin": {
+    "mitch-tracking": "bin/cli.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "templates"
+  ],
   "exports": {
     ".": {
       "types": "./src/index.ts",

package/templates/MetaEventTemplates.tsx

@@ -0,0 +1,247 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { useMetaTracking } from "@mitchdesigns/tracking";
+
+/**
+ * Drop-in tracking components.
+ *
+ * These are intentionally framework-agnostic: they take all data (user, cart,
+ * products) as props rather than reaching into a specific store or auth layer.
+ * Wire them to your own data source where you render them, e.g.:
+ *
+ *   const user = useCurrentUser();              // your auth
+ *   const cartItems = useCart();                // your store
+ *   <InitiateCheckoutTracking cartItems={cartItems} user={user} />
+ *
+ * `user` is optional — when provided it is forwarded to the CAPI for better
+ * match quality. `currency` defaults to "USD"; override per component or set a
+ * project-wide default below.
+ */
+
+const DEFAULT_CURRENCY = "USD";
+
+// Loose shapes — adapt to your domain models as needed.
+type AnyUser = Record<string, any> | null | undefined;
+
+type CartItem = {
+  id?: string | number;
+  product_id?: string | number;
+  sku?: string;
+  price: number;
+  quantity: number;
+  [key: string]: any;
+};
+
+type Product = {
+  id?: string | number;
+  sku?: string;
+  name?: string | { en?: string };
+  price?: number;
+  categories?: { name?: string }[];
+  [key: string]: any;
+};
+
+type OrderItem = {
+  id?: string | number;
+  product_id?: string | number;
+  price?: number;
+  total_amount?: number;
+  quantity?: number;
+  [key: string]: any;
+};
+
+const productName = (name: Product["name"]) =>
+  typeof name === "object" ? name?.en : name;
+
+const itemId = (item: { sku?: string; product_id?: string | number; id?: string | number }) =>
+  item.sku?.toString() || item.product_id?.toString() || item.id?.toString() || "unknown";
+
+/**
+ * Drop inside the product page provider/context.
+ * Fires ViewContent once per product — guarded against re-renders (e.g. after add to cart).
+ */
+export const ProductViewTracking = ({
+  product,
+  user,
+  currency = DEFAULT_CURRENCY,
+}: {
+  product: Product | null | undefined;
+  user?: AnyUser;
+  currency?: string;
+}) => {
+  const { trackViewContent } = useMetaTracking(user);
+  const trackedId = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!product) return;
+    const productId = product.sku || product.id?.toString();
+    if (!productId || trackedId.current === productId) return;
+    trackedId.current = productId;
+    trackViewContent({
+      content_ids: [productId],
+      content_name: productName(product.name),
+      content_category: product.categories?.[0]?.name,
+      value: product.price,
+      currency,
+    });
+  }, [product, user, currency, trackViewContent]);
+
+  return null;
+};
+
+/**
+ * Drop at the top of the checkout page.
+ * Fires InitiateCheckout once on mount.
+ */
+export const InitiateCheckoutTracking = ({
+  cartItems,
+  user,
+  currency = DEFAULT_CURRENCY,
+}: {
+  cartItems: CartItem[];
+  user?: AnyUser;
+  currency?: string;
+}) => {
+  const { trackInitiateCheckout } = useMetaTracking(user);
+
+  useEffect(() => {
+    if (!cartItems || cartItems.length === 0) return;
+    const total = cartItems.reduce((acc, item) => acc + item.price * item.quantity, 0);
+    trackInitiateCheckout({
+      content_ids: cartItems.map(itemId),
+      contents: cartItems.map((item) => ({
+        id: itemId(item),
+        quantity: item.quantity,
+        item_price: item.price,
+      })),
+      value: total,
+      currency,
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []); // only on mount
+
+  return null;
+};
+
+/**
+ * Drop inside the shop/category page controller.
+ * Fires ViewCategory when products load, and again if category or count changes.
+ */
+export const CategoryViewTracking = ({
+  products,
+  shoppingCategory,
+  categoryNameEn,
+  user,
+}: {
+  products: Product[] | undefined;
+  shoppingCategory?: string;
+  categoryNameEn?: string;
+  user?: AnyUser;
+}) => {
+  const { trackViewCategory } = useMetaTracking(user);
+  const lastTrackedCategory = useRef<string | null>(null);
+  const lastTrackedCount = useRef<number>(0);
+
+  useEffect(() => {
+    if (!products || products.length === 0) return;
+    const currentCount = products.length;
+    const normalizedCategory = shoppingCategory || null;
+    if (
+      lastTrackedCategory.current === normalizedCategory &&
+      lastTrackedCount.current === currentCount
+    ) return;
+    const currentIds = products.slice(0, 30).map((p) => p.sku || p.id?.toString() || "unknown");
+    trackViewCategory({
+      content_category: categoryNameEn || shoppingCategory || "unknown",
+      content_ids: currentIds,
+    });
+    lastTrackedCategory.current = normalizedCategory;
+    lastTrackedCount.current = currentCount;
+  }, [products, shoppingCategory, categoryNameEn, trackViewCategory]);
+
+  return null;
+};
+
+/**
+ * Drop on the thank-you / order confirmation page.
+ * Fires Purchase — uses orderNumber as the deduplication key.
+ */
+export const PurchaseTracking = ({
+  orderNumber,
+  items,
+  total,
+  user,
+  currency = DEFAULT_CURRENCY,
+}: {
+  orderNumber: string;
+  items: OrderItem[];
+  total: number;
+  user?: AnyUser;
+  currency?: string;
+}) => {
+  const { trackPurchase } = useMetaTracking(user);
+
+  useEffect(() => {
+    if (!items || items.length === 0) return;
+    trackPurchase({
+      content_ids: items.map(itemId),
+      contents: items.map((item) => {
+        const quantity = Number(item.quantity) || 1;
+        const itemPrice =
+          Number(item.price) ||
+          (item.total_amount ? Number(item.total_amount) / quantity : 0) ||
+          total / items.length ||
+          0;
+        return {
+          id: itemId(item),
+          quantity,
+          item_price: Number(itemPrice.toFixed(2)),
+        };
+      }),
+      value: Number(total.toFixed(2)),
+      currency,
+      numItems: items.reduce((acc, item) => acc + (Number(item.quantity) || 1), 0),
+      orderId: orderNumber,
+    });
+  }, [orderNumber, items, total, user, currency, trackPurchase]);
+
+  return null;
+};
+
+/**
+ * Drop inside the checkout stepper.
+ * Fires AddPaymentInfo when `activeStep` reaches `triggerStep` (default 2).
+ */
+export const AddPaymentInfoTracking = ({
+  activeStep,
+  cartItems,
+  user,
+  triggerStep = 2,
+  currency = DEFAULT_CURRENCY,
+}: {
+  activeStep: number;
+  cartItems: CartItem[];
+  user?: AnyUser;
+  triggerStep?: number;
+  currency?: string;
+}) => {
+  const { trackAddPaymentInfo } = useMetaTracking(user);
+
+  useEffect(() => {
+    if (activeStep !== triggerStep || !cartItems || cartItems.length === 0) return;
+    const total = cartItems.reduce((acc, item) => acc + item.price * item.quantity, 0);
+    trackAddPaymentInfo({
+      content_ids: cartItems.map(itemId),
+      contents: cartItems.map((item) => ({
+        id: itemId(item),
+        quantity: item.quantity,
+        item_price: item.price,
+      })),
+      value: total,
+      currency,
+    });
+  }, [activeStep, triggerStep, cartItems, user, currency, trackAddPaymentInfo]);
+
+  return null;
+};

package/templates/capi-route.ts

@@ -0,0 +1,2 @@
+export const runtime = "edge";
+export { POST } from "@mitchdesigns/tracking/server";

package/templates/env.example

@@ -0,0 +1,9 @@
+# --- @mitchdesigns/tracking ---
+# Meta Pixel + Conversions API
+NEXT_PUBLIC_META_PIXEL_ID=your_pixel_id
+META_ACCESS_TOKEN=your_capi_access_token
+# Remove before production:
+NEXT_PUBLIC_META_TEST_EVENT_CODE=TESTxxxxx
+
+# Google Tag Manager (optional)
+NEXT_PUBLIC_GTM_ID=GTM-XXXXXXX