@spfn/notification 0.1.0-beta.13 → 0.1.0-beta.15

package/dist/server.js

@@ -43,6 +43,29 @@ var notificationEnvSchema = defineEnvSchema({
       examples: ["https://hooks.slack.com/services/xxx/xxx/xxx"]
     })
   },
+  // Tracking
+  SPFN_NOTIFICATION_TRACKING_ENABLED: {
+    ...envString({
+      description: "Enable email engagement tracking (open/click)",
+      default: "false",
+      required: false,
+      examples: ["true", "false"]
+    })
+  },
+  SPFN_NOTIFICATION_TRACKING_SECRET: {
+    ...envString({
+      description: "HMAC secret key for tracking token signing",
+      required: false,
+      sensitive: true
+    })
+  },
+  SPFN_NOTIFICATION_TRACKING_BASE_URL: {
+    ...envString({
+      description: "Base URL for tracking endpoints",
+      required: false,
+      examples: ["https://api.example.com"]
+    })
+  },
   // AWS (shared with other AWS services)
   AWS_REGION: {
     ...envString({
@@ -93,6 +116,18 @@ function getAppName() {
 function isHistoryEnabled() {
   return globalConfig.enableHistory ?? false;
 }
+function isTrackingEnabled() {
+  if (globalConfig.tracking?.enabled != null) {
+    return globalConfig.tracking.enabled;
+  }
+  return env.SPFN_NOTIFICATION_TRACKING_ENABLED === "true";
+}
+function getTrackingSecret() {
+  return globalConfig.tracking?.secret ?? env.SPFN_NOTIFICATION_TRACKING_SECRET;
+}
+function getTrackingBaseUrl() {
+  return globalConfig.tracking?.baseUrl ?? env.SPFN_NOTIFICATION_TRACKING_BASE_URL;
+}
 
 // src/channels/email/providers/aws-ses.ts
 import { logger } from "@spfn/core/logger";
@@ -168,6 +203,114 @@ var awsSesProvider = {
   }
 };
 
+// src/tracking/token.ts
+import { createHmac } from "crypto";
+function toBase64Url(buffer) {
+  return buffer.toString("base64url");
+}
+function fromBase64Url(str) {
+  return Buffer.from(str, "base64url").toString("utf8");
+}
+function sign(payload) {
+  const secret = getTrackingSecret();
+  if (!secret) {
+    throw new Error("Tracking secret is not configured");
+  }
+  const payloadEncoded = toBase64Url(Buffer.from(payload, "utf8"));
+  const hmac = createHmac("sha256", secret).update(payload).digest();
+  const hmacEncoded = toBase64Url(hmac);
+  return `${payloadEncoded}.${hmacEncoded}`;
+}
+function verify(token) {
+  const secret = getTrackingSecret();
+  if (!secret) {
+    return { valid: false };
+  }
+  const dotIndex = token.indexOf(".");
+  if (dotIndex === -1) {
+    return { valid: false };
+  }
+  const payloadEncoded = token.substring(0, dotIndex);
+  const hmacEncoded = token.substring(dotIndex + 1);
+  const payload = fromBase64Url(payloadEncoded);
+  const expectedHmac = createHmac("sha256", secret).update(payload).digest();
+  const expectedHmacEncoded = toBase64Url(expectedHmac);
+  if (hmacEncoded !== expectedHmacEncoded) {
+    return { valid: false };
+  }
+  return { valid: true, payload };
+}
+function generateOpenToken(notificationId) {
+  return sign(`o:${notificationId}`);
+}
+function generateClickToken(notificationId, linkIndex) {
+  return sign(`c:${notificationId}:${linkIndex}`);
+}
+function verifyOpenToken(token) {
+  const result = verify(token);
+  if (!result.valid || !result.payload) {
+    return { valid: false };
+  }
+  const match = result.payload.match(/^o:(\d+)$/);
+  if (!match) {
+    return { valid: false };
+  }
+  return { valid: true, notificationId: Number(match[1]) };
+}
+function verifyClickToken(token) {
+  const result = verify(token);
+  if (!result.valid || !result.payload) {
+    return { valid: false };
+  }
+  const match = result.payload.match(/^c:(\d+):(\d+)$/);
+  if (!match) {
+    return { valid: false };
+  }
+  return {
+    valid: true,
+    notificationId: Number(match[1]),
+    linkIndex: Number(match[2])
+  };
+}
+
+// src/tracking/processor.ts
+var SKIP_PROTOCOLS = ["mailto:", "tel:", "sms:", "javascript:"];
+function shouldSkipUrl(url) {
+  const trimmed = url.trim();
+  if (trimmed === "" || trimmed === "#" || trimmed.startsWith("#")) {
+    return true;
+  }
+  const lower = trimmed.toLowerCase();
+  return SKIP_PROTOCOLS.some((proto) => lower.startsWith(proto));
+}
+function processTrackingHtml(html, options) {
+  const { notificationId, baseUrl } = options;
+  const trackedLinks = [];
+  let linkIndex = 0;
+  const processedHtml = html.replace(
+    /<a\s([^>]*?)href\s*=\s*["']([^"']+)["']([^>]*?)>/gi,
+    (match, before, url, after) => {
+      if (shouldSkipUrl(url)) {
+        return match;
+      }
+      const currentIndex = linkIndex++;
+      const clickToken = generateClickToken(notificationId, currentIndex);
+      const trackingUrl = `${baseUrl}/_noti/t/c/${clickToken}?url=${encodeURIComponent(url)}`;
+      trackedLinks.push({ index: currentIndex, url });
+      return `<a ${before}href="${trackingUrl}"${after}>`;
+    }
+  );
+  const openToken = generateOpenToken(notificationId);
+  const pixel = `<img src="${baseUrl}/_noti/t/o/${openToken}" width="1" height="1" style="display:none" alt="" />`;
+  let finalHtml;
+  if (processedHtml.includes("</body>")) {
+    finalHtml = processedHtml.replace("</body>", `${pixel}</body>`);
+  } else {
+    finalHtml = processedHtml + pixel;
+  }
+  return { html: finalHtml, trackedLinks };
+}
+
 // src/templates/renderer.ts
 var filters = {
   /**
@@ -503,6 +646,47 @@ var notifications = notificationSchema.table(
   ]
 );
 
+// src/entities/tracking-events.ts
+import { integer, text as text2, index as index2 } from "drizzle-orm/pg-core";
+import { id as id2, timestamps as timestamps2 } from "@spfn/core/db";
+var TRACKING_EVENT_TYPES = ["open", "click"];
+var trackingEvents = notificationSchema.table(
+  "tracking_events",
+  {
+    id: id2(),
+    /**
+     * Reference to history.id (notification that was tracked)
+     */
+    notificationId: integer("notification_id").notNull(),
+    /**
+     * Event type (open or click)
+     */
+    type: text2("type", { enum: TRACKING_EVENT_TYPES }).notNull(),
+    /**
+     * Original URL (click events only)
+     */
+    linkUrl: text2("link_url"),
+    /**
+     * Link position index in the email (click events only)
+     */
+    linkIndex: integer("link_index"),
+    /**
+     * IP address of the requester
+     */
+    ipAddress: text2("ip_address"),
+    /**
+     * User agent string of the requester
+     */
+    userAgent: text2("user_agent"),
+    ...timestamps2()
+  },
+  (table) => [
+    index2("te_notification_id_idx").on(table.notificationId),
+    index2("te_type_idx").on(table.type),
+    index2("te_created_at_idx").on(table.createdAt)
+  ]
+);
+
 // src/services/notification.service.ts
 async function createNotificationRecord(data) {
   return await create(notifications, {
@@ -516,13 +700,13 @@ async function createScheduledNotification(data) {
     status: "scheduled"
   });
 }
-async function updateNotificationJobId(id2, jobId) {
-  return await updateOne(notifications, { id: id2 }, { jobId });
+async function updateNotificationJobId(id3, jobId) {
+  return await updateOne(notifications, { id: id3 }, { jobId });
 }
-async function markNotificationSent(id2, providerMessageId) {
+async function markNotificationSent(id3, providerMessageId) {
   return await updateOne(
     notifications,
-    { id: id2 },
+    { id: id3 },
     {
       status: "sent",
       sentAt: /* @__PURE__ */ new Date(),
@@ -530,27 +714,27 @@ async function markNotificationSent(id2, providerMessageId) {
     }
   );
 }
-async function markNotificationFailed(id2, errorMessage) {
+async function markNotificationFailed(id3, errorMessage) {
   return await updateOne(
     notifications,
-    { id: id2 },
+    { id: id3 },
     {
       status: "failed",
       errorMessage
     }
   );
 }
-async function markNotificationPending(id2) {
+async function markNotificationPending(id3) {
   return await updateOne(
     notifications,
-    { id: id2 },
+    { id: id3 },
     { status: "pending" }
   );
 }
-async function cancelScheduledNotification(id2) {
+async function cancelScheduledNotification(id3) {
   return await updateOne(
     notifications,
-    { id: id2 },
+    { id: id3 },
     { status: "cancelled" }
   );
 }
@@ -653,7 +837,7 @@ function getProvider() {
 async function sendEmail(params) {
   const recipients = Array.isArray(params.to) ? params.to : [params.to];
   let subject = params.subject;
-  let text2 = params.text;
+  let text3 = params.text;
   let html = params.html;
   if (params.template) {
     if (!hasTemplate(params.template)) {
@@ -666,7 +850,7 @@ async function sendEmail(params) {
     const rendered = renderTemplate(params.template, params.data || {}, "email");
     if (rendered.email) {
       subject = rendered.email.subject;
-      text2 = rendered.email.text;
+      text3 = rendered.email.text;
       html = rendered.email.html;
     }
   }
@@ -677,7 +861,7 @@ async function sendEmail(params) {
       error: "Email subject is required"
     };
   }
-  if (!text2 && !html) {
+  if (!text3 && !html) {
     log2.warn("Email content (text or html) is required", { to: recipients, subject });
     return {
       success: false,
@@ -689,7 +873,7 @@ async function sendEmail(params) {
     from: params.from || getEmailFrom(),
     replyTo: params.replyTo || getEmailReplyTo(),
     subject,
-    text: text2,
+    text: text3,
     html
   };
   const provider = getProvider();
@@ -702,7 +886,7 @@ async function sendEmail(params) {
         templateName: params.template,
         templateData: params.data,
         subject,
-        content: text2,
+        content: text3,
         providerName: provider.name
       });
       historyId = record.id;
@@ -710,6 +894,19 @@ async function sendEmail(params) {
       log2.warn("Failed to create notification history record", error);
     }
   }
+  const shouldTrack = params.tracking ?? isTrackingEnabled();
+  const trackingBaseUrl = getTrackingBaseUrl();
+  if (shouldTrack && historyId && internalParams.html && trackingBaseUrl) {
+    try {
+      const { html: trackedHtml } = processTrackingHtml(internalParams.html, {
+        notificationId: historyId,
+        baseUrl: trackingBaseUrl
+      });
+      internalParams.html = trackedHtml;
+    } catch (error) {
+      log2.warn("Failed to apply tracking to email HTML", error);
+    }
+  }
   const result = await provider.send(internalParams);
   if (result.success) {
     log2.info("Email sent", { to: recipients, subject, messageId: result.messageId });
@@ -977,7 +1174,7 @@ async function sendSlack(params) {
       error: "Slack webhook URL is required. Set SPFN_NOTIFICATION_SLACK_WEBHOOK_URL or pass webhookUrl."
     };
   }
-  let text2 = params.text;
+  let text3 = params.text;
   let blocks = params.blocks;
   if (params.template) {
     if (!hasTemplate(params.template)) {
@@ -989,11 +1186,11 @@ async function sendSlack(params) {
     }
     const rendered = renderTemplate(params.template, params.data || {}, "slack");
     if (rendered.slack) {
-      text2 = rendered.slack.text;
+      text3 = rendered.slack.text;
       blocks = rendered.slack.blocks;
     }
   }
-  if (!text2 && !blocks) {
+  if (!text3 && !blocks) {
     log6.warn("Slack message requires text or blocks");
     return {
       success: false,
@@ -1002,7 +1199,7 @@ async function sendSlack(params) {
   }
   const internalParams = {
     webhookUrl,
-    text: text2,
+    text: text3,
     blocks
   };
   const provider = getProvider3();
@@ -1014,7 +1211,7 @@ async function sendSlack(params) {
         recipient: webhookUrl,
         templateName: params.template,
         templateData: params.data,
-        content: text2,
+        content: text3,
         providerName: provider.name
       });
       historyId = record.id;
@@ -1733,8 +1930,8 @@ function Array2(items, options) {
 }
 
 // ../../node_modules/.pnpm/@sinclair+typebox@0.34.41/node_modules/@sinclair/typebox/build/esm/type/argument/argument.mjs
-function Argument(index2) {
-  return CreateType({ [Kind]: "Argument", index: index2 });
+function Argument(index3) {
+  return CreateType({ [Kind]: "Argument", index: index3 });
 }
 
 // ../../node_modules/.pnpm/@sinclair+typebox@0.34.41/node_modules/@sinclair/typebox/build/esm/type/async-iterator/async-iterator.mjs
@@ -1813,28 +2010,28 @@ var TemplateLiteralParserError = class extends TypeBoxError {
 function Unescape(pattern) {
   return pattern.replace(/\\\$/g, "$").replace(/\\\*/g, "*").replace(/\\\^/g, "^").replace(/\\\|/g, "|").replace(/\\\(/g, "(").replace(/\\\)/g, ")");
 }
-function IsNonEscaped(pattern, index2, char) {
-  return pattern[index2] === char && pattern.charCodeAt(index2 - 1) !== 92;
+function IsNonEscaped(pattern, index3, char) {
+  return pattern[index3] === char && pattern.charCodeAt(index3 - 1) !== 92;
 }
-function IsOpenParen(pattern, index2) {
-  return IsNonEscaped(pattern, index2, "(");
+function IsOpenParen(pattern, index3) {
+  return IsNonEscaped(pattern, index3, "(");
 }
-function IsCloseParen(pattern, index2) {
-  return IsNonEscaped(pattern, index2, ")");
+function IsCloseParen(pattern, index3) {
+  return IsNonEscaped(pattern, index3, ")");
 }
-function IsSeparator(pattern, index2) {
-  return IsNonEscaped(pattern, index2, "|");
+function IsSeparator(pattern, index3) {
+  return IsNonEscaped(pattern, index3, "|");
 }
 function IsGroup(pattern) {
   if (!(IsOpenParen(pattern, 0) && IsCloseParen(pattern, pattern.length - 1)))
     return false;
   let count2 = 0;
-  for (let index2 = 0; index2 < pattern.length; index2++) {
-    if (IsOpenParen(pattern, index2))
+  for (let index3 = 0; index3 < pattern.length; index3++) {
+    if (IsOpenParen(pattern, index3))
       count2 += 1;
-    if (IsCloseParen(pattern, index2))
+    if (IsCloseParen(pattern, index3))
       count2 -= 1;
-    if (count2 === 0 && index2 !== pattern.length - 1)
+    if (count2 === 0 && index3 !== pattern.length - 1)
       return false;
   }
   return true;
@@ -1844,19 +2041,19 @@ function InGroup(pattern) {
 }
 function IsPrecedenceOr(pattern) {
   let count2 = 0;
-  for (let index2 = 0; index2 < pattern.length; index2++) {
-    if (IsOpenParen(pattern, index2))
+  for (let index3 = 0; index3 < pattern.length; index3++) {
+    if (IsOpenParen(pattern, index3))
       count2 += 1;
-    if (IsCloseParen(pattern, index2))
+    if (IsCloseParen(pattern, index3))
       count2 -= 1;
-    if (IsSeparator(pattern, index2) && count2 === 0)
+    if (IsSeparator(pattern, index3) && count2 === 0)
       return true;
   }
   return false;
 }
 function IsPrecedenceAnd(pattern) {
-  for (let index2 = 0; index2 < pattern.length; index2++) {
-    if (IsOpenParen(pattern, index2))
+  for (let index3 = 0; index3 < pattern.length; index3++) {
+    if (IsOpenParen(pattern, index3))
       return true;
   }
   return false;
@@ -1864,16 +2061,16 @@ function IsPrecedenceAnd(pattern) {
 function Or(pattern) {
   let [count2, start] = [0, 0];
   const expressions = [];
-  for (let index2 = 0; index2 < pattern.length; index2++) {
-    if (IsOpenParen(pattern, index2))
+  for (let index3 = 0; index3 < pattern.length; index3++) {
+    if (IsOpenParen(pattern, index3))
       count2 += 1;
-    if (IsCloseParen(pattern, index2))
+    if (IsCloseParen(pattern, index3))
       count2 -= 1;
-    if (IsSeparator(pattern, index2) && count2 === 0) {
-      const range2 = pattern.slice(start, index2);
+    if (IsSeparator(pattern, index3) && count2 === 0) {
+      const range2 = pattern.slice(start, index3);
       if (range2.length > 0)
         expressions.push(TemplateLiteralParse(range2));
-      start = index2 + 1;
+      start = index3 + 1;
     }
   }
   const range = pattern.slice(start);
@@ -1886,40 +2083,40 @@ function Or(pattern) {
   return { type: "or", expr: expressions };
 }
 function And(pattern) {
-  function Group(value, index2) {
-    if (!IsOpenParen(value, index2))
+  function Group(value, index3) {
+    if (!IsOpenParen(value, index3))
       throw new TemplateLiteralParserError(`TemplateLiteralParser: Index must point to open parens`);
     let count2 = 0;
-    for (let scan = index2; scan < value.length; scan++) {
+    for (let scan = index3; scan < value.length; scan++) {
       if (IsOpenParen(value, scan))
         count2 += 1;
       if (IsCloseParen(value, scan))
         count2 -= 1;
       if (count2 === 0)
-        return [index2, scan];
+        return [index3, scan];
     }
     throw new TemplateLiteralParserError(`TemplateLiteralParser: Unclosed group parens in expression`);
   }
-  function Range(pattern2, index2) {
-    for (let scan = index2; scan < pattern2.length; scan++) {
+  function Range(pattern2, index3) {
+    for (let scan = index3; scan < pattern2.length; scan++) {
       if (IsOpenParen(pattern2, scan))
-        return [index2, scan];
+        return [index3, scan];
     }
-    return [index2, pattern2.length];
+    return [index3, pattern2.length];
   }
   const expressions = [];
-  for (let index2 = 0; index2 < pattern.length; index2++) {
-    if (IsOpenParen(pattern, index2)) {
-      const [start, end] = Group(pattern, index2);
+  for (let index3 = 0; index3 < pattern.length; index3++) {
+    if (IsOpenParen(pattern, index3)) {
+      const [start, end] = Group(pattern, index3);
       const range = pattern.slice(start, end + 1);
       expressions.push(TemplateLiteralParse(range));
-      index2 = end;
+      index3 = end;
     } else {
-      const [start, end] = Range(pattern, index2);
+      const [start, end] = Range(pattern, index3);
       const range = pattern.slice(start, end);
       if (range.length > 0)
         expressions.push(TemplateLiteralParse(range));
-      index2 = end - 1;
+      index3 = end - 1;
     }
   }
   return expressions.length === 0 ? { type: "const", const: "" } : expressions.length === 1 ? expressions[0] : { type: "and", expr: expressions };
@@ -2611,13 +2808,13 @@ function FromBoolean(left, right) {
   return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) ? FromObjectRight(left, right) : type_exports.IsRecord(right) ? FromRecordRight(left, right) : type_exports.IsBoolean(right) ? ExtendsResult.True : ExtendsResult.False;
 }
 function FromConstructor(left, right) {
-  return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) ? FromObjectRight(left, right) : !type_exports.IsConstructor(right) ? ExtendsResult.False : left.parameters.length > right.parameters.length ? ExtendsResult.False : !left.parameters.every((schema, index2) => IntoBooleanResult(Visit3(right.parameters[index2], schema)) === ExtendsResult.True) ? ExtendsResult.False : IntoBooleanResult(Visit3(left.returns, right.returns));
+  return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) ? FromObjectRight(left, right) : !type_exports.IsConstructor(right) ? ExtendsResult.False : left.parameters.length > right.parameters.length ? ExtendsResult.False : !left.parameters.every((schema, index3) => IntoBooleanResult(Visit3(right.parameters[index3], schema)) === ExtendsResult.True) ? ExtendsResult.False : IntoBooleanResult(Visit3(left.returns, right.returns));
 }
 function FromDate(left, right) {
   return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) ? FromObjectRight(left, right) : type_exports.IsRecord(right) ? FromRecordRight(left, right) : type_exports.IsDate(right) ? ExtendsResult.True : ExtendsResult.False;
 }
 function FromFunction(left, right) {
-  return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) ? FromObjectRight(left, right) : !type_exports.IsFunction(right) ? ExtendsResult.False : left.parameters.length > right.parameters.length ? ExtendsResult.False : !left.parameters.every((schema, index2) => IntoBooleanResult(Visit3(right.parameters[index2], schema)) === ExtendsResult.True) ? ExtendsResult.False : IntoBooleanResult(Visit3(left.returns, right.returns));
+  return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) ? FromObjectRight(left, right) : !type_exports.IsFunction(right) ? ExtendsResult.False : left.parameters.length > right.parameters.length ? ExtendsResult.False : !left.parameters.every((schema, index3) => IntoBooleanResult(Visit3(right.parameters[index3], schema)) === ExtendsResult.True) ? ExtendsResult.False : IntoBooleanResult(Visit3(left.returns, right.returns));
 }
 function FromIntegerRight(left, right) {
   return type_exports.IsLiteral(left) && value_exports.IsNumber(left.const) ? ExtendsResult.True : type_exports.IsNumber(left) || type_exports.IsInteger(left) ? ExtendsResult.True : ExtendsResult.False;
@@ -2777,7 +2974,7 @@ function FromTupleRight(left, right) {
   return type_exports.IsNever(left) ? ExtendsResult.True : type_exports.IsUnknown(left) ? ExtendsResult.False : type_exports.IsAny(left) ? ExtendsResult.Union : ExtendsResult.False;
 }
 function FromTuple3(left, right) {
-  return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) && IsObjectArrayLike(right) ? ExtendsResult.True : type_exports.IsArray(right) && IsArrayOfTuple(left, right) ? ExtendsResult.True : !type_exports.IsTuple(right) ? ExtendsResult.False : value_exports.IsUndefined(left.items) && !value_exports.IsUndefined(right.items) || !value_exports.IsUndefined(left.items) && value_exports.IsUndefined(right.items) ? ExtendsResult.False : value_exports.IsUndefined(left.items) && !value_exports.IsUndefined(right.items) ? ExtendsResult.True : left.items.every((schema, index2) => Visit3(schema, right.items[index2]) === ExtendsResult.True) ? ExtendsResult.True : ExtendsResult.False;
+  return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) && IsObjectArrayLike(right) ? ExtendsResult.True : type_exports.IsArray(right) && IsArrayOfTuple(left, right) ? ExtendsResult.True : !type_exports.IsTuple(right) ? ExtendsResult.False : value_exports.IsUndefined(left.items) && !value_exports.IsUndefined(right.items) || !value_exports.IsUndefined(left.items) && value_exports.IsUndefined(right.items) ? ExtendsResult.False : value_exports.IsUndefined(left.items) && !value_exports.IsUndefined(right.items) ? ExtendsResult.True : left.items.every((schema, index3) => Visit3(schema, right.items[index3]) === ExtendsResult.True) ? ExtendsResult.True : ExtendsResult.False;
 }
 function FromUint8Array(left, right) {
   return IsStructuralRight(right) ? StructuralRight(left, right) : type_exports.IsObject(right) ? FromObjectRight(left, right) : type_exports.IsRecord(right) ? FromRecordRight(left, right) : type_exports.IsUint8Array(right) ? ExtendsResult.True : ExtendsResult.False;
@@ -3726,7 +3923,7 @@ var sendScheduledSmsJob = job2("notification.send-scheduled-sms").input(SendSche
 async function scheduleEmail(params, options) {
   const recipients = Array.isArray(params.to) ? params.to : [params.to];
   let subject = params.subject;
-  let text2 = params.text;
+  let text3 = params.text;
   let html = params.html;
   if (params.template) {
     if (!hasTemplate(params.template)) {
@@ -3738,7 +3935,7 @@ async function scheduleEmail(params, options) {
     const rendered = renderTemplate(params.template, params.data || {}, "email");
     if (rendered.email) {
       subject = rendered.email.subject;
-      text2 = rendered.email.text;
+      text3 = rendered.email.text;
       html = rendered.email.html;
     }
   }
@@ -3748,7 +3945,7 @@ async function scheduleEmail(params, options) {
       error: "Email subject is required"
     };
   }
-  if (!text2 && !html) {
+  if (!text3 && !html) {
     return {
       success: false,
       error: "Email content (text or html) is required"
@@ -3761,7 +3958,7 @@ async function scheduleEmail(params, options) {
       templateName: params.template,
       templateData: params.data,
       subject,
-      content: text2,
+      content: text3,
       providerName: "pending",
       // Will be set when job runs
       scheduledAt: options.scheduledAt,
@@ -3896,12 +4093,12 @@ async function cancelNotification(notificationId) {
 }
 async function cancelNotificationsByReference(referenceType, referenceId) {
   const { findMany: findMany2 } = await import("@spfn/core/db");
-  const { eq: eq2, and: and2 } = await import("drizzle-orm");
+  const { eq: eq3, and: and3 } = await import("drizzle-orm");
   const scheduledNotifications = await findMany2(notifications, {
-    where: and2(
-      eq2(notifications.referenceType, referenceType),
-      eq2(notifications.referenceId, referenceId),
-      eq2(notifications.status, "scheduled")
+    where: and3(
+      eq3(notifications.referenceType, referenceType),
+      eq3(notifications.referenceId, referenceId),
+      eq3(notifications.status, "scheduled")
     )
   });
   let cancelled = 0;
@@ -4045,11 +4242,189 @@ function createErrorSlackNotifier(options = {}) {
   };
 }
 
+// src/tracking/routes.ts
+import { route } from "@spfn/core/route";
+import { defineRouter } from "@spfn/core/route";
+
+// src/tracking/tracking.service.ts
+import { create as create2, getDatabase } from "@spfn/core/db";
+import { eq as eq2, and as and2, gte as gte2, lte as lte2, count as drizzleCount, countDistinct } from "drizzle-orm";
+import { logger as logger7 } from "@spfn/core/logger";
+var log7 = logger7.child("@spfn/notification:tracking");
+function recordOpenEvent(notificationId, meta) {
+  create2(trackingEvents, {
+    notificationId,
+    type: "open",
+    ipAddress: meta?.ipAddress,
+    userAgent: meta?.userAgent
+  }).catch((error) => {
+    log7.warn("Failed to record open event", error);
+  });
+}
+function recordClickEvent(notificationId, linkIndex, linkUrl, meta) {
+  create2(trackingEvents, {
+    notificationId,
+    type: "click",
+    linkUrl,
+    linkIndex,
+    ipAddress: meta?.ipAddress,
+    userAgent: meta?.userAgent
+  }).catch((error) => {
+    log7.warn("Failed to record click event", error);
+  });
+}
+async function getTrackingStats(notificationId) {
+  const db = getDatabase("read");
+  const rows = await db.select({
+    type: trackingEvents.type,
+    total: drizzleCount(),
+    unique: countDistinct(trackingEvents.ipAddress)
+  }).from(trackingEvents).where(eq2(trackingEvents.notificationId, notificationId)).groupBy(trackingEvents.type);
+  const openRow = rows.find((r) => r.type === "open");
+  const clickRow = rows.find((r) => r.type === "click");
+  return {
+    totalOpens: Number(openRow?.total ?? 0),
+    uniqueOpens: Number(openRow?.unique ?? 0),
+    totalClicks: Number(clickRow?.total ?? 0),
+    uniqueClicks: Number(clickRow?.unique ?? 0)
+  };
+}
+async function getEngagementStats(options = {}) {
+  const db = getDatabase("read");
+  const sentConditions = [eq2(notifications.status, "sent")];
+  if (options.channel) {
+    sentConditions.push(eq2(notifications.channel, options.channel));
+  }
+  if (options.from) {
+    sentConditions.push(gte2(notifications.createdAt, options.from));
+  }
+  if (options.to) {
+    sentConditions.push(lte2(notifications.createdAt, options.to));
+  }
+  const [sentResult] = await db.select({ count: drizzleCount() }).from(notifications).where(and2(...sentConditions));
+  const sent = Number(sentResult?.count ?? 0);
+  if (sent === 0) {
+    return { sent: 0, opened: 0, clicked: 0, openRate: 0, clickRate: 0 };
+  }
+  const eventConditions = [];
+  if (options.from) {
+    eventConditions.push(gte2(trackingEvents.createdAt, options.from));
+  }
+  if (options.to) {
+    eventConditions.push(lte2(trackingEvents.createdAt, options.to));
+  }
+  const openConditions = [
+    eq2(trackingEvents.type, "open"),
+    ...eventConditions
+  ];
+  const clickConditions = [
+    eq2(trackingEvents.type, "click"),
+    ...eventConditions
+  ];
+  const [[openResult], [clickResult]] = await Promise.all([
+    db.select({ count: countDistinct(trackingEvents.notificationId) }).from(trackingEvents).where(and2(...openConditions)),
+    db.select({ count: countDistinct(trackingEvents.notificationId) }).from(trackingEvents).where(and2(...clickConditions))
+  ]);
+  const opened = Number(openResult?.count ?? 0);
+  const clicked = Number(clickResult?.count ?? 0);
+  return {
+    sent,
+    opened,
+    clicked,
+    openRate: sent > 0 ? Number((opened / sent * 100).toFixed(2)) : 0,
+    clickRate: sent > 0 ? Number((clicked / sent * 100).toFixed(2)) : 0
+  };
+}
+async function getClickDetails(notificationId) {
+  const db = getDatabase("read");
+  const rows = await db.select({
+    linkUrl: trackingEvents.linkUrl,
+    linkIndex: trackingEvents.linkIndex,
+    totalClicks: drizzleCount(),
+    uniqueClicks: countDistinct(trackingEvents.ipAddress)
+  }).from(trackingEvents).where(
+    and2(
+      eq2(trackingEvents.notificationId, notificationId),
+      eq2(trackingEvents.type, "click")
+    )
+  ).groupBy(trackingEvents.linkUrl, trackingEvents.linkIndex).orderBy(trackingEvents.linkIndex);
+  return rows.map((row) => ({
+    linkUrl: row.linkUrl ?? "",
+    linkIndex: row.linkIndex ?? 0,
+    totalClicks: Number(row.totalClicks),
+    uniqueClicks: Number(row.uniqueClicks)
+  }));
+}
+
+// src/tracking/routes.ts
+import { logger as logger8 } from "@spfn/core/logger";
+var log8 = logger8.child("@spfn/notification:tracking:routes");
+var TRANSPARENT_GIF = Buffer.from(
+  "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
+  "base64"
+);
+var trackOpen = route.get("/_noti/t/o/:token").input({
+  params: Type.Object({
+    token: Type.String()
+  })
+}).skip(["auth"]).handler(async (c) => {
+  const { params } = await c.data();
+  const result = verifyOpenToken(params.token);
+  if (result.valid && result.notificationId) {
+    recordOpenEvent(result.notificationId, {
+      ipAddress: c.raw.req.header("x-forwarded-for") ?? c.raw.req.header("x-real-ip"),
+      userAgent: c.raw.req.header("user-agent")
+    });
+  } else {
+    log8.warn("Invalid open tracking token");
+  }
+  return new Response(TRANSPARENT_GIF, {
+    status: 200,
+    headers: {
+      "Content-Type": "image/gif",
+      "Content-Length": String(TRANSPARENT_GIF.length),
+      "Cache-Control": "no-store, no-cache, must-revalidate"
+    }
+  });
+});
+var trackClick = route.get("/_noti/t/c/:token").input({
+  params: Type.Object({
+    token: Type.String()
+  }),
+  query: Type.Object({
+    url: Type.String()
+  })
+}).skip(["auth"]).handler(async (c) => {
+  const { params, query } = await c.data();
+  const targetUrl = query.url;
+  const result = verifyClickToken(params.token);
+  if (result.valid && result.notificationId != null && result.linkIndex != null) {
+    recordClickEvent(result.notificationId, result.linkIndex, targetUrl, {
+      ipAddress: c.raw.req.header("x-forwarded-for") ?? c.raw.req.header("x-real-ip"),
+      userAgent: c.raw.req.header("user-agent")
+    });
+  } else {
+    log8.warn("Invalid click tracking token");
+  }
+  return new Response(null, {
+    status: 302,
+    headers: {
+      "Location": targetUrl,
+      "Cache-Control": "no-store, no-cache, must-revalidate"
+    }
+  });
+});
+var trackingRouter = defineRouter({
+  trackOpen,
+  trackClick
+});
+
 // src/server.ts
 registerBuiltinTemplates();
 export {
   NOTIFICATION_CHANNELS,
   NOTIFICATION_STATUSES,
+  TRACKING_EVENT_TYPES,
   cancelNotification,
   cancelNotificationsByReference,
   cancelScheduledNotification,
@@ -4062,19 +4437,26 @@ export {
   findNotifications,
   findScheduledNotifications,
   getAppName,
+  getClickDetails,
   getEmailFrom,
   getEmailReplyTo,
+  getEngagementStats,
   getNotificationConfig,
   getNotificationStats,
   getSmsDefaultCountryCode,
   getTemplate,
   getTemplateNames,
+  getTrackingBaseUrl,
+  getTrackingSecret,
+  getTrackingStats,
   hasTemplate,
+  isTrackingEnabled,
   markNotificationFailed,
   markNotificationPending,
   markNotificationSent,
   notificationJobRouter,
   notifications,
+  processTrackingHtml,
   registerBuiltinTemplates,
   registerEmailProvider,
   registerFilter,
@@ -4092,6 +4474,8 @@ export {
   sendScheduledSmsJob,
   sendSlack,
   sendSlackBulk,
+  trackingEvents,
+  trackingRouter,
   updateNotificationJobId
 };
 //# sourceMappingURL=server.js.map