@m13v/seo-components 0.38.5 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/seo-components",
-  "version": "0.38.5",
+  "version": "0.40.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/download-route.ts

@@ -0,0 +1,192 @@
+import { NextRequest } from "next/server";
+import { capturePostHogServer } from "./posthog-capture";
+
+/**
+ * Generic email-gated download redirect handler.
+ *
+ * Companion to `createNewsletterHandler`. The newsletter flow captures the
+ * email and emails the user a tokenized download link
+ * (e.g. `/api/download?token=<HMAC>`). This factory wires up the GET endpoint
+ * that link points at. It:
+ *
+ *   1. Reads the token from either the configured cookie or the `?token=`
+ *      query param.
+ *   2. Calls the caller's `verifyToken` (HMAC checks live in the consumer
+ *      because the signing secret is app-specific).
+ *   3. On invalid token: 302 to `gateRedirect` (defaults to
+ *      `/?gate=required&from=download`).
+ *   4. On valid token:
+ *        - resolves the download URL via `resolveDownloadUrl` (e.g. latest
+ *          GitHub release `.dmg` asset),
+ *        - fires a server-side PostHog event (default
+ *          `download_link_clicked_server`), ground-truth, ad-blocker proof,
+ *        - fires the optional `onClick` callback (DB insert lives here),
+ *        - 302s to the resolved URL.
+ *
+ * Bot UAs (LinkedIn / Slack / Twitter link unfurls) are detected and the
+ * PostHog event + onClick callback are suppressed for them so funnel stats
+ * stay clean. The 302 still fires so previews render.
+ */
+
+const BOT_UA_RE = /bot|crawler|spider|Twitterbot|LinkedInBot|Slackbot|facebookexternalhit|Discordbot|TelegramBot|WhatsApp|Applebot|Googlebot|Bingbot|YandexBot|DuckDuckBot|redditbot|Pinterest|Embedly|Snapchat|axios\/|python-requests|python-urllib|node-fetch|^node$|dataminr|Anthill|^Mozilla\/5\.0$|Chrome\/70\.|Nexus 5X Build\/MMB29P|AI-Innovation-Radar|^AFMMainUI|LinkResolver|link-resolver|^Mozilla\/5\.0 \(compatible\)$|^curl\//i;
+
+export interface DownloadHandlerOk {
+  ok: true;
+  email: string;
+}
+export interface DownloadHandlerFail {
+  ok: false;
+  reason: string;
+}
+export type DownloadHandlerVerifyResult = DownloadHandlerOk | DownloadHandlerFail;
+
+export interface DownloadHandlerClickInfo {
+  email: string;
+  version: string | null;
+  url: string;
+  userAgent: string;
+  referer: string;
+  ip: string | null;
+  country: string | null;
+  source: "cookie" | "query";
+  isBot: boolean;
+}
+
+export interface DownloadHandlerConfig {
+  /** Site slug, used as a PostHog property (e.g. "claude-meter"). */
+  site: string;
+  /** Cookie name to read the install token from. */
+  cookieName: string;
+  /**
+   * Verifies the token (HMAC or otherwise). Returns the captured email on
+   * success. The signing secret stays in the consumer app because it is
+   * app-specific.
+   */
+  verifyToken: (token: string | undefined | null) => DownloadHandlerVerifyResult;
+  /**
+   * Resolves the final destination URL (e.g. latest GitHub release .dmg).
+   * Called only when the token is valid, so misses cost nothing on bounces.
+   */
+  resolveDownloadUrl: () => Promise<{ url: string; version: string | null }>;
+  /**
+   * Builds the Set-Cookie header value to stamp the install token when the
+   * request arrived via `?token=` (so subsequent installs on the same browser
+   * skip the URL token). If omitted, no cookie is stamped on the query path.
+   */
+  buildTokenCookie?: (email: string) => string;
+  /**
+   * Where to bounce on missing / bad token. Defaults to
+   * `/?gate=required&from=download`. Relative so it works behind proxies
+   * where `req.url` resolves to the internal binding.
+   */
+  gateRedirect?: string;
+  /**
+   * Optional DB-logging hook fired AFTER the destination URL is resolved and
+   * the PostHog event is sent, but BEFORE the 302 response is returned.
+   * Errors are swallowed so a logging miss can't break the download path.
+   * Not called for bots.
+   */
+  onClick?: (info: DownloadHandlerClickInfo) => Promise<void> | void;
+  /** PostHog event name. Defaults to `download_link_clicked_server`. */
+  posthogEvent?: string;
+}
+
+export function createDownloadHandler(config: DownloadHandlerConfig) {
+  const {
+    site,
+    cookieName,
+    verifyToken,
+    resolveDownloadUrl,
+    buildTokenCookie,
+    gateRedirect = "/?gate=required&from=download",
+    onClick,
+    posthogEvent = "download_link_clicked_server",
+  } = config;
+
+  return async function GET(req: NextRequest): Promise<Response> {
+    const cookieToken = req.cookies.get(cookieName)?.value;
+    const queryToken = req.nextUrl.searchParams.get("token") ?? undefined;
+
+    let verdict = verifyToken(cookieToken);
+    let acceptedFrom: "cookie" | "query" | null = verdict.ok ? "cookie" : null;
+    if (!verdict.ok && queryToken) {
+      const queryVerdict = verifyToken(queryToken);
+      if (queryVerdict.ok) {
+        verdict = queryVerdict;
+        acceptedFrom = "query";
+      }
+    }
+
+    if (!verdict.ok) {
+      return new Response(null, {
+        status: 302,
+        headers: {
+          Location: gateRedirect,
+          "Cache-Control": "no-store, no-cache, must-revalidate, max-age=0",
+          "x-install-gate": verdict.reason ?? "missing",
+        },
+      });
+    }
+
+    const { url, version } = await resolveDownloadUrl();
+
+    const ua = req.headers.get("user-agent") || "";
+    const isBot = !ua || BOT_UA_RE.test(ua);
+    const referer = req.headers.get("referer") || "";
+    const xff = req.headers.get("x-forwarded-for") || "";
+    const ip = xff.split(",")[0]?.trim() || null;
+    const country = req.headers.get("x-vercel-ip-country") || req.headers.get("cf-ipcountry") || null;
+    const email = verdict.email;
+
+    if (!isBot) {
+      let host: string | undefined;
+      try {
+        host = req.headers.get("host") || undefined;
+      } catch {
+        host = undefined;
+      }
+      await capturePostHogServer({
+        event: posthogEvent,
+        distinctId: email,
+        host,
+        properties: {
+          email,
+          site,
+          version,
+          source: acceptedFrom,
+          referer,
+          country,
+        },
+      });
+
+      if (onClick) {
+        try {
+          await onClick({
+            email,
+            version,
+            url,
+            userAgent: ua,
+            referer,
+            ip,
+            country,
+            source: acceptedFrom ?? "cookie",
+            isBot,
+          });
+        } catch (err) {
+          console.error("[download-handler] onClick threw:", err);
+        }
+      }
+    }
+
+    const headers = new Headers({
+      Location: url,
+      "Cache-Control": "private, max-age=0, s-maxage=0",
+      "x-install-gate": "ok",
+      "x-install-gate-source": acceptedFrom ?? "unknown",
+    });
+    if (acceptedFrom === "query" && buildTokenCookie) {
+      headers.append("Set-Cookie", buildTokenCookie(email));
+    }
+    return new Response(null, { status: 302, headers });
+  };
+}

