From 626d148a8c76b93c9188f25449d213eb4ce5c70b Mon Sep 17 00:00:00 2001
From: ZVN DEV <78920650+zvndev@users.noreply.github.com>
Date: Fri, 2 Oct 2026 01:22:30 -0400
Subject: [PATCH] Add Little Friend analytics to whenny.dev

Production deployments render the Little Friend tag (journey mode, with
session replay) in the root layout. Previews and local dev render
nothing, because the tag depends on VERCEL_ENV being production.

- install.copy fires after an install command is copied (home page
  command blocks, CLI lines, module chips, and the docs installation
  section and code blocks), with method create, cli or package. The
  command text is never sent.
- github.click and npm.click for links to GitHub and npm.
- data-lf click ids on the home nav, calls to action and footer.
- CSP: script-src adds https://cdn.littlefriend.io, and a connect-src of
  'self' https://in.littlefriend.io replaces the default-src fallback.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 apps/example/app/docs/page.tsx     |  4 ++++
 apps/example/app/layout.tsx        | 18 ++++++++++++++++
 apps/example/app/little-friend.tsx | 26 +++++++++++++++++++++++
 apps/example/app/page.tsx          | 16 ++++++++------
 apps/example/lib/little-friend.ts  | 34 ++++++++++++++++++++++++++++++
 apps/example/next.config.js        |  2 +-
 6 files changed, 93 insertions(+), 7 deletions(-)
 create mode 100644 apps/example/app/little-friend.tsx
 create mode 100644 apps/example/lib/little-friend.ts

diff --git a/apps/example/app/docs/page.tsx b/apps/example/app/docs/page.tsx
index 57d832f..00e829e 100644
--- a/apps/example/app/docs/page.tsx
+++ b/apps/example/app/docs/page.tsx
@@ -2,6 +2,7 @@
 
 import Link from 'next/link'
 import { useState } from 'react'
+import { trackCopy } from '@/lib/little-friend'
 
 type Section = 'installation' | 'upgrading' | 'quickstart' | 'core' | 'formatting' | 'relative' | 'smart' | 'compare' | 'duration' | 'timezone' | 'calendar' | 'natural' | 'react' | 'config' | 'cli'
 
@@ -11,6 +12,7 @@ function CodeBlock({ children, title }: { children: string; title?: string }) {
 
   const copyToClipboard = async () => {
     await navigator.clipboard.writeText(children)
+    trackCopy(children)
     setCopied(true)
     setTimeout(() => setCopied(false), 2000)
   }
@@ -246,6 +248,7 @@ function InstallationSection() {
 
   const copyCommand = async () => {
     await navigator.clipboard.writeText(addCommand)
+    trackCopy(addCommand)
     setCopied(true)
     setTimeout(() => setCopied(false), 2000)
   }
@@ -264,6 +267,7 @@ function InstallationSection() {
           <button
             onClick={async () => {
               await navigator.clipboard.writeText('npx whenny init')
+              trackCopy('npx whenny init')
               setCopied(true)
               setTimeout(() => setCopied(false), 2000)
             }}
diff --git a/apps/example/app/layout.tsx b/apps/example/app/layout.tsx
index fc61d4c..2536bc5 100644
--- a/apps/example/app/layout.tsx
+++ b/apps/example/app/layout.tsx
@@ -1,4 +1,6 @@
 import type { Metadata } from 'next'
+import { LITTLE_FRIEND_ENABLED, LITTLE_FRIEND_SITE_KEY } from '@/lib/little-friend'
+import LittleFriendEvents from './little-friend'
 import './globals.css'
 
 const title = 'Whenny - The Modern TypeScript Date Library for the AI Era'
@@ -124,8 +126,24 @@ export default function RootLayout({
           type="application/ld+json"
           dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
         />
+        {LITTLE_FRIEND_ENABLED && (
+          <>
+            <script
+              defer
+              src="https://cdn.littlefriend.io/lf.js"
+              data-site={LITTLE_FRIEND_SITE_KEY}
+              data-mode="journey"
+            />
+            <script
+              defer
+              src="https://cdn.littlefriend.io/lf-replay.js"
+              data-site={LITTLE_FRIEND_SITE_KEY}
+            />
+          </>
+        )}
       </head>
       <body className="font-sans">
+        {LITTLE_FRIEND_ENABLED && <LittleFriendEvents />}
         <a
           href="#main-content"
           className="sr-only focus:not-sr-only focus:fixed focus:top-4 focus:left-4 focus:z-50 focus:px-4 focus:py-2 focus:bg-slate-900 focus:text-white focus:rounded-lg focus:text-sm focus:font-medium focus:outline-none focus:ring-2 focus:ring-slate-400 focus:ring-offset-2"
diff --git a/apps/example/app/little-friend.tsx b/apps/example/app/little-friend.tsx
new file mode 100644
index 0000000..a5362b0
--- /dev/null
+++ b/apps/example/app/little-friend.tsx
@@ -0,0 +1,26 @@
+'use client'
+
+import { useEffect } from 'react'
+import { track } from '@/lib/little-friend'
+
+// Goals match event names, so GitHub and npm links send their own.
+function onClick(event: MouseEvent) {
+  if (event.button > 1 || !(event.target instanceof Element)) return
+  const link = event.target.closest('a[href]')
+  if (!(link instanceof HTMLAnchorElement)) return
+  const host = link.hostname.replace(/^www\./, '')
+  if (host === 'github.com') track('github.click')
+  else if (host === 'npmjs.com') track('npm.click')
+}
+
+export default function LittleFriendEvents() {
+  useEffect(() => {
+    document.addEventListener('click', onClick)
+    document.addEventListener('auxclick', onClick)
+    return () => {
+      document.removeEventListener('click', onClick)
+      document.removeEventListener('auxclick', onClick)
+    }
+  }, [])
+  return null
+}
diff --git a/apps/example/app/page.tsx b/apps/example/app/page.tsx
index f8cd79c..7848e2a 100644
--- a/apps/example/app/page.tsx
+++ b/apps/example/app/page.tsx
@@ -4,6 +4,7 @@ import Link from 'next/link'
 import { useState, useEffect } from 'react'
 import { whenny } from 'whenny'
 import { useRelativeTime } from 'whenny-react'
+import { trackCopy } from '@/lib/little-friend'
 
 // Fade-in animation wrapper
 function FadeIn({ children, delay = 0 }: { children: React.ReactNode; delay?: number }) {
@@ -56,6 +57,7 @@ function CommandBlock({ command, variant = 'dark' }: { command: string; variant?
 
   const handleCopy = async () => {
     await navigator.clipboard.writeText(command)
+    trackCopy(command)
     setCopied(true)
     setTimeout(() => setCopied(false), 2000)
   }
@@ -99,10 +101,10 @@ export default function HomePage() {
         <div className="max-w-5xl mx-auto px-4 sm:px-6 py-3 sm:py-4 flex items-center justify-between">
           <Link href="/" className="font-semibold text-slate-900">Whenny</Link>
           <div className="flex items-center gap-3 sm:gap-6">
-            <Link href="/demo" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900 transition-colors">Demo</Link>
-            <Link href="/docs" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900 transition-colors">Docs</Link>
+            <Link href="/demo" data-lf="nav.demo" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900 transition-colors">Demo</Link>
+            <Link href="/docs" data-lf="nav.docs" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900 transition-colors">Docs</Link>
             <Link href="/blog" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900 transition-colors">Blog</Link>
-            <a href="https://github.com/ZVN-DEV/whenny" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900 transition-colors">GitHub</a>
+            <a href="https://github.com/ZVN-DEV/whenny" data-lf="nav.github" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900 transition-colors">GitHub</a>
           </div>
         </div>
       </header>
@@ -396,10 +398,10 @@ whenny(event.date).smart()
             <h2 className="text-xl sm:text-2xl font-bold text-slate-900 mb-3 sm:mb-4">Ready to simplify dates?</h2>
             <p className="text-sm sm:text-base text-slate-600 mb-6 sm:mb-8">Start with the CLI or install the package. Your choice.</p>
             <div className="flex flex-col sm:flex-row gap-3 justify-center">
-              <Link href="/docs" className="px-5 sm:px-6 py-2.5 sm:py-3 bg-slate-900 text-white rounded-lg font-medium hover:bg-slate-800 transition-colors text-sm sm:text-base">
+              <Link href="/docs" data-lf="cta.docs" className="px-5 sm:px-6 py-2.5 sm:py-3 bg-slate-900 text-white rounded-lg font-medium hover:bg-slate-800 transition-colors text-sm sm:text-base">
                 Read the Docs
               </Link>
-              <Link href="/demo" className="px-5 sm:px-6 py-2.5 sm:py-3 bg-white text-slate-900 border border-slate-200 rounded-lg font-medium hover:bg-slate-50 transition-colors text-sm sm:text-base">
+              <Link href="/demo" data-lf="cta.demo" className="px-5 sm:px-6 py-2.5 sm:py-3 bg-white text-slate-900 border border-slate-200 rounded-lg font-medium hover:bg-slate-50 transition-colors text-sm sm:text-base">
                 Try the Demo
               </Link>
             </div>
@@ -414,7 +416,7 @@ whenny(event.date).smart()
           <div className="flex items-center gap-4 sm:gap-6">
             <Link href="/docs" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900">Docs</Link>
             <Link href="/demo" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900">Demo</Link>
-            <a href="https://github.com/ZVN-DEV/whenny" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900">GitHub</a>
+            <a href="https://github.com/ZVN-DEV/whenny" data-lf="footer.github" className="text-xs sm:text-sm text-slate-600 hover:text-slate-900">GitHub</a>
           </div>
         </div>
       </footer>
@@ -471,6 +473,7 @@ function ModuleChip({ name }: { name: string }) {
 
   const handleCopy = async () => {
     await navigator.clipboard.writeText(command)
+    trackCopy(command)
     setCopied(true)
     setTimeout(() => setCopied(false), 2000)
   }
@@ -497,6 +500,7 @@ function CopyableLine({ command }: { command: string }) {
 
   const handleCopy = async () => {
     await navigator.clipboard.writeText(command)
+    trackCopy(command)
     setCopied(true)
     setTimeout(() => setCopied(false), 2000)
   }
diff --git a/apps/example/lib/little-friend.ts b/apps/example/lib/little-friend.ts
new file mode 100644
index 0000000..a0ad56d
--- /dev/null
+++ b/apps/example/lib/little-friend.ts
@@ -0,0 +1,34 @@
+// Little Friend analytics (littlefriend.io). The site key is public: it only
+// names the project the tracker reports to. The tracker sets no cookies, reads
+// no form values or page text, and strips query strings.
+
+export const LITTLE_FRIEND_SITE_KEY = 'lf_om3kqCX76KvI2c9G0Yt5UMoc'
+
+// Production deployments only, so previews and local dev send nothing.
+export const LITTLE_FRIEND_ENABLED = process.env.VERCEL_ENV === 'production'
+
+type LittleFriendProps = Record<string, string | number | boolean>
+
+declare global {
+  interface Window {
+    lf?: (command: string, ...args: unknown[]) => void
+  }
+}
+
+// A named event. Does nothing until the tracker has loaded, and nothing at
+// all outside production, where the tag is not rendered.
+export function track(name: string, props?: LittleFriendProps) {
+  if (typeof window === 'undefined') return
+  window.lf?.('track', name, props)
+}
+
+// After a copy: install commands send install.copy with how they install.
+// The command text itself is never sent.
+export function trackCopy(text: string) {
+  const command = text.trim()
+  if (command.startsWith('npx create-whenny')) track('install.copy', { method: 'create' })
+  else if (command.startsWith('npx whenny')) track('install.copy', { method: 'cli' })
+  else if (/^(npm install|npm i|pnpm add|yarn add|bun add) /.test(command)) {
+    track('install.copy', { method: 'package' })
+  }
+}
diff --git a/apps/example/next.config.js b/apps/example/next.config.js
index 09f500c..b71c127 100644
--- a/apps/example/next.config.js
+++ b/apps/example/next.config.js
@@ -8,7 +8,7 @@ const nextConfig = {
         headers: [
           {
             key: 'Content-Security-Policy',
-            value: "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; base-uri 'self'; form-action 'self'; frame-ancestors 'none';",
+            value: "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.littlefriend.io; connect-src 'self' https://in.littlefriend.io; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; base-uri 'self'; form-action 'self'; frame-ancestors 'none';",
           },
           {
             key: 'Strict-Transport-Security',