@hogsend/email 0.13.2 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/email",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "type": "module",
   "license": "MIT",
   "repository": {

package/src/__tests__/email-action.test.ts

@@ -0,0 +1,89 @@
+import { createElement } from "react";
+import { Body, Html } from "react-email";
+import { describe, expect, it } from "vitest";
+import { EmailAction } from "../email-action.js";
+import { renderToHtml, renderToPlainText } from "../render.js";
+
+// EmailAction is the template side of the semantic-link wire: it must render a
+// plain anchor carrying data-hs-event / data-hs-props through renderToHtml so
+// the engine's rewriteLinks can lift + strip them at send time.
+function fixtureElement() {
+  return createElement(
+    Html,
+    null,
+    createElement(
+      Body,
+      null,
+      createElement(
+        EmailAction,
+        {
+          href: "https://example.com/thanks?score=9",
+          event: "nps.submitted",
+          properties: { score: 9, source: "email" },
+        },
+        "9",
+      ),
+    ),
+  );
+}
+
+describe("EmailAction", () => {
+  it("renders an anchor with the semantic data attributes", async () => {
+    const html = await renderToHtml(fixtureElement());
+    expect(html).toContain('href="https://example.com/thanks?score=9"');
+    expect(html).toContain('data-hs-event="nps.submitted"');
+    // React entity-escapes the JSON quotes — the engine lifter decodes them.
+    expect(html).toContain(
+      'data-hs-props="{"score":9,"source":"email"}"',
+    );
+  });
+
+  it("omits data-hs-props when no properties are given", async () => {
+    const html = await renderToHtml(
+      createElement(
+        Html,
+        null,
+        createElement(
+          Body,
+          null,
+          createElement(
+            EmailAction,
+            { href: "https://example.com/yes", event: "checkin.answered" },
+            "Yes",
+          ),
+        ),
+      ),
+    );
+    expect(html).toContain('data-hs-event="checkin.answered"');
+    expect(html).not.toContain("data-hs-props");
+  });
+
+  it("passes ordinary anchor props through", async () => {
+    const html = await renderToHtml(
+      createElement(
+        Html,
+        null,
+        createElement(
+          Body,
+          null,
+          createElement(
+            EmailAction,
+            {
+              href: "https://example.com/yes",
+              event: "checkin.answered",
+              style: { color: "rgb(1, 2, 3)" },
+            },
+            "Yes",
+          ),
+        ),
+      ),
+    );
+    expect(html).toContain("color:rgb(1, 2, 3)");
+  });
+
+  it("leaves plain-text rendering untouched", async () => {
+    const text = await renderToPlainText(fixtureElement());
+    expect(text).not.toContain("data-hs-event");
+    expect(text).not.toContain("data-hs-props");
+  });
+});

package/src/email-action.ts

@@ -0,0 +1,64 @@
+import {
+  type ComponentPropsWithoutRef,
+  createElement,
+  type ReactElement,
+} from "react";
+
+/**
+ * Attribute names used to carry semantic-link metadata from the rendered
+ * template to the engine's link rewriter. INTERNAL wire format: the engine
+ * strips both attributes before the HTML reaches the email provider — the
+ * persisted `tracked_links` row is the contract, not this encoding.
+ */
+export const EMAIL_ACTION_EVENT_ATTR = "data-hs-event";
+export const EMAIL_ACTION_PROPS_ATTR = "data-hs-props";
+
+/** Scalar-only payload — non-scalar values don't survive the Hatchet wire. */
+export type EmailActionProperties = Record<
+  string,
+  string | number | boolean | null
+>;
+
+export interface EmailActionProps extends ComponentPropsWithoutRef<"a"> {
+  /** Where the recipient lands after the click is recorded. */
+  href: string;
+  /**
+   * Consumer event name emitted through the full ingest pipeline when this
+   * link is clicked (e.g. "nps.submitted"). Engine-reserved namespaces
+   * (`email.*`, `journey.*`, `bucket.*`, `contact.*`) are rejected at send
+   * time.
+   */
+  event: string;
+  /** Event payload, recorded at send time and emitted with every answer. */
+  properties?: EmailActionProperties;
+}
+
+/**
+ * A semantic link — an `<a>` whose click MEANS something. Renders a plain
+ * anchor (react-email's Tailwind transform still applies to `className`),
+ * tagged with the event metadata for the engine to lift at send time.
+ *
+ * Every answer in an email is a link: a yes/no question is two EmailActions,
+ * an NPS survey is eleven. The first click per (send, event name) wins.
+ *
+ * Plain `.ts` + `createElement` (no JSX) so consumers type-checking this
+ * package's raw source need no `jsx` compiler setting.
+ */
+export function EmailAction({
+  event,
+  properties,
+  children,
+  ...anchor
+}: EmailActionProps): ReactElement {
+  return createElement(
+    "a",
+    {
+      ...anchor,
+      [EMAIL_ACTION_EVENT_ATTR]: event,
+      [EMAIL_ACTION_PROPS_ATTR]: properties
+        ? JSON.stringify(properties)
+        : undefined,
+    },
+    children,
+  );
+}

package/src/index.ts

@@ -2,6 +2,16 @@
 // baked in here; clients own their `.tsx` templates + registry and augment the
 // open `TemplateRegistryMap` interface (Option B).
 
+// Semantic links (in-email actions)
+export type {
+  EmailActionProperties,
+  EmailActionProps,
+} from "./email-action.js";
+export {
+  EMAIL_ACTION_EVENT_ATTR,
+  EMAIL_ACTION_PROPS_ATTR,
+  EmailAction,
+} from "./email-action.js";
 // Template registry
 export {
   createRegistry,
@@ -10,7 +20,6 @@ export {
   getTemplateDefinition,
   getTemplateNames,
 } from "./registry.js";
-
 // Rendering
 export { renderToHtml, renderToPlainText } from "./render.js";