@spfn/notification 0.1.0-beta.4 → 0.1.0-beta.5

package/README.md

@@ -4,7 +4,7 @@ Multi-channel notification system for SPFN applications.
 
 ## Features
 
-- **Multi-channel support**: Email, SMS (Slack, Push coming soon)
+- **Multi-channel support**: Email, SMS, Slack (Push coming soon)
 - **Provider pattern**: Pluggable providers (AWS SES, AWS SNS, etc.)
 - **Template system**: Variable substitution with filters
 - **Scheduled delivery**: Schedule notifications for later via pg-boss
@@ -282,6 +282,32 @@ const twilioProvider: SMSProvider = {
 registerSMSProvider(twilioProvider);
 ```
 
+## Logging & Error Handling
+
+All channels log via `@spfn/core/logger`. Logs are tagged by channel:
+
+- `@spfn/notification:email` — Email send success/failure, validation errors
+- `@spfn/notification:sms` — SMS send success/failure, validation errors
+- `@spfn/notification:slack` — Slack send success/failure, validation errors
+- `@spfn/notification:ses` — AWS SES client lifecycle, provider errors
+- `@spfn/notification:sns` — AWS SNS client lifecycle, provider errors
+
+`sendEmail`, `sendSMS`, `sendSlack` are designed to **not throw** — they return a `SendResult` object. Always check the result:
+
+```typescript
+const result = await sendEmail({
+    to: 'user@example.com',
+    template: 'welcome',
+    data: { name: 'John' },
+});
+
+if (!result.success)
+{
+    // result.error contains the failure reason
+    console.error('Email failed:', result.error);
+}
+```
+
 ## Notification History
 
 Enable history tracking to store all notifications in the database:
@@ -333,6 +359,7 @@ export type {
     SendResult,
     SendEmailParams,
     SendSMSParams,
+    SendSlackParams,
     TemplateDefinition,
     TemplateData,
 };
@@ -353,6 +380,11 @@ export {
     sendSMSBulk,
     registerSMSProvider,
 
+    // Slack
+    sendSlack,
+    sendSlackBulk,
+    registerSlackProvider,
+
     // Scheduling
     scheduleEmail,
     scheduleSMS,

package/dist/config/index.d.ts

@@ -10,6 +10,7 @@ declare const notificationEnvSchema: {
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "SPFN_NOTIFICATION_EMAIL_PROVIDER";
     };
@@ -18,6 +19,7 @@ declare const notificationEnvSchema: {
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "SPFN_NOTIFICATION_EMAIL_FROM";
     };
@@ -27,6 +29,7 @@ declare const notificationEnvSchema: {
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "SPFN_NOTIFICATION_SMS_PROVIDER";
     };
@@ -35,6 +38,7 @@ declare const notificationEnvSchema: {
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "SPFN_NOTIFICATION_SLACK_WEBHOOK_URL";
     };
@@ -44,6 +48,7 @@ declare const notificationEnvSchema: {
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "AWS_REGION";
     };
@@ -52,6 +57,7 @@ declare const notificationEnvSchema: {
         required: boolean;
         sensitive: boolean;
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "AWS_ACCESS_KEY_ID";
     };
@@ -60,6 +66,7 @@ declare const notificationEnvSchema: {
         required: boolean;
         sensitive: boolean;
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "AWS_SECRET_ACCESS_KEY";
     };
@@ -72,6 +79,7 @@ declare const env: _spfn_core_env.InferEnvType<{
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "SPFN_NOTIFICATION_EMAIL_PROVIDER";
     };
@@ -80,6 +88,7 @@ declare const env: _spfn_core_env.InferEnvType<{
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "SPFN_NOTIFICATION_EMAIL_FROM";
     };
@@ -89,6 +98,7 @@ declare const env: _spfn_core_env.InferEnvType<{
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "SPFN_NOTIFICATION_SMS_PROVIDER";
     };
@@ -97,6 +107,7 @@ declare const env: _spfn_core_env.InferEnvType<{
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "SPFN_NOTIFICATION_SLACK_WEBHOOK_URL";
     };
@@ -106,6 +117,7 @@ declare const env: _spfn_core_env.InferEnvType<{
         required: boolean;
         examples: string[];
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "AWS_REGION";
     };
@@ -114,6 +126,7 @@ declare const env: _spfn_core_env.InferEnvType<{
         required: boolean;
         sensitive: boolean;
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "AWS_ACCESS_KEY_ID";
     };
@@ -122,6 +135,7 @@ declare const env: _spfn_core_env.InferEnvType<{
         required: boolean;
         sensitive: boolean;
         type: "string";
+        validator: (value: string) => string;
     } & {
         key: "AWS_SECRET_ACCESS_KEY";
     };

package/dist/server.d.ts

@@ -627,13 +627,13 @@ declare function cancelNotificationsByReference(referenceType: string, reference
  * Scheduled email sending job
  */
 declare const sendScheduledEmailJob: _spfn_core_job.JobDef<{
+    from?: string | undefined;
     subject?: string | undefined;
     html?: string | undefined;
     text?: string | undefined;
     data?: {
         [x: string]: unknown;
     } | undefined;
-    from?: string | undefined;
     template?: string | undefined;
     replyTo?: string | undefined;
     to: string | string[];
@@ -678,13 +678,13 @@ declare const sendScheduledSmsJob: _spfn_core_job.JobDef<{
  */
 declare const notificationJobRouter: _spfn_core_job.JobRouter<{
     sendScheduledEmail: _spfn_core_job.JobDef<{
+        from?: string | undefined;
         subject?: string | undefined;
         html?: string | undefined;
         text?: string | undefined;
         data?: {
             [x: string]: unknown;
         } | undefined;
-        from?: string | undefined;
         template?: string | undefined;
         replyTo?: string | undefined;
         to: string | string[];

package/dist/server.js

@@ -95,6 +95,8 @@ function isHistoryEnabled() {
 }
 
 // src/channels/email/providers/aws-ses.ts
+import { logger } from "@spfn/core/logger";
+var log = logger.child("@spfn/notification:ses");
 var sesClient = null;
 async function getSESClient() {
   if (sesClient) {
@@ -109,6 +111,7 @@ async function getSESClient() {
         secretAccessKey: env.AWS_SECRET_ACCESS_KEY
       } : void 0
     });
+    log.debug("SES client created", { region: env.AWS_REGION });
     return sesClient;
   } catch {
     throw new Error(
@@ -156,6 +159,7 @@ var awsSesProvider = {
       };
     } catch (error) {
       const err = error;
+      log.error("SES send failed", err, { to: params.to, from: params.from });
       return {
         success: false,
         error: err.message
@@ -630,6 +634,8 @@ async function findScheduledNotifications(options = {}) {
 }
 
 // src/channels/email/index.ts
+import { logger as logger2 } from "@spfn/core/logger";
+var log2 = logger2.child("@spfn/notification:email");
 var providers = {
   "aws-ses": awsSesProvider
 };
@@ -651,6 +657,7 @@ async function sendEmail(params) {
   let html = params.html;
   if (params.template) {
     if (!hasTemplate(params.template)) {
+      log2.warn(`Template not found: ${params.template}`);
       return {
         success: false,
         error: `Template not found: ${params.template}`
@@ -664,12 +671,14 @@ async function sendEmail(params) {
     }
   }
   if (!subject) {
+    log2.warn("Email subject is required", { to: recipients });
     return {
       success: false,
       error: "Email subject is required"
     };
   }
   if (!text2 && !html) {
+    log2.warn("Email content (text or html) is required", { to: recipients, subject });
     return {
       success: false,
       error: "Email content (text or html) is required"
@@ -697,10 +706,16 @@ async function sendEmail(params) {
         providerName: provider.name
       });
       historyId = record.id;
-    } catch {
+    } catch (error) {
+      log2.warn("Failed to create notification history record", error);
     }
   }
   const result = await provider.send(internalParams);
+  if (result.success) {
+    log2.info("Email sent", { to: recipients, subject, messageId: result.messageId });
+  } else {
+    log2.error("Email send failed", { to: recipients, subject, error: result.error });
+  }
   if (historyId && isHistoryEnabled()) {
     try {
       if (result.success) {
@@ -708,7 +723,8 @@ async function sendEmail(params) {
       } else {
         await markNotificationFailed(historyId, result.error || "Unknown error");
       }
-    } catch {
+    } catch (error) {
+      log2.warn("Failed to update notification history record", error);
     }
   }
   return result;
@@ -730,6 +746,8 @@ async function sendEmailBulk(items) {
 }
 
 // src/channels/sms/providers/aws-sns.ts
+import { logger as logger3 } from "@spfn/core/logger";
+var log3 = logger3.child("@spfn/notification:sns");
 var snsClient = null;
 async function getSNSClient() {
   if (snsClient) {
@@ -744,6 +762,7 @@ async function getSNSClient() {
         secretAccessKey: env.AWS_SECRET_ACCESS_KEY
       } : void 0
     });
+    log3.debug("SNS client created", { region: env.AWS_REGION });
     return snsClient;
   } catch {
     throw new Error(
@@ -774,6 +793,7 @@ var awsSnsProvider = {
       };
     } catch (error) {
       const err = error;
+      log3.error("SNS send failed", err, { to: params.to });
       return {
         success: false,
         error: err.message
@@ -796,6 +816,8 @@ function normalizePhoneNumber(phone, defaultCountryCode) {
 }
 
 // src/channels/sms/index.ts
+import { logger as logger4 } from "@spfn/core/logger";
+var log4 = logger4.child("@spfn/notification:sms");
 var providers2 = {
   "aws-sns": awsSnsProvider
 };
@@ -815,6 +837,7 @@ async function sendSMS(params) {
   let message = params.message;
   if (params.template) {
     if (!hasTemplate(params.template)) {
+      log4.warn(`Template not found: ${params.template}`);
       return {
         success: false,
         error: `Template not found: ${params.template}`
@@ -826,6 +849,7 @@ async function sendSMS(params) {
     }
   }
   if (!message) {
+    log4.warn("SMS message is required", { to: recipients });
     return {
       success: false,
       error: "SMS message is required"
@@ -851,10 +875,16 @@ async function sendSMS(params) {
           providerName: provider.name
         });
         historyId = record.id;
-      } catch {
+      } catch (error) {
+        log4.warn("Failed to create notification history record", error);
       }
     }
     const result = await provider.send(internalParams);
+    if (result.success) {
+      log4.info("SMS sent", { to: normalizedPhone, messageId: result.messageId });
+    } else {
+      log4.error("SMS send failed", { to: normalizedPhone, error: result.error });
+    }
     if (historyId && isHistoryEnabled()) {
       try {
         if (result.success) {
@@ -862,7 +892,8 @@ async function sendSMS(params) {
         } else {
           await markNotificationFailed(historyId, result.error || "Unknown error");
         }
-      } catch {
+      } catch (error) {
+        log4.warn("Failed to update notification history record", error);
       }
     }
     results.push(result);
@@ -893,6 +924,8 @@ async function sendSMSBulk(items) {
 }
 
 // src/channels/slack/providers/webhook.ts
+import { logger as logger5 } from "@spfn/core/logger";
+var log5 = logger5.child("@spfn/notification:slack-webhook");
 var webhookProvider = {
   name: "webhook",
   async send(params) {
@@ -911,6 +944,7 @@ var webhookProvider = {
       };
     } catch (error) {
       const err = error;
+      log5.error("Webhook request failed", err);
       return {
         success: false,
         error: err.message
@@ -920,6 +954,8 @@ var webhookProvider = {
 };
 
 // src/channels/slack/index.ts
+import { logger as logger6 } from "@spfn/core/logger";
+var log6 = logger6.child("@spfn/notification:slack");
 var providers3 = {
   "webhook": webhookProvider
 };
@@ -935,6 +971,7 @@ function resolveWebhookUrl(params) {
 async function sendSlack(params) {
   const webhookUrl = resolveWebhookUrl(params);
   if (!webhookUrl) {
+    log6.warn("Slack webhook URL is required");
     return {
       success: false,
       error: "Slack webhook URL is required. Set SPFN_NOTIFICATION_SLACK_WEBHOOK_URL or pass webhookUrl."
@@ -944,6 +981,7 @@ async function sendSlack(params) {
   let blocks = params.blocks;
   if (params.template) {
     if (!hasTemplate(params.template)) {
+      log6.warn(`Template not found: ${params.template}`);
       return {
         success: false,
         error: `Template not found: ${params.template}`
@@ -956,6 +994,7 @@ async function sendSlack(params) {
     }
   }
   if (!text2 && !blocks) {
+    log6.warn("Slack message requires text or blocks");
     return {
       success: false,
       error: "Slack message requires text or blocks"
@@ -979,10 +1018,16 @@ async function sendSlack(params) {
         providerName: provider.name
       });
       historyId = record.id;
-    } catch {
+    } catch (error) {
+      log6.warn("Failed to create notification history record", error);
     }
   }
   const result = await provider.send(internalParams);
+  if (result.success) {
+    log6.info("Slack message sent");
+  } else {
+    log6.error("Slack send failed", { error: result.error });
+  }
   if (historyId && isHistoryEnabled()) {
     try {
       if (result.success) {
@@ -990,7 +1035,8 @@ async function sendSlack(params) {
       } else {
         await markNotificationFailed(historyId, result.error || "Unknown error");
       }
-    } catch {
+    } catch (error) {
+      log6.warn("Failed to update notification history record", error);
     }
   }
   return result;