@m13v/seo-components 0.32.2 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m13v/seo-components",
-  "version": "0.32.2",
+  "version": "0.34.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/components/InstallEmailGate.tsx

@@ -69,9 +69,22 @@ export interface InstallEmailGateProps {
   newsletterPath?: string;
   /** Render a custom trigger element instead of the default button. Receives an onClick handler. */
   renderTrigger?: (props: { onClick: () => void; disabled?: boolean }) => React.ReactNode;
+  /**
+   * Email-only delivery mode. When true, the command is NEVER revealed in the
+   * modal; instead, after a successful email submit the user sees a
+   * "Check your inbox" success state. The newsletter route is responsible for
+   * sending the install command via email. Forces a re-submit on every click
+   * (no localStorage skip) so each click drives a fresh send and a clean
+   * `newsletter_subscribed` + `get_started_click` signal.
+   */
+  emailOnly?: boolean;
+  /** Stage 2 (sent) heading when emailOnly is true. */
+  sentTitle?: string;
+  /** Stage 2 (sent) body copy when emailOnly is true. Receives the submitted email. */
+  sentDescription?: (email: string) => React.ReactNode;
 }
 
-type Stage = "closed" | "email" | "command";
+type Stage = "closed" | "email" | "command" | "sent";
 
 export function InstallEmailGate({
   command,
@@ -92,10 +105,14 @@ export function InstallEmailGate({
   storageKey = DEFAULT_STORAGE_KEY,
   newsletterPath = "/api/newsletter",
   renderTrigger,
+  emailOnly = false,
+  sentTitle = "Check your inbox",
+  sentDescription,
 }: InstallEmailGateProps) {
   const capture = useCapture();
   const [stage, setStage] = useState<Stage>("closed");
   const [email, setEmail] = useState("");
+  const [submittedEmail, setSubmittedEmail] = useState("");
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState("");
   const [copied, setCopied] = useState<"command" | "config" | null>(null);
@@ -119,7 +136,10 @@ export function InstallEmailGate({
   }, [stage]);
 
   const onOpen = () => {
-    const skip = remember && hasCapturedInstallEmail(storageKey);
+    // emailOnly mode: never skip via localStorage, never reveal the command.
+    // Every click goes through the email form so the user gets a fresh email
+    // and the funnel records a fresh signal.
+    const skip = !emailOnly && remember && hasCapturedInstallEmail(storageKey);
     if (skip) {
       // Gate already passed previously: fire the canonical funnel event for
       // the gated-passed click. No event when the gate is fresh and we're
@@ -168,20 +188,23 @@ export function InstallEmailGate({
         site,
         section,
         source: "install_gate",
+        delivery: emailOnly ? "email_only" : "page_reveal",
       });
       trackGetStartedClick({
-        destination: "modal:command",
+        destination: emailOnly ? "email:install" : "modal:command",
         site,
         section,
         text: "email-submitted",
         component: "InstallEmailGate",
-        extra: { email: trimmed },
+        extra: { email: trimmed, delivery: emailOnly ? "email_only" : "page_reveal" },
       });
-      setStage("command");
+      setSubmittedEmail(trimmed);
+      setStage(emailOnly ? "sent" : "command");
     } catch (err) {
       console.warn("[InstallEmailGate] newsletter POST network error", err);
       if (remember) markInstallEmailCaptured(trimmed, storageKey);
-      setStage("command");
+      setSubmittedEmail(trimmed);
+      setStage(emailOnly ? "sent" : "command");
     } finally {
       setSubmitting(false);
     }
@@ -291,11 +314,72 @@ export function InstallEmailGate({
                     </button>
                   </form>
                   <p className="mt-4 text-xs text-zinc-500">
-                    Already subscribed? Submit anyway, the command unlocks either way.
+                    {emailOnly
+                      ? "Already subscribed? Submit anyway, we'll resend the install link."
+                      : "Already subscribed? Submit anyway, the command unlocks either way."}
                   </p>
                 </div>
               )}
 
+              {stage === "sent" && (
+                <div className="p-7">
+                  <div className="mb-5 flex items-start justify-between gap-4">
+                    <div>
+                      <div className="mb-3 inline-flex h-10 w-10 items-center justify-center rounded-full bg-teal-50 text-teal-600">
+                        <svg
+                          className="h-5 w-5"
+                          fill="none"
+                          viewBox="0 0 24 24"
+                          stroke="currentColor"
+                          strokeWidth={2}
+                          aria-hidden="true"
+                        >
+                          <path strokeLinecap="round" strokeLinejoin="round" d="M3 8l7.5 5.25a3 3 0 003 0L21 8M5 19h14a2 2 0 002-2V7a2 2 0 00-2-2H5a2 2 0 00-2 2v10a2 2 0 002 2z" />
+                        </svg>
+                      </div>
+                      <h2 className="text-xl font-semibold tracking-tight text-zinc-900">
+                        {sentTitle}
+                      </h2>
+                      <p className="mt-1 text-sm leading-relaxed text-zinc-600">
+                        {sentDescription
+                          ? sentDescription(submittedEmail)
+                          : (
+                            <>
+                              Sent the install command to{" "}
+                              <span className="font-medium text-zinc-900">{submittedEmail}</span>.
+                              It usually arrives in under a minute. If you don&apos;t see it, check
+                              spam or promotions.
+                            </>
+                          )}
+                      </p>
+                    </div>
+                    <CloseButton onClick={() => setStage("closed")} />
+                  </div>
+
+                  <div className="mt-5 flex items-center justify-between gap-3">
+                    {githubUrl ? (
+                      <a
+                        href={githubUrl}
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="text-sm font-medium text-teal-700 hover:text-teal-800"
+                      >
+                        View on GitHub →
+                      </a>
+                    ) : (
+                      <span />
+                    )}
+                    <button
+                      type="button"
+                      onClick={() => setStage("closed")}
+                      className="rounded-md border border-zinc-300 bg-white px-4 py-2 text-sm font-medium text-zinc-900 hover:bg-zinc-50"
+                    >
+                      Done
+                    </button>
+                  </div>
+                </div>
+              )}
+
               {stage === "command" && (
                 <div className="p-7">
                   <div className="mb-5 flex items-start justify-between gap-4">

package/src/lib/dm-short-link-redirect.ts

@@ -19,18 +19,27 @@ export interface DmShortLinkRedirectConfig {
 /**
  * Factory for `GET /r/[code]`.
  *
- * Each per-DM short link maps to a Cal.com / Calendly URL with full UTM and
- * `metadata[utm_*]` so cal_bookings closes the loop on which DM produced the
- * booking. The cached `target_url` is frozen at mint time on the dms row, so
- * the resolver is a single DB read with no config.json dependency.
+ * Each short link maps to a destination URL. Two rails are supported:
+ *
+ *   DM rail: code is minted from dm_links. Target is a Cal.com / Calendly URL
+ *   with full UTM and metadata[utm_*] so cal_bookings closes the loop on which
+ *   DM produced the booking. Fires `dm_short_link_clicked` in PostHog.
+ *
+ *   Post rail: code is minted from post_links (public posts/comments). Target
+ *   is typically the product homepage or a landing page. UTM params are injected
+ *   at redirect time (utm_source, utm_medium, utm_campaign, utm_content) so
+ *   PostHog can stitch the full funnel: post click -> get_started_click ->
+ *   schedule_click -> checkout_success. Fires `post_short_link_clicked` in
+ *   PostHog.
  *
  * Behavior:
  *   1. Read `code` from the route param. Reject non-alphanumeric / wrong-length.
- *   2. Hit `<resolverBase>/api/short-links/<code>`. The resolver increments
- *      dms.short_link_clicks and stamps first/last click timestamps.
- *   3. Fire a PostHog `dm_short_link_clicked` event with dm_id, project,
- *      platform, code, site.
- *   4. 302 to the resolved target_url. On miss/error, 302 to "/".
+ *   2. Hit `<resolverBase>/api/short-links/<code>`. The resolver increments the
+ *      click counter and stamps first/last click timestamps.
+ *   3. For post rail links: inject UTM params into the target URL.
+ *   4. Fire the appropriate PostHog event (dm_short_link_clicked or
+ *      post_short_link_clicked) fire-and-forget, non-blocking.
+ *   5. 302 to the resolved target_url. On miss/error, 302 to "/".
  */
 export function createDmShortLinkRedirectHandler(config: DmShortLinkRedirectConfig) {
   const {
@@ -55,6 +64,8 @@ export function createDmShortLinkRedirectHandler(config: DmShortLinkRedirectConf
 
     let target: string | null = null;
     let dmId: number | null = null;
+    let postId: number | null = null;
+    let replyId: number | null = null;
     let project: string | null = null;
     let platform: string | null = null;
 
@@ -67,12 +78,16 @@ export function createDmShortLinkRedirectHandler(config: DmShortLinkRedirectConf
         const body = (await resp.json()) as {
           target_url?: string;
           dm_id?: number;
+          post_id?: number;
+          reply_id?: number;
           project?: string;
           platform?: string;
         };
         if (body.target_url) {
           target = body.target_url;
           dmId = body.dm_id ?? null;
+          postId = body.post_id ?? null;
+          replyId = body.reply_id ?? null;
           project = body.project ?? null;
           platform = body.platform ?? null;
         }
@@ -81,8 +96,29 @@ export function createDmShortLinkRedirectHandler(config: DmShortLinkRedirectConf
       console.error("[dm-short-link/redirect] resolver fetch failed:", err);
     }
 
+    // For post rail links (public posts/comments), inject UTM params so
+    // PostHog can stitch click -> conversion events. DM rail links already
+    // have Cal.com metadata[utm_*] attribution embedded at mint time, so we
+    // leave those URLs untouched.
+    if (target && (postId != null || replyId != null)) {
+      try {
+        const targetUrl = new URL(target);
+        if (!targetUrl.searchParams.has("utm_source")) {
+          if (platform) targetUrl.searchParams.set("utm_source", platform);
+          targetUrl.searchParams.set("utm_medium", "social");
+          if (project) targetUrl.searchParams.set("utm_campaign", project);
+          targetUrl.searchParams.set("utm_content", code);
+          target = targetUrl.toString();
+        }
+      } catch {
+        // Keep original target if URL parsing fails (e.g. non-HTTP scheme).
+      }
+    }
+
     const posthogKey = process.env[posthogKeyEnv];
     const posthogHost = (process.env[posthogHostEnv] || "https://us.i.posthog.com").replace(/\/+$/, "");
+
+    // DM rail event
     if (target && posthogKey && dmId != null) {
       fetch(`${posthogHost}/i/v0/e/`, {
         method: "POST",
@@ -99,6 +135,30 @@ export function createDmShortLinkRedirectHandler(config: DmShortLinkRedirectConf
       );
     }
 
+    // Post rail event
+    if (target && posthogKey && (postId != null || replyId != null)) {
+      fetch(`${posthogHost}/i/v0/e/`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          api_key: posthogKey,
+          event: "post_short_link_clicked",
+          distinct_id: `post_${postId ?? replyId}`,
+          timestamp: new Date().toISOString(),
+          properties: {
+            post_id: postId,
+            reply_id: replyId,
+            project,
+            platform,
+            code,
+            site,
+          },
+        }),
+      }).catch((err) =>
+        console.error("[dm-short-link/redirect] posthog fetch failed:", err)
+      );
+    }
+
     return Response.redirect(target || homeUrl, 302);
   };
 }

package/src/lib/newsletter-route.ts

@@ -124,6 +124,7 @@ export interface NewsletterConfig {
   onSignup?: (email: string, resendEmailId: string | null) => Promise<void>;
 }
 
+
 /* ------------------------------------------------------------------ */
 /*  Factory                                                            */
 /* ------------------------------------------------------------------ */