keystone-design-bootstrap 1.0.68 → 1.0.70

package/src/tracking/PostHogProvider.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import posthog from 'posthog-js';
+import { PostHogProvider as PHProvider } from 'posthog-js/react';
+import { useEffect, Suspense } from 'react';
+import { usePathname, useSearchParams } from 'next/navigation';
+
+const DEFAULT_HOST = 'https://us.i.posthog.com';
+
+export type PostHogProviderProps = {
+  apiKey: string;
+  apiHost?: string;
+  /** Keystone account ID — attached to every event as a super property. */
+  accountId?: number;
+  /** Keystone account name (company_name) — attached to every event as a super property. */
+  accountName?: string;
+  children: React.ReactNode;
+};
+
+// ---------------------------------------------------------------------------
+// Page name resolution
+// ---------------------------------------------------------------------------
+
+type PageInfo = { page_name: string; page_slug?: string };
+
+function resolvePageInfo(pathname: string): PageInfo {
+  if (pathname === '/') return { page_name: 'home' };
+
+  const patterns: Array<[RegExp, (m: RegExpMatchArray) => PageInfo]> = [
+    [/^\/services\/(.+)$/, ([, slug]) => ({ page_name: 'service_detail', page_slug: slug })],
+    [/^\/locations\/(.+)$/, ([, slug]) => ({ page_name: 'location_detail', page_slug: slug })],
+    [/^\/blog\/(.+)$/, ([, slug]) => ({ page_name: 'blog_post', page_slug: slug })],
+    [/^\/jobs\/(.+)$/, ([, slug]) => ({ page_name: 'job_detail', page_slug: slug })],
+    [/^\/packages\/(.+)$/, ([, slug]) => ({ page_name: 'package_detail', page_slug: slug })],
+  ];
+
+  for (const [pattern, resolve] of patterns) {
+    const match = pathname.match(pattern);
+    if (match) return resolve(match);
+  }
+
+  const staticNames: Record<string, string> = {
+    '/services': 'services',
+    '/locations': 'locations',
+    '/contact': 'contact',
+    '/about': 'about',
+    '/blog': 'blog',
+    '/portal': 'portal',
+    '/gallery': 'gallery',
+    '/team': 'team',
+    '/faq': 'faq',
+    '/reviews': 'reviews',
+    '/jobs': 'jobs',
+    '/packages': 'packages',
+    '/service-menu': 'service_menu',
+    '/privacy-policy': 'privacy_policy',
+    '/terms': 'terms_of_service',
+  };
+
+  return { page_name: staticNames[pathname] ?? 'unknown' };
+}
+
+// ---------------------------------------------------------------------------
+// Pageview tracker — must be wrapped in <Suspense> (useSearchParams)
+// ---------------------------------------------------------------------------
+
+function PostHogPageviewTracker() {
+  const pathname = usePathname();
+  const searchParams = useSearchParams();
+
+  useEffect(() => {
+    if (!pathname) return;
+
+    const search = searchParams?.toString();
+    const url = window.location.origin + pathname + (search ? `?${search}` : '');
+    const { page_name, page_slug } = resolvePageInfo(pathname);
+
+    posthog.capture('$pageview', {
+      $current_url: url,
+      page_name,
+      page_path: pathname,
+      ...(page_slug && { page_slug }),
+    });
+  }, [pathname, searchParams]);
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialises PostHog, registers account-level super properties, and fires
+ * an enriched `$pageview` on every App Router navigation.
+ *
+ * Super properties attached to every event automatically:
+ *   - account_id    (Keystone account ID)
+ *   - account_name  (company_name)
+ *   - site_domain   (window.location.hostname)
+ *
+ * Mount once in the root layout body. One project key covers all customer
+ * sites — filter by account_name or site_domain in the PostHog dashboard.
+ */
+export function PostHogProvider({ apiKey, apiHost, accountId, accountName, children }: PostHogProviderProps) {
+  useEffect(() => {
+    posthog.init(apiKey, {
+      api_host: apiHost ?? DEFAULT_HOST,
+      person_profiles: 'identified_only',
+      capture_pageview: false,
+    });
+
+    posthog.register({
+      ...(accountId !== undefined && { account_id: accountId }),
+      ...(accountName && { account_name: accountName }),
+      site_domain: window.location.hostname,
+    });
+  }, [apiKey, apiHost, accountId, accountName]);
+
+  return (
+    <PHProvider client={posthog}>
+      <Suspense fallback={null}>
+        <PostHogPageviewTracker />
+      </Suspense>
+      {children}
+    </PHProvider>
+  );
+}

package/src/tracking/captureEvent.ts

@@ -0,0 +1,140 @@
+/**
+ * PostHog event capture — Keystone customer sites.
+ *
+ * ## Naming convention
+ * All events use snake_case `object_action` format.
+ * Properties use snake_case as well.
+ *
+ * ## Event taxonomy
+ * Add new events here: define the name in `KsEventName` and its required
+ * properties in `KsEventProperties`. Every callsite is then type-checked.
+ *
+ * ## Usage
+ *
+ *   import { captureEvent } from 'keystone-design-bootstrap/tracking';
+ *
+ *   captureEvent('form_submitted', { form_type: 'lead' });
+ *   captureEvent('booking_cta_clicked', { source_path: '/services/massage', booking_url: url });
+ *
+ * All calls are safe no-ops when PostHog has not been initialised (e.g. no
+ * POSTHOG_API_KEY configured on the server).
+ *
+ * ## Super properties
+ * account_id, account_name, and site_domain are registered as super properties
+ * by PostHogProvider and are automatically attached to every event — you do not
+ * need to include them in individual captureEvent calls.
+ */
+
+import posthog from 'posthog-js';
+
+// ---------------------------------------------------------------------------
+// Event taxonomy
+// ---------------------------------------------------------------------------
+
+export type KsEventName =
+  // Navigation
+  | 'page_viewed'
+  // Booking / conversion
+  | 'booking_cta_clicked'
+  // Forms
+  | 'form_submitted'
+  | 'form_failed'
+  // Chat widget
+  | 'chat_opened'
+  | 'chat_message_sent'
+  | 'chat_message_failed'
+  // Member portal — tab navigation
+  | 'portal_tab_viewed'
+  // Member portal — authentication flow
+  | 'portal_login_started'
+  | 'portal_login_identified'
+  | 'portal_login_completed'
+  | 'portal_login_failed';
+
+export type KsEventProperties = {
+  /** Fired on every page navigation. $pageview is also fired for PostHog web analytics. */
+  page_viewed: {
+    page_name: string;
+    page_path: string;
+    page_slug?: string;
+  };
+
+  /** Fired when a visitor clicks any CTA that links to the external booking URL. */
+  booking_cta_clicked: {
+    source_path: string;
+    booking_url: string;
+  };
+
+  /** Fired when a Keystone form is successfully submitted. */
+  form_submitted: {
+    /** One of: lead | job_application | marketing_list_signup */
+    form_type: string;
+    /** Server-generated event ID for CAPI deduplication (when present). */
+    event_id?: string;
+  };
+
+  /** Fired when a form submission fails (validation error or network error). */
+  form_failed: {
+    form_type: string;
+    error: string;
+  };
+
+  /** Fired when the chat widget is first opened by the visitor. */
+  chat_opened: Record<string, never>;
+
+  /** Fired when a chat message is successfully sent. */
+  chat_message_sent: {
+    /** Whether the visitor is authenticated (contactId present). */
+    is_authenticated: boolean;
+  };
+
+  /** Fired when a chat message fails to send. */
+  chat_message_failed: {
+    error: string;
+  };
+
+  /** Fired when a member portal tab is opened. */
+  portal_tab_viewed: {
+    tab: string;
+  };
+
+  /** Fired when the portal login modal is opened / login flow starts. */
+  portal_login_started: Record<string, never>;
+
+  /**
+   * Fired after the identifier step resolves — we know whether the user
+   * already has an account.
+   */
+  portal_login_identified: {
+    method: 'email' | 'phone' | 'email_and_phone';
+    user_exists: boolean;
+  };
+
+  /** Fired after the user successfully signs in or creates an account. */
+  portal_login_completed: {
+    flow: 'signin' | 'signup';
+  };
+
+  /** Fired when any step of the login flow returns an error. */
+  portal_login_failed: {
+    step: 'identifier' | 'signin' | 'signup';
+    reason: string;
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Capture helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Captures a typed Keystone analytics event via PostHog.
+ * Safe no-op when PostHog has not been initialised.
+ */
+export function captureEvent<E extends KsEventName>(
+  event: E,
+  ...args: KsEventProperties[E] extends Record<string, never>
+    ? []
+    : [properties: KsEventProperties[E]]
+): void {
+  posthog.capture(event, args[0] as Record<string, unknown>);
+}

package/src/tracking/index.ts

@@ -23,3 +23,8 @@ export type { MetaPixelProps } from './MetaPixel';
 export { MetaPixelTracker } from './MetaPixelTracker';
 export { firePixelEvent, setPixelUserData } from './firePixelEvent';
 export type { PixelEvent, PixelEventParams, PixelUserData } from './firePixelEvent';
+export { PostHogProvider } from './PostHogProvider';
+export type { PostHogProviderProps } from './PostHogProvider';
+export { KeystoneAnalyticsTracker } from './KeystoneAnalyticsTracker';
+export { captureEvent } from './captureEvent';
+export type { KsEventName, KsEventProperties } from './captureEvent';