@m13v/seo-components 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/seo-components",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "scripts": {
     "build:css": "tailwind -i src/_build.css -o dist/styles.css --minify",
     "lint:mobile-spans": "node scripts/lint-mobile-spans.mjs",

package/src/lib/newsletter-route.ts

@@ -1,4 +1,5 @@
 import { NextRequest } from "next/server";
+import { capturePostHogServer } from "./posthog-capture";
 
 /* ------------------------------------------------------------------ */
 /*  Default welcome email template (light theme, teal brand)           */
@@ -116,12 +117,24 @@ export interface NewsletterConfig {
    * Receives the subscriber email and should return an HTML string.
    */
   welcomeHtml?: (email: string) => string;
+  /**
+   * Optional plain-text MIME part for the welcome email. Useful when the
+   * email body contains commands or URLs that whitespace-collapse when
+   * Resend auto-extracts text from HTML (claude-meter, assrt, etc.).
+   */
+  welcomeText?: (email: string) => string;
   /**
    * Optional: log the signup to a database.
    * Called after the email is sent successfully.
    * Receives the subscriber email and the Resend email ID.
    */
   onSignup?: (email: string, resendEmailId: string | null) => Promise<void>;
+  /**
+   * Short slug identifying the site (e.g. "fazm", "mediar", "claude-meter").
+   * Attached to the server-side PostHog `newsletter_subscribed_server` event
+   * so the dashboard can bucket signups by site even if `$host` is blocked.
+   */
+  site?: string;
 }
 
 
@@ -139,7 +152,9 @@ export function createNewsletterHandler(config: NewsletterConfig) {
     apiKeyEnv = "RESEND_API_KEY",
     welcomeSubject,
     welcomeHtml,
+    welcomeText,
     onSignup,
+    site,
   } = config;
 
   return async function POST(req: NextRequest) {
@@ -204,6 +219,8 @@ export function createNewsletterHandler(config: NewsletterConfig) {
 
     let resendEmailId: string | null = null;
 
+    const text = welcomeText ? welcomeText(email) : undefined;
+
     const emailRes = await fetch("https://api.resend.com/emails", {
       method: "POST",
       headers: {
@@ -215,6 +232,7 @@ export function createNewsletterHandler(config: NewsletterConfig) {
         to: email,
         subject,
         html,
+        ...(text ? { text } : {}),
       }),
     });
 
@@ -236,6 +254,30 @@ export function createNewsletterHandler(config: NewsletterConfig) {
       }
     }
 
+    // 4. Server-side PostHog capture (ground truth, not ad-blocked).
+    //    Fires once per successful signup. The dashboard's funnel_per_day.py
+    //    counts `newsletter_subscribed_server` for the "Email Signups" column.
+    //    Distinct from the client-side `newsletter_subscribed` event so we
+    //    don't double-count when both fire.
+    let host: string | undefined;
+    try {
+      host = req.headers.get("host") || new URL(siteUrl).hostname;
+    } catch {
+      host = undefined;
+    }
+    void capturePostHogServer({
+      event: "newsletter_subscribed_server",
+      distinctId: email,
+      host,
+      properties: {
+        email,
+        site: site || brand.toLowerCase(),
+        brand,
+        resend_email_id: resendEmailId,
+        component: "createNewsletterHandler",
+      },
+    });
+
     return new Response(
       JSON.stringify({ success: true }),
       { status: 200, headers: { "content-type": "application/json" } },

package/src/lib/posthog-capture.ts

@@ -0,0 +1,100 @@
+// Server-side PostHog capture helper.
+//
+// PostHog's client-side `posthog.capture()` is killed by ad-blockers (uBlock,
+// Brave shields, Privacy Badger), DNT, and any privacy extension that drops
+// the /e/ ingest call. That makes any client-only metric (newsletter signups,
+// download clicks, schedule clicks) lossy by 30 to 50 percent against the
+// real server-truth count.
+//
+// Use this helper from API routes that already have server-side ground truth
+// (a Resend send succeeded, a Cal.com webhook fired, a paid checkout closed)
+// to fire a parallel PostHog event from the server. Server captures land on
+// the same `events` table, so the dashboard's existing HogQL queries pick
+// them up the moment the event clause is updated.
+//
+// Convention: name server events with a `_server` suffix so they never
+// collide with the client event of the same intent. The dashboard chooses
+// which one to count; both can coexist for transition windows.
+
+interface CaptureOptions {
+  /** Event name. Convention: suffix with `_server` (e.g. "newsletter_subscribed_server"). */
+  event: string;
+  /**
+   * Stable identifier for the user. For email-gated flows this is the
+   * lowercased email so PostHog stitches with the client-side identify(email)
+   * that fires once the welcome email click drops them back on the site.
+   */
+  distinctId: string;
+  /**
+   * Event properties. The helper auto-merges `$host` (so the dashboard's
+   * `properties.$host IN (...)` domain filter matches) and a few standard
+   * keys, but anything in here wins over the auto-merged values.
+   */
+  properties?: Record<string, unknown>;
+  /**
+   * Hostname of the request. Pass `req.headers.get("host")` from a Next.js
+   * Route Handler. Used to populate `$host` so events bucket by domain in
+   * the dashboard. Falls back to a config default if omitted.
+   */
+  host?: string;
+  /**
+   * PostHog write key. Defaults to `process.env.NEXT_PUBLIC_POSTHOG_KEY`,
+   * then `process.env.POSTHOG_KEY`. The "public" key is the project's ingest
+   * key; it's safe to use server-side because it's already shipped to every
+   * browser.
+   */
+  apiKey?: string;
+  /**
+   * PostHog ingest host. Defaults to `process.env.NEXT_PUBLIC_POSTHOG_HOST`,
+   * then https://us.i.posthog.com.
+   */
+  apiHost?: string;
+}
+
+/**
+ * Fire a server-side PostHog capture. Never throws; logs and returns false
+ * on any failure so a tracking miss can't take down the calling route.
+ *
+ * Returns true on a 2xx ingest response, false otherwise.
+ */
+export async function capturePostHogServer(opts: CaptureOptions): Promise<boolean> {
+  const apiKey = opts.apiKey || process.env.NEXT_PUBLIC_POSTHOG_KEY || process.env.POSTHOG_KEY;
+  if (!apiKey) {
+    console.warn("[posthog-server] no PostHog key in env; skipping", opts.event);
+    return false;
+  }
+  const apiHost =
+    opts.apiHost || process.env.NEXT_PUBLIC_POSTHOG_HOST || "https://us.i.posthog.com";
+
+  const properties: Record<string, unknown> = {
+    ...(opts.host ? { $host: opts.host } : {}),
+    source: "server",
+    ...(opts.properties || {}),
+  };
+
+  try {
+    const res = await fetch(`${apiHost.replace(/\/$/, "")}/i/v0/e/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        api_key: apiKey,
+        event: opts.event,
+        distinct_id: opts.distinctId,
+        properties,
+        timestamp: new Date().toISOString(),
+      }),
+    });
+    if (!res.ok) {
+      const detail = await res.text().catch(() => "");
+      console.warn(
+        `[posthog-server] capture ${opts.event} returned ${res.status}:`,
+        detail.slice(0, 200),
+      );
+      return false;
+    }
+    return true;
+  } catch (err) {
+    console.warn(`[posthog-server] capture ${opts.event} threw:`, err);
+    return false;
+  }
+}

package/src/server.ts

@@ -37,6 +37,8 @@ export { getSupabaseAdmin } from "./lib/supabase-admin";
 export { createNewsletterHandler } from "./lib/newsletter-route";
 export type { NewsletterConfig } from "./lib/newsletter-route";
 
+export { capturePostHogServer } from "./lib/posthog-capture";
+
 export { createBookCallHandler } from "./lib/book-call-route";
 export type { BookCallConfig } from "./lib/book-call-route";