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

package/README.md

@@ -9,6 +9,7 @@ Multi-channel notification system for SPFN applications.
 - **Template system**: Variable substitution with filters
 - **Scheduled delivery**: Schedule notifications for later via pg-boss
 - **History tracking**: Optional notification history with database storage
+- **Email tracking**: Open pixel & click redirect tracking with engagement analytics
 
 ## Installation
 
@@ -70,6 +71,11 @@ SPFN_NOTIFICATION_EMAIL_FROM=noreply@example.com
 # SMS
 SPFN_NOTIFICATION_SMS_PROVIDER=aws-sns
 
+# Tracking
+SPFN_NOTIFICATION_TRACKING_ENABLED=true
+SPFN_NOTIFICATION_TRACKING_SECRET=your-hmac-secret-key
+SPFN_NOTIFICATION_TRACKING_BASE_URL=https://api.example.com
+
 # AWS Credentials
 AWS_REGION=ap-northeast-2
 AWS_ACCESS_KEY_ID=xxx
@@ -95,6 +101,11 @@ configureNotification({
         appName: 'MyApp',
     },
     enableHistory: true, // Enable notification history tracking
+    tracking: {
+        enabled: true,                          // Enable email tracking
+        secret: 'your-hmac-secret-key',         // HMAC signing key
+        baseUrl: 'https://api.example.com',     // Tracking endpoint URL
+    },
 });
 ```
 
@@ -348,6 +359,114 @@ const scheduled = await findScheduledNotifications({
 });
 ```
 
+## Email Tracking
+
+Track email opens and link clicks to measure engagement.
+
+### How It Works
+
+1. **Open tracking**: A 1x1 transparent GIF is inserted before `</body>`. When the email client loads the image, an open event is recorded.
+2. **Click tracking**: `<a href>` links are wrapped with redirect URLs. When clicked, a click event is recorded and the user is redirected to the original URL.
+3. Links with `mailto:`, `tel:`, `sms:`, `javascript:`, and `#` protocols are automatically skipped.
+
+### Setup
+
+Tracking requires:
+- `enableHistory: true` (tracking events reference the history table via FK)
+- `tracking.secret` configured (HMAC token signing)
+- `tracking.baseUrl` configured (where tracking endpoints are accessible)
+- `trackingRouter` registered in your app router
+
+```typescript
+import { configureNotification, trackingRouter } from '@spfn/notification/server';
+import { defineRouter } from '@spfn/core/route';
+
+configureNotification({
+    enableHistory: true,
+    tracking: {
+        enabled: true,
+        secret: 'your-hmac-secret-key',
+        baseUrl: 'https://api.example.com',
+    },
+});
+
+// Register tracking router (provides /_noti/t/o/:token and /_noti/t/c/:token)
+const appRouter = defineRouter({ ... })
+    .packages([trackingRouter]);
+```
+
+### Per-Email Control
+
+Override the global tracking setting for individual emails:
+
+```typescript
+// Force tracking on for this email (even if globally disabled)
+await sendEmail({
+    to: 'user@example.com',
+    template: 'campaign',
+    data: { ... },
+    tracking: true,
+});
+
+// Force tracking off for this email (even if globally enabled)
+await sendEmail({
+    to: 'admin@example.com',
+    subject: 'Internal Report',
+    html: '<p>...</p>',
+    tracking: false,
+});
+```
+
+### Priority
+
+```
+sendEmail({ tracking: true/false })              ← 1st: per-call override
+configureNotification({ tracking: { enabled } }) ← 2nd: code config
+SPFN_NOTIFICATION_TRACKING_ENABLED=true           ← 3rd: environment variable
+```
+
+### Tracking Endpoints
+
+These endpoints skip authentication (accessed by email clients):
+
+| Endpoint | Response | Action |
+|----------|----------|--------|
+| `GET /_noti/t/o/:token` | 200 + 1x1 GIF | Records open event |
+| `GET /_noti/t/c/:token?url=...` | 302 redirect | Records click event, redirects to original URL |
+
+- Invalid tokens still return pixel/redirect (UX protection)
+- `Cache-Control: no-store` for re-open tracking
+- DB writes are fire-and-forget (response speed first)
+
+### Analytics
+
+```typescript
+import {
+    getTrackingStats,
+    getEngagementStats,
+    getClickDetails,
+} from '@spfn/notification/server';
+
+// Stats for a specific notification
+const stats = await getTrackingStats(notificationId);
+// { totalOpens: 15, uniqueOpens: 8, totalClicks: 5, uniqueClicks: 3 }
+
+// Overall engagement stats
+const engagement = await getEngagementStats({ channel: 'email' });
+// { sent: 1000, opened: 450, clicked: 120, openRate: 45.00, clickRate: 12.00 }
+
+// Click details per link
+const clicks = await getClickDetails(notificationId);
+// [{ linkUrl: 'https://...', linkIndex: 0, totalClicks: 5, uniqueClicks: 3 }]
+```
+
+Unique counts are based on distinct IP addresses.
+
+### Limitations
+
+- **Open tracking is approximate**: Email clients like Apple Mail Privacy Protection may pre-fetch images, inflating open counts.
+- Tracking auto-disables when `enableHistory: false` (FK dependency) or `tracking.secret` is not set.
+
 ## API Reference
 
 ### Exports
@@ -399,6 +518,14 @@ export {
     findNotifications,
     getNotificationStats,
 
+    // Tracking
+    trackingRouter,
+    processTrackingHtml,
+    getTrackingStats,
+    getEngagementStats,
+    getClickDetails,
+    isTrackingEnabled,
+
     // Jobs
     notificationJobRouter,
 };

package/dist/config/index.d.ts

@@ -42,6 +42,34 @@ declare const notificationEnvSchema: {
     } & {
         key: "SPFN_NOTIFICATION_SLACK_WEBHOOK_URL";
     };
+    SPFN_NOTIFICATION_TRACKING_ENABLED: {
+        description: string;
+        default: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_NOTIFICATION_TRACKING_ENABLED";
+    };
+    SPFN_NOTIFICATION_TRACKING_SECRET: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_NOTIFICATION_TRACKING_SECRET";
+    };
+    SPFN_NOTIFICATION_TRACKING_BASE_URL: {
+        description: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_NOTIFICATION_TRACKING_BASE_URL";
+    };
     AWS_REGION: {
         description: string;
         default: string;
@@ -111,6 +139,34 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "SPFN_NOTIFICATION_SLACK_WEBHOOK_URL";
     };
+    SPFN_NOTIFICATION_TRACKING_ENABLED: {
+        description: string;
+        default: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_NOTIFICATION_TRACKING_ENABLED";
+    };
+    SPFN_NOTIFICATION_TRACKING_SECRET: {
+        description: string;
+        required: boolean;
+        sensitive: boolean;
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_NOTIFICATION_TRACKING_SECRET";
+    };
+    SPFN_NOTIFICATION_TRACKING_BASE_URL: {
+        description: string;
+        required: boolean;
+        examples: string[];
+        type: "string";
+        validator: (value: string) => string;
+    } & {
+        key: "SPFN_NOTIFICATION_TRACKING_BASE_URL";
+    };
     AWS_REGION: {
         description: string;
         default: string;
@@ -164,6 +220,17 @@ interface NotificationConfig {
      * @default false
      */
     enableHistory?: boolean;
+    /**
+     * Email engagement tracking configuration
+     */
+    tracking?: {
+        /** Enable tracking (default: false) */
+        enabled?: boolean;
+        /** HMAC secret key for token signing */
+        secret?: string;
+        /** Base URL for tracking endpoints */
+        baseUrl?: string;
+    };
 }
 /**
  * Configure notification settings
@@ -193,5 +260,17 @@ declare function getAppName(): string;
  * Check if history tracking is enabled
  */
 declare function isHistoryEnabled(): boolean;
+/**
+ * Check if tracking is enabled (config → env → false)
+ */
+declare function isTrackingEnabled(): boolean;
+/**
+ * Get tracking HMAC secret
+ */
+declare function getTrackingSecret(): string | undefined;
+/**
+ * Get tracking base URL
+ */
+declare function getTrackingBaseUrl(): string | undefined;
 
-export { type NotificationConfig, configureNotification, env, getAppName, getEmailFrom, getEmailReplyTo, getNotificationConfig, getSmsDefaultCountryCode, isHistoryEnabled, notificationEnvSchema };
+export { type NotificationConfig, configureNotification, env, getAppName, getEmailFrom, getEmailReplyTo, getNotificationConfig, getSmsDefaultCountryCode, getTrackingBaseUrl, getTrackingSecret, isHistoryEnabled, isTrackingEnabled, notificationEnvSchema };

package/dist/config/index.js

@@ -37,6 +37,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({
@@ -87,6 +110,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;
+}
 export {
   configureNotification,
   env,
@@ -95,7 +130,10 @@ export {
   getEmailReplyTo,
   getNotificationConfig,
   getSmsDefaultCountryCode,
+  getTrackingBaseUrl,
+  getTrackingSecret,
   isHistoryEnabled,
+  isTrackingEnabled,
   notificationEnvSchema
 };
 //# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/config/index.ts","../../src/config/schema.ts"],"sourcesContent":["/**\n * @spfn/notification - Configuration\n */\n\nimport { createEnvRegistry } from '@spfn/core/env';\nimport { notificationEnvSchema } from './schema';\n\nexport { notificationEnvSchema };\n\n/**\n * Environment registry\n */\nconst registry = createEnvRegistry(notificationEnvSchema);\nexport const env = registry.validate();\n\n/**\n * Notification configuration\n */\nexport interface NotificationConfig\n{\n    email?: {\n        provider?: 'aws-ses' | 'sendgrid' | 'smtp';\n        from?: string;\n        replyTo?: string;\n    };\n    sms?: {\n        provider?: 'aws-sns' | 'twilio';\n        defaultCountryCode?: string;\n    };\n    slack?: {\n        webhookUrl?: string;\n    };\n    defaults?: {\n        appName?: string;\n    };\n    /**\n     * Enable notification history tracking (requires database)\n     * @default false\n     */\n    enableHistory?: boolean;\n}\n\nlet globalConfig: NotificationConfig = {};\n\n/**\n * Configure notification settings\n */\nexport function configureNotification(config: NotificationConfig): void\n{\n    globalConfig = { ...globalConfig, ...config };\n}\n\n/**\n * Get current notification configuration\n */\nexport function getNotificationConfig(): NotificationConfig\n{\n    return { ...globalConfig };\n}\n\n/**\n * Get email from address\n */\nexport function getEmailFrom(): string\n{\n    return globalConfig.email?.from || env.SPFN_NOTIFICATION_EMAIL_FROM || 'noreply@example.com';\n}\n\n/**\n * Get email reply-to address\n */\nexport function getEmailReplyTo(): string | undefined\n{\n    return globalConfig.email?.replyTo;\n}\n\n/**\n * Get SMS default country code\n */\nexport function getSmsDefaultCountryCode(): string\n{\n    return globalConfig.sms?.defaultCountryCode || '+82';\n}\n\n/**\n * Get app name for templates\n */\nexport function getAppName(): string\n{\n    return globalConfig.defaults?.appName || 'SPFN';\n}\n\n/**\n * Check if history tracking is enabled\n */\nexport function isHistoryEnabled(): boolean\n{\n    return globalConfig.enableHistory ?? false;\n}\n","/**\n * @spfn/notification - Environment Schema\n */\n\nimport { defineEnvSchema, envString } from '@spfn/core/env';\n\nexport const notificationEnvSchema = defineEnvSchema({\n    // Email\n    SPFN_NOTIFICATION_EMAIL_PROVIDER: {\n        ...envString({\n            description: 'Email provider (aws-ses, sendgrid, smtp)',\n            default: 'aws-ses',\n            required: false,\n            examples: ['aws-ses', 'sendgrid', 'smtp'],\n        }),\n    },\n\n    SPFN_NOTIFICATION_EMAIL_FROM: {\n        ...envString({\n            description: 'Default sender email address',\n            required: false,\n            examples: ['noreply@example.com'],\n        }),\n    },\n\n    // SMS\n    SPFN_NOTIFICATION_SMS_PROVIDER: {\n        ...envString({\n            description: 'SMS provider (aws-sns, twilio)',\n            default: 'aws-sns',\n            required: false,\n            examples: ['aws-sns', 'twilio'],\n        }),\n    },\n\n    // Slack\n    SPFN_NOTIFICATION_SLACK_WEBHOOK_URL: {\n        ...envString({\n            description: 'Slack webhook URL',\n            required: false,\n            examples: ['https://hooks.slack.com/services/xxx/xxx/xxx'],\n        }),\n    },\n\n    // AWS (shared with other AWS services)\n    AWS_REGION: {\n        ...envString({\n            description: 'AWS region',\n            default: 'ap-northeast-2',\n            required: false,\n            examples: ['ap-northeast-2', 'us-east-1'],\n        }),\n    },\n\n    AWS_ACCESS_KEY_ID: {\n        ...envString({\n            description: 'AWS access key ID',\n            required: false,\n            sensitive: true,\n        }),\n    },\n\n    AWS_SECRET_ACCESS_KEY: {\n        ...envString({\n            description: 'AWS secret access key',\n            required: false,\n            sensitive: true,\n        }),\n    },\n});\n"],"mappings":";AAIA,SAAS,yBAAyB;;;ACAlC,SAAS,iBAAiB,iBAAiB;AAEpC,IAAM,wBAAwB,gBAAgB;AAAA;AAAA,EAEjD,kCAAkC;AAAA,IAC9B,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,SAAS;AAAA,MACT,UAAU;AAAA,MACV,UAAU,CAAC,WAAW,YAAY,MAAM;AAAA,IAC5C,CAAC;AAAA,EACL;AAAA,EAEA,8BAA8B;AAAA,IAC1B,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,UAAU;AAAA,MACV,UAAU,CAAC,qBAAqB;AAAA,IACpC,CAAC;AAAA,EACL;AAAA;AAAA,EAGA,gCAAgC;AAAA,IAC5B,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,SAAS;AAAA,MACT,UAAU;AAAA,MACV,UAAU,CAAC,WAAW,QAAQ;AAAA,IAClC,CAAC;AAAA,EACL;AAAA;AAAA,EAGA,qCAAqC;AAAA,IACjC,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,UAAU;AAAA,MACV,UAAU,CAAC,8CAA8C;AAAA,IAC7D,CAAC;AAAA,EACL;AAAA;AAAA,EAGA,YAAY;AAAA,IACR,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,SAAS;AAAA,MACT,UAAU;AAAA,MACV,UAAU,CAAC,kBAAkB,WAAW;AAAA,IAC5C,CAAC;AAAA,EACL;AAAA,EAEA,mBAAmB;AAAA,IACf,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,UAAU;AAAA,MACV,WAAW;AAAA,IACf,CAAC;AAAA,EACL;AAAA,EAEA,uBAAuB;AAAA,IACnB,GAAG,UAAU;AAAA,MACT,aAAa;AAAA,MACb,UAAU;AAAA,MACV,WAAW;AAAA,IACf,CAAC;AAAA,EACL;AACJ,CAAC;;;ADzDD,IAAM,WAAW,kBAAkB,qBAAqB;AACjD,IAAM,MAAM,SAAS,SAAS;AA6BrC,IAAI,eAAmC,CAAC;AAKjC,SAAS,sBAAsB,QACtC;AACI,iBAAe,EAAE,GAAG,cAAc,GAAG,OAAO;AAChD;AAKO,SAAS,wBAChB;AACI,SAAO,EAAE,GAAG,aAAa;AAC7B;AAKO,SAAS,eAChB;AACI,SAAO,aAAa,OAAO,QAAQ,IAAI,gCAAgC;AAC3E;AAKO,SAAS,kBAChB;AACI,SAAO,aAAa,OAAO;AAC/B;AAKO,SAAS,2BAChB;AACI,SAAO,aAAa,KAAK,sBAAsB;AACnD;AAKO,SAAS,aAChB;AACI,SAAO,aAAa,UAAU,WAAW;AAC7C;AAKO,SAAS,mBAChB;AACI,SAAO,aAAa,iBAAiB;AACzC;","names":[]}
+{"version":3,"sources":["../../src/config/index.ts","../../src/config/schema.ts"],"sourcesContent":["/**\n * @spfn/notification - Configuration\n */\n\nimport { createEnvRegistry } from '@spfn/core/env';\nimport { notificationEnvSchema } from './schema';\n\nexport { notificationEnvSchema };\n\n/**\n * Environment registry\n */\nconst registry = createEnvRegistry(notificationEnvSchema);\nexport const env = registry.validate();\n\n/**\n * Notification configuration\n */\nexport interface NotificationConfig\n{\n    email?: {\n        provider?: 'aws-ses' | 'sendgrid' | 'smtp';\n        from?: string;\n        replyTo?: string;\n    };\n    sms?: {\n        provider?: 'aws-sns' | 'twilio';\n        defaultCountryCode?: string;\n    };\n    slack?: {\n        webhookUrl?: string;\n    };\n    defaults?: {\n        appName?: string;\n    };\n    /**\n     * Enable notification history tracking (requires database)\n     * @default false\n     */\n    enableHistory?: boolean;\n    /**\n     * Email engagement tracking configuration\n     */\n    tracking?: {\n        /** Enable tracking (default: false) */\n        enabled?: boolean;\n        /** HMAC secret key for token signing */\n        secret?: string;\n        /** Base URL for tracking endpoints */\n        baseUrl?: string;\n    };\n}\n\nlet globalConfig: NotificationConfig = {};\n\n/**\n * Configure notification settings\n */\nexport function configureNotification(config: NotificationConfig): void\n{\n    globalConfig = { ...globalConfig, ...config };\n}\n\n/**\n * Get current notification configuration\n */\nexport function getNotificationConfig(): NotificationConfig\n{\n    return { ...globalConfig };\n}\n\n/**\n * Get email from address\n */\nexport function getEmailFrom(): string\n{\n    return globalConfig.email?.from || env.SPFN_NOTIFICATION_EMAIL_FROM || 'noreply@example.com';\n}\n\n/**\n * Get email reply-to address\n */\nexport function getEmailReplyTo(): string | undefined\n{\n    return globalConfig.email?.replyTo;\n}\n\n/**\n * Get SMS default country code\n */\nexport function getSmsDefaultCountryCode(): string\n{\n    return globalConfig.sms?.defaultCountryCode || '+82';\n}\n\n/**\n * Get app name for templates\n */\nexport function getAppName(): string\n{\n    return globalConfig.defaults?.appName || 'SPFN';\n}\n\n/**\n * Check if history tracking is enabled\n */\nexport function isHistoryEnabled(): boolean\n{\n    return globalConfig.enableHistory ?? false;\n}\n\n/**\n * Check if tracking is enabled (config → env → false)\n */\nexport function isTrackingEnabled(): boolean\n{\n    if (globalConfig.tracking?.enabled != null)\n    {\n        return globalConfig.tracking.enabled;\n    }\n    return env.SPFN_NOTIFICATION_TRACKING_ENABLED === 'true';\n}\n\n/**\n * Get tracking HMAC secret\n */\nexport function getTrackingSecret(): string | undefined\n{\n    return globalConfig.tracking?.secret ?? env.SPFN_NOTIFICATION_TRACKING_SECRET;\n}\n\n/**\n * Get tracking base URL\n */\nexport function getTrackingBaseUrl(): string | undefined\n{\n    return globalConfig.tracking?.baseUrl ?? env.SPFN_NOTIFICATION_TRACKING_BASE_URL;\n}\n","/**\n * @spfn/notification - Environment Schema\n */\n\nimport { defineEnvSchema, envString } from '@spfn/core/env';\n\nexport const notificationEnvSchema = defineEnvSchema({\n    // Email\n    SPFN_NOTIFICATION_EMAIL_PROVIDER: {\n        ...envString({\n            description: 'Email provider (aws-ses, sendgrid, smtp)',\n            default: 'aws-ses',\n            required: false,\n            examples: ['aws-ses', 'sendgrid', 'smtp'],\n        }),\n    },\n\n    SPFN_NOTIFICATION_EMAIL_FROM: {\n        ...envString({\n            description: 'Default sender email address',\n            required: false,\n            examples: ['noreply@example.com'],\n        }),\n    },\n\n    // SMS\n    SPFN_NOTIFICATION_SMS_PROVIDER: {\n        ...envString({\n            description: 'SMS provider (aws-sns, twilio)',\n            default: 'aws-sns',\n            required: false,\n            examples: ['aws-sns', 'twilio'],\n        }),\n    },\n\n    // Slack\n    SPFN_NOTIFICATION_SLACK_WEBHOOK_URL: {\n        ...envString({\n            description: 'Slack webhook URL',\n            required: false,\n            examples: ['https://hooks.slack.com/services/xxx/xxx/xxx'],\n        }),\n    },\n\n    // Tracking\n    SPFN_NOTIFICATION_TRACKING_ENABLED: {\n        ...envString({\n            description: 'Enable email engagement tracking (open/click)',\n            default: 'false',\n            required: false,\n            examples: ['true', 'false'],\n        }),\n    },\n\n    SPFN_NOTIFICATION_TRACKING_SECRET: {\n        ...envString({\n            description: 'HMAC secret key for tracking token signing',\n            required: false,\n            sensitive: true,\n        }),\n    },\n\n    SPFN_NOTIFICATION_TRACKING_BASE_URL: {\n        ...envString({\n            description: 'Base URL for tracking endpoints',\n            required: false,\n            examples: ['https://api.example.com'],\n        }),\n    },\n\n    // AWS (shared with other AWS services)\n    AWS_REGION: {\n        ...envString({\n            description: 'AWS region',\n            default: 'ap-northeast-2',\n            required: false,\n            examples: ['ap-northeast-2', 'us-east-1'],\n        }),\n    },\n\n    AWS_ACCESS_KEY_ID: {\n        ...envString({\n            description: 'AWS access key ID',\n            required: false,\n            sensitive: true,\n        }),\n    },\n\n    AWS_SECRET_ACCESS_KEY: {\n        ...envString({\n            description: 'AWS secret access key',\n            required: false,\n            sensitive: true,\n        }),\n    },\n});\n"],"mappings":"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","names":[]}

package/dist/{index-BAe1ZBYQ.d.ts → index-DHgXI5Eq.d.ts}

@@ -61,6 +61,11 @@ interface SendEmailParams {
      * Reply-to address
      */
     replyTo?: string;
+    /**
+     * Enable/disable engagement tracking for this email.
+     * When undefined, falls back to global tracking config.
+     */
+    tracking?: boolean;
 }
 /**
  * Email provider interface

package/dist/index.d.ts

@@ -1 +1 @@
-export { g as EmailTemplateContent, N as NotificationChannel, S as SendEmailParams, a as SendResult, b as SendSMSParams, d as SendSlackParams, i as SlackTemplateContent, h as SmsTemplateContent, f as TemplateData, T as TemplateDefinition } from './index-BAe1ZBYQ.js';
+export { g as EmailTemplateContent, N as NotificationChannel, S as SendEmailParams, a as SendResult, b as SendSMSParams, d as SendSlackParams, i as SlackTemplateContent, h as SmsTemplateContent, f as TemplateData, T as TemplateDefinition } from './index-DHgXI5Eq.js';

package/dist/server.d.ts

@@ -1,8 +1,10 @@
-export { NotificationConfig, configureNotification, getAppName, getEmailFrom, getEmailReplyTo, getNotificationConfig, getSmsDefaultCountryCode } from './config/index.js';
-import { S as SendEmailParams, a as SendResult, E as EmailProvider, b as SendSMSParams, c as SMSProvider, d as SendSlackParams, e as SlackProvider, T as TemplateDefinition, f as TemplateData, N as NotificationChannel$1, R as RenderedTemplate } from './index-BAe1ZBYQ.js';
-export { g as EmailTemplateContent, i as SlackTemplateContent, h as SmsTemplateContent } from './index-BAe1ZBYQ.js';
+export { NotificationConfig, configureNotification, getAppName, getEmailFrom, getEmailReplyTo, getNotificationConfig, getSmsDefaultCountryCode, getTrackingBaseUrl, getTrackingSecret, isTrackingEnabled } from './config/index.js';
+import { S as SendEmailParams, a as SendResult, E as EmailProvider, b as SendSMSParams, c as SMSProvider, d as SendSlackParams, e as SlackProvider, T as TemplateDefinition, f as TemplateData, N as NotificationChannel$1, R as RenderedTemplate } from './index-DHgXI5Eq.js';
+export { g as EmailTemplateContent, i as SlackTemplateContent, h as SmsTemplateContent } from './index-DHgXI5Eq.js';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import * as _spfn_core_job from '@spfn/core/job';
+import * as _spfn_core_route from '@spfn/core/route';
+import * as _sinclair_typebox from '@sinclair/typebox';
 import '@spfn/core/env';
 
 /**
@@ -510,6 +512,184 @@ declare const notifications: drizzle_orm_pg_core.PgTableWithColumns<{
 type Notification = typeof notifications.$inferSelect;
 type NewNotification = typeof notifications.$inferInsert;
 
+/**
+ * @spfn/notification - Tracking Events Entity
+ *
+ * Stores email engagement tracking events (opens, clicks)
+ */
+/**
+ * Tracking event types
+ */
+declare const TRACKING_EVENT_TYPES: readonly ["open", "click"];
+type TrackingEventType = typeof TRACKING_EVENT_TYPES[number];
+/**
+ * Tracking events table - stores email engagement events
+ */
+declare const trackingEvents: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "tracking_events";
+    schema: string;
+    columns: {
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "tracking_events";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "tracking_events";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "tracking_events";
+            dataType: "number";
+            columnType: "PgBigSerial53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        notificationId: drizzle_orm_pg_core.PgColumn<{
+            name: "notification_id";
+            tableName: "tracking_events";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        type: drizzle_orm_pg_core.PgColumn<{
+            name: "type";
+            tableName: "tracking_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: "open" | "click";
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["open", "click"];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        linkUrl: drizzle_orm_pg_core.PgColumn<{
+            name: "link_url";
+            tableName: "tracking_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        linkIndex: drizzle_orm_pg_core.PgColumn<{
+            name: "link_index";
+            tableName: "tracking_events";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        ipAddress: drizzle_orm_pg_core.PgColumn<{
+            name: "ip_address";
+            tableName: "tracking_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userAgent: drizzle_orm_pg_core.PgColumn<{
+            name: "user_agent";
+            tableName: "tracking_events";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+/**
+ * Type inference
+ */
+type TrackingEvent = typeof trackingEvents.$inferSelect;
+
 /**
  * @spfn/notification - Notification Service
  *
@@ -777,4 +957,99 @@ interface ErrorSlackOptions {
  */
 declare function createErrorSlackNotifier(options?: ErrorSlackOptions): (err: Error, ctx: ErrorContext) => Promise<void>;
 
-export { type CancelResult, EmailProvider, type ErrorSlackOptions, type FindNotificationsOptions, NOTIFICATION_CHANNELS, NOTIFICATION_STATUSES, type NewNotification, type Notification, NotificationChannel$1 as NotificationChannel, type NotificationStats, type NotificationStatus, SMSProvider, type ScheduleOptions, type ScheduleResult, SendEmailParams, SendResult, SendSMSParams, SendSlackParams, SlackProvider, TemplateData, TemplateDefinition, cancelNotification, cancelNotificationsByReference, cancelScheduledNotification, countNotifications, createErrorSlackNotifier, createNotificationRecord, createScheduledNotification, findNotificationByJobId, findNotifications, findScheduledNotifications, getNotificationStats, getTemplate, getTemplateNames, hasTemplate, markNotificationFailed, markNotificationPending, markNotificationSent, notificationJobRouter, notifications, registerBuiltinTemplates, registerEmailProvider, registerFilter, registerSMSProvider, registerSlackProvider, registerTemplate, renderTemplate, scheduleEmail, scheduleSMS, sendEmail, sendEmailBulk, sendSMS, sendSMSBulk, sendScheduledEmailJob, sendScheduledSmsJob, sendSlack, sendSlackBulk, updateNotificationJobId };
+/**
+ * Tracking router
+ */
+declare const trackingRouter: _spfn_core_route.Router<{
+    trackOpen: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            token: _sinclair_typebox.TString;
+        }>;
+    }, {}, Response>;
+    trackClick: _spfn_core_route.RouteDef<{
+        params: _sinclair_typebox.TObject<{
+            token: _sinclair_typebox.TString;
+        }>;
+        query: _sinclair_typebox.TObject<{
+            url: _sinclair_typebox.TString;
+        }>;
+    }, {}, Response>;
+}>;
+
+/**
+ * @spfn/notification - Tracking HTML Processor
+ *
+ * Injects open tracking pixel and wraps links for click tracking.
+ */
+interface ProcessTrackingOptions {
+    notificationId: number;
+    baseUrl: string;
+}
+interface TrackedLink {
+    index: number;
+    url: string;
+}
+interface ProcessTrackingResult {
+    html: string;
+    trackedLinks: TrackedLink[];
+}
+/**
+ * Process HTML to inject tracking pixel and wrap links
+ *
+ * 1. Wraps <a href="..."> links with click tracking redirect URLs
+ * 2. Inserts a 1x1 transparent GIF tracking pixel before </body>
+ */
+declare function processTrackingHtml(html: string, options: ProcessTrackingOptions): ProcessTrackingResult;
+
+/**
+ * @spfn/notification - Tracking Service
+ *
+ * Records engagement events and provides analytics queries.
+ */
+
+/**
+ * Tracking stats for a single notification
+ */
+interface TrackingStats {
+    totalOpens: number;
+    uniqueOpens: number;
+    totalClicks: number;
+    uniqueClicks: number;
+}
+/**
+ * Get tracking stats for a specific notification
+ */
+declare function getTrackingStats(notificationId: number): Promise<TrackingStats>;
+/**
+ * Engagement stats across notifications
+ */
+interface EngagementStats {
+    sent: number;
+    opened: number;
+    clicked: number;
+    openRate: number;
+    clickRate: number;
+}
+/**
+ * Get engagement stats with optional filters
+ */
+declare function getEngagementStats(options?: {
+    channel?: NotificationChannel;
+    from?: Date;
+    to?: Date;
+}): Promise<EngagementStats>;
+/**
+ * Click detail for a specific link
+ */
+interface ClickDetail {
+    linkUrl: string;
+    linkIndex: number;
+    totalClicks: number;
+    uniqueClicks: number;
+}
+/**
+ * Get click details for a specific notification
+ */
+declare function getClickDetails(notificationId: number): Promise<ClickDetail[]>;
+
+export { type CancelResult, type ClickDetail, EmailProvider, type EngagementStats, type ErrorSlackOptions, type FindNotificationsOptions, NOTIFICATION_CHANNELS, NOTIFICATION_STATUSES, type NewNotification, type Notification, NotificationChannel$1 as NotificationChannel, type NotificationStats, type NotificationStatus, SMSProvider, type ScheduleOptions, type ScheduleResult, SendEmailParams, SendResult, SendSMSParams, SendSlackParams, SlackProvider, TRACKING_EVENT_TYPES, TemplateData, TemplateDefinition, type TrackingEvent, type TrackingEventType, type TrackingStats, cancelNotification, cancelNotificationsByReference, cancelScheduledNotification, countNotifications, createErrorSlackNotifier, createNotificationRecord, createScheduledNotification, findNotificationByJobId, findNotifications, findScheduledNotifications, getClickDetails, getEngagementStats, getNotificationStats, getTemplate, getTemplateNames, getTrackingStats, hasTemplate, markNotificationFailed, markNotificationPending, markNotificationSent, notificationJobRouter, notifications, processTrackingHtml, registerBuiltinTemplates, registerEmailProvider, registerFilter, registerSMSProvider, registerSlackProvider, registerTemplate, renderTemplate, scheduleEmail, scheduleSMS, sendEmail, sendEmailBulk, sendSMS, sendSMSBulk, sendScheduledEmailJob, sendScheduledSmsJob, sendSlack, sendSlackBulk, trackingEvents, trackingRouter, updateNotificationJobId };