@spfn/notification 0.1.0-beta.1 → 0.1.0-beta.10

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/{index-D_XTwHmO.d.ts → index-BAe1ZBYQ.d.ts}

@@ -119,6 +119,50 @@ interface InternalSendSMSParams {
     message: string;
 }
 
+/**
+ * @spfn/notification - Slack Channel Types
+ */
+
+/**
+ * Parameters for sending Slack message
+ */
+interface SendSlackParams {
+    /**
+     * Webhook URL (overrides env/config default)
+     */
+    webhookUrl?: string;
+    /**
+     * Plain text message
+     */
+    text?: string;
+    /**
+     * Slack Block Kit blocks
+     */
+    blocks?: unknown[];
+    /**
+     * Template name
+     */
+    template?: string;
+    /**
+     * Template data for variable substitution
+     */
+    data?: Record<string, unknown>;
+}
+/**
+ * Slack provider interface
+ */
+interface SlackProvider extends ChannelProvider<InternalSendSlackParams> {
+    name: 'webhook' | string;
+}
+/**
+ * Internal send Slack params (after template rendering)
+ */
+interface InternalSendSlackParams {
+    webhookUrl: string;
+    text?: string;
+    blocks?: unknown[];
+}
+
 /**
  * @spfn/notification - Template Types
  */
@@ -167,4 +211,4 @@ interface RenderedTemplate {
  */
 type TemplateData = Record<string, unknown>;
 
-export type { EmailProvider as E, NotificationChannel as N, RenderedTemplate as R, SendEmailParams as S, TemplateDefinition as T, SendResult as a, SendSMSParams as b, SMSProvider as c, TemplateData as d, EmailTemplateContent as e, SmsTemplateContent as f, SlackTemplateContent as g };
+export type { EmailProvider as E, NotificationChannel as N, RenderedTemplate as R, SendEmailParams as S, TemplateDefinition as T, SendResult as a, SendSMSParams as b, SMSProvider as c, SendSlackParams as d, SlackProvider as e, TemplateData as f, EmailTemplateContent as g, SmsTemplateContent as h, SlackTemplateContent as i };

package/dist/index.d.ts

@@ -1 +1 @@
-export { e as EmailTemplateContent, N as NotificationChannel, S as SendEmailParams, a as SendResult, b as SendSMSParams, g as SlackTemplateContent, f as SmsTemplateContent, d as TemplateData, T as TemplateDefinition } from './index-D_XTwHmO.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-BAe1ZBYQ.js';

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 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, T as TemplateDefinition, d as TemplateData, N as NotificationChannel$1, R as RenderedTemplate } from './index-D_XTwHmO.js';
-export { e as EmailTemplateContent, g as SlackTemplateContent, f as SmsTemplateContent } from './index-D_XTwHmO.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';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import * as _spfn_core_job from '@spfn/core/job';
 import '@spfn/core/env';
@@ -47,6 +47,27 @@ declare function sendSMSBulk(items: SendSMSParams[]): Promise<{
     failureCount: number;
 }>;
 
+/**
+ * @spfn/notification - Slack Channel
+ */
+
+/**
+ * Register custom Slack provider
+ */
+declare function registerSlackProvider(provider: SlackProvider): void;
+/**
+ * Send Slack message
+ */
+declare function sendSlack(params: SendSlackParams): Promise<SendResult>;
+/**
+ * Send bulk Slack messages
+ */
+declare function sendSlackBulk(items: SendSlackParams[]): Promise<{
+    results: SendResult[];
+    successCount: number;
+    failureCount: number;
+}>;
+
 /**
  * @spfn/notification - Schedule Service
  *
@@ -606,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[];
@@ -657,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[];
@@ -680,4 +701,80 @@ declare const notificationJobRouter: _spfn_core_job.JobRouter<{
     }, void>;
 }>;
 
-export { type CancelResult, EmailProvider, 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, TemplateData, TemplateDefinition, cancelNotification, cancelNotificationsByReference, cancelScheduledNotification, countNotifications, createNotificationRecord, createScheduledNotification, findNotificationByJobId, findNotifications, findScheduledNotifications, getNotificationStats, getTemplate, getTemplateNames, hasTemplate, markNotificationFailed, markNotificationPending, markNotificationSent, notificationJobRouter, notifications, registerBuiltinTemplates, registerEmailProvider, registerFilter, registerSMSProvider, registerTemplate, renderTemplate, scheduleEmail, scheduleSMS, sendEmail, sendEmailBulk, sendSMS, sendSMSBulk, sendScheduledEmailJob, sendScheduledSmsJob, updateNotificationJobId };
+/**
+ * @spfn/notification - Error → Slack Integration
+ *
+ * Factory for creating an onError callback that sends error notifications to Slack.
+ *
+ * @example
+ * ```typescript
+ * import { createServer } from '@spfn/core/server';
+ * import { createErrorSlackNotifier } from '@spfn/notification/server';
+ *
+ * await createServer({
+ *     middleware: {
+ *         onError: createErrorSlackNotifier({ minStatusCode: 500 }),
+ *     },
+ * });
+ * ```
+ */
+interface ErrorContext {
+    statusCode: number;
+    path: string;
+    method: string;
+    requestId?: string;
+    timestamp: string;
+    userId?: string;
+    request: {
+        headers: Record<string, string>;
+        query: Record<string, string>;
+    };
+}
+interface ErrorSlackOptions {
+    /**
+     * Minimum status code to trigger notification
+     * @default 500
+     */
+    minStatusCode?: number;
+    /**
+     * Throttle window in milliseconds.
+     * Duplicate errors (same name + statusCode + path) within this window are suppressed.
+     * @default 60_000
+     */
+    throttleMs?: number;
+    /**
+     * Webhook URL override (defaults to env/config)
+     */
+    webhookUrl?: string;
+    /**
+     * Custom message formatter
+     */
+    formatMessage?: (err: Error, ctx: ErrorContext) => {
+        text?: string;
+        blocks?: unknown[];
+    };
+}
+/**
+ * Create an onError callback that sends Slack notifications
+ *
+ * Returns a function matching ErrorHandler's onError signature.
+ * Duplicate errors (same name + statusCode + path) within `throttleMs` are suppressed.
+ *
+ * @deprecated Use `createMonitorErrorHandler()` from `@spfn/monitor/server` instead.
+ * It provides DB-backed error tracking with fingerprint deduplication,
+ * state-based notifications (new/reopened), and an admin dashboard.
+ *
+ * Migration:
+ * ```typescript
+ * // Before
+ * import { createErrorSlackNotifier } from '@spfn/notification/server';
+ * middleware: { onError: createErrorSlackNotifier() }
+ *
+ * // After
+ * import { createMonitorErrorHandler } from '@spfn/monitor/server';
+ * middleware: { onError: createMonitorErrorHandler() }
+ * ```
+ */
+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 };