package/src/lib/newsletter-route.ts

@@ -255,17 +255,17 @@ 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.
+    //    Awaited (not `void`) so the fetch completes before the response is
+    //    returned. On Cloud Run / serverless runtimes the container can be
+    //    frozen the moment the response is sent, killing fire-and-forget
+    //    fetches. Adds ~50-150ms latency, worth it for reliable funnel data.
     let host: string | undefined;
     try {
       host = req.headers.get("host") || new URL(siteUrl).hostname;
     } catch {
       host = undefined;
     }
-    void capturePostHogServer({
+    await capturePostHogServer({
       event: "newsletter_subscribed_server",
       distinctId: email,
       host,

package/src/lib/resend-inbound-route.ts

@@ -1,4 +1,5 @@
 import { NextRequest } from "next/server";
+import { capturePostHogServer } from "./posthog-capture";
 
 /* ------------------------------------------------------------------ */
 /*  Resend Inbound webhook handler                                     */
@@ -103,6 +104,26 @@ export interface ResendInboundConfig {
     resendId: string;
     timestamp: string;
   }) => Promise<void>;
+  /**
+   * Optional: fire server-side PostHog events for delivery lifecycle
+   * (`email_sent_server`, `email_delivered_server`, `email_opened_server`,
+   * `email_clicked_server`, `email_bounced_server`, `email_complained_server`,
+   * `email_delayed_server`). When set, the webhook receives ALL delivery
+   * events for the connected Resend workspace, so use `fromDomainFilter` to
+   * scope to this site only.
+   */
+  posthog?: {
+    /** Site slug attached to the PostHog event (e.g. "claude-meter"). */
+    site: string;
+    /**
+     * Only fire PostHog events when the email's `from` address ends in this
+     * domain (e.g. "claude-meter.com"). Critical because Resend webhooks are
+     * registered at workspace level: every delivery event for every domain
+     * in the account hits every webhook. Without this filter, claude-meter's
+     * PostHog gets polluted by fazm / mediar / vipassana delivery events.
+     */
+    fromDomainFilter: string;
+  };
   /**
    * Skip forwarding (only persist + return 200). Useful for tests, or for
    * sites where the DB log is the only consumer.
@@ -145,6 +166,7 @@ export function createResendInboundHandler(config: ResendInboundConfig) {
     apiKeyEnv = "RESEND_API_KEY",
     onInbound,
     onDeliveryEvent,
+    posthog,
     skipForward = false,
     ignoredSenders = DEFAULT_IGNORED_SENDERS,
     ignoredSubjects = DEFAULT_IGNORED_SUBJECTS,
@@ -220,18 +242,55 @@ export function createResendInboundHandler(config: ResendInboundConfig) {
     }
   }
 
-  async function handleDelivery(payload: ResendInboundPayload) {
+  async function handleDelivery(payload: ResendInboundPayload, host?: string) {
     const status = DELIVERY_STATUS_MAP[payload.type];
-    if (!status || !onDeliveryEvent) return;
-    try {
-      await onDeliveryEvent({
-        type: payload.type,
-        status,
-        resendId: payload.data.email_id,
-        timestamp: payload.created_at,
+    if (!status) return;
+
+    if (onDeliveryEvent) {
+      try {
+        await onDeliveryEvent({
+          type: payload.type,
+          status,
+          resendId: payload.data.email_id,
+          timestamp: payload.created_at,
+        });
+      } catch (err) {
+        console.error(`${tag} onDeliveryEvent error`, err);
+      }
+    }
+
+    // Optional PostHog fire — only when configured AND the email originated
+    // from our domain (Resend webhooks are workspace-level, so filtering is
+    // mandatory to avoid cross-site pollution).
+    if (posthog) {
+      const fromAddr = parseEmail(payload.data.from || "");
+      const matchesDomain = fromAddr.endsWith(`@${posthog.fromDomainFilter.toLowerCase()}`);
+      if (!matchesDomain) {
+        console.log(
+          `${tag} posthog skip, from domain mismatch:`,
+          fromAddr,
+          "expected:",
+          posthog.fromDomainFilter,
+        );
+        return;
+      }
+      const recipient = payload.data.to?.[0]?.toLowerCase() || payload.data.email_id;
+      await capturePostHogServer({
+        event: `email_${status}_server`,
+        distinctId: recipient,
+        host,
+        properties: {
+          email: recipient,
+          site: posthog.site,
+          resend_email_id: payload.data.email_id,
+          type: payload.type,
+          status,
+          subject: payload.data.subject || null,
+          from: fromAddr,
+          timestamp: payload.created_at,
+          component: "createResendInboundHandler",
+        },
       });
-    } catch (err) {
-      console.error(`${tag} onDeliveryEvent error`, err);
     }
   }
 
@@ -257,11 +316,18 @@ export function createResendInboundHandler(config: ResendInboundConfig) {
 
     console.log(`${tag}`, payload.type, payload.data?.email_id);
 
+    let host: string | undefined;
+    try {
+      host = req.headers.get("host") || undefined;
+    } catch {
+      host = undefined;
+    }
+
     try {
       if (payload.type === "email.received") {
         await handleInbound(payload, apiKey);
       } else if (DELIVERY_STATUS_MAP[payload.type]) {
-        await handleDelivery(payload);
+        await handleDelivery(payload, host);
       }
     } catch (err) {
       console.error(`${tag} handler error`, err);

package/src/server.ts

@@ -48,6 +48,13 @@ export type { BookCallRedirectConfig } from "./lib/book-call-redirect";
 export { createDmShortLinkRedirectHandler } from "./lib/dm-short-link-redirect";
 export type { DmShortLinkRedirectConfig } from "./lib/dm-short-link-redirect";
 
+export { createDownloadHandler } from "./lib/download-route";
+export type {
+  DownloadHandlerConfig,
+  DownloadHandlerVerifyResult,
+  DownloadHandlerClickInfo,
+} from "./lib/download-route";
+
 export { createResendInboundHandler } from "./lib/resend-inbound-route";
 export type {
   ResendInboundConfig,