@checkstack/notification-smtp-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# @checkstack/notification-smtp-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/notification-backend@0.0.2
+
+## 0.0.4
+
+### Patch Changes
+
+- a65e002: Add compile-time type safety for Lucide icon names
+
+  - Add `LucideIconName` type and `lucideIconSchema` Zod schema to `@checkstack/common`
+  - Update backend interfaces (`AuthStrategy`, `NotificationStrategy`, `IntegrationProvider`, `CommandDefinition`) to use `LucideIconName`
+  - Update RPC contracts to use `lucideIconSchema` for proper type inference across RPC boundaries
+  - Simplify `SocialProviderButton` to use `DynamicIcon` directly (removes 30+ lines of pascalCase conversion)
+  - Replace static `iconMap` in `SearchDialog` with `DynamicIcon` for dynamic icon rendering
+  - Add fallback handling in `DynamicIcon` when icon name isn't found
+  - Fix legacy kebab-case icon names to PascalCase: `mail`→`Mail`, `send`→`Send`, `github`→`Github`, `key-round`→`KeyRound`, `network`→`Network`, `AlertCircle`→`CircleAlert`
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/notification-backend@0.1.2
+  - @checkstack/common@0.2.0
+
+## 0.0.3
+
+### Patch Changes
+
+- @checkstack/notification-backend@0.1.1
+
+## 0.0.2
+
+### Patch Changes
+
+- b354ab3: # Strategy Instructions Support & Telegram Notification Plugin
+
+  ## Strategy Instructions Interface
+
+  Added `adminInstructions` and `userInstructions` optional fields to the `NotificationStrategy` interface. These allow strategies to export markdown-formatted setup guides that are displayed in the configuration UI:
+
+  - **`adminInstructions`**: Shown when admins configure platform-wide strategy settings (e.g., how to create API keys)
+  - **`userInstructions`**: Shown when users configure their personal settings (e.g., how to link their account)
+
+  ### Updated Components
+
+  - `StrategyConfigCard` now accepts an `instructions` prop and renders it before config sections
+  - `StrategyCard` passes `adminInstructions` to `StrategyConfigCard`
+  - `UserChannelCard` renders `userInstructions` when users need to connect
+
+  ## New Telegram Notification Plugin
+
+  Added `@checkstack/notification-telegram-backend` plugin for sending notifications via Telegram:
+
+  - Uses [grammY](https://grammy.dev/) framework for Telegram Bot API integration
+  - Sends messages with MarkdownV2 formatting and inline keyboard buttons for actions
+  - Includes comprehensive admin instructions for bot setup via @BotFather
+  - Includes user instructions for account linking
+
+  ### Configuration
+
+  Admins need to configure a Telegram Bot Token obtained from @BotFather.
+
+  ### User Linking
+
+  The strategy uses `contactResolution: { type: "custom" }` for Telegram Login Widget integration. Full frontend integration for the Login Widget is pending future work.
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/notification-backend@0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@checkstack/notification-smtp-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/notification-backend": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "nodemailer": "^7.0.3",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/nodemailer": "^6.4.17",
+    "@checkstack/tsconfig": "workspace:*",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,194 @@
+import {
+  createBackendPlugin,
+  type NotificationStrategy,
+  Versioned,
+  configString,
+  markdownToHtml,
+  markdownToPlainText,
+  wrapInEmailLayout,
+  configNumber,
+  configBoolean,
+} from "@checkstack/backend-api";
+import { notificationStrategyExtensionPoint } from "@checkstack/notification-backend";
+import { z } from "zod";
+import { createTransport, type Transporter } from "nodemailer";
+import { pluginMetadata } from "./plugin-metadata";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// SMTP Configuration Schema
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * SMTP configuration schema with versioning support.
+ * Uses configString with x-secret for sensitive fields.
+ */
+const smtpConfigSchemaV1 = z.object({
+  host: configString({}).optional().describe("SMTP server hostname"),
+  port: configNumber({}).default(587).describe("SMTP server port"),
+  secure: configBoolean({}).default(false).describe("Use TLS/SSL (port 465)"),
+  username: configString({ "x-secret": true })
+    .describe("SMTP username")
+    .optional(),
+  password: configString({ "x-secret": true })
+    .describe("SMTP password")
+    .optional(),
+  fromAddress: configString({})
+    .email()
+    .optional()
+    .describe("Sender email address"),
+  fromName: configString({}).optional().describe("Sender display name"),
+});
+
+type SmtpConfig = z.infer<typeof smtpConfigSchemaV1>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Email Layout Configuration Schema (Admin-Customizable)
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Layout configuration for email styling.
+ * Admins can customize branding via the settings UI.
+ */
+const smtpLayoutConfigSchemaV1 = z.object({
+  logoUrl: configString({})
+    .url()
+    .optional()
+    .describe("Logo URL (max 200px wide)"),
+  primaryColor: configString({ "x-color": true })
+    .describe("Primary brand color (hex)")
+    .default("#3b82f6"),
+  accentColor: configString({ "x-color": true })
+    .describe("Accent color for buttons")
+    .optional(),
+  footerText: configString({})
+    .default("This is an automated notification.")
+    .describe("Footer text"),
+});
+
+type SmtpLayoutConfig = z.infer<typeof smtpLayoutConfigSchemaV1>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// SMTP Strategy Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const smtpStrategy: NotificationStrategy<
+  SmtpConfig,
+  undefined,
+  SmtpLayoutConfig
+> = {
+  id: "smtp",
+  displayName: "Email (SMTP)",
+  description: "Send notifications via email using SMTP",
+  icon: "Mail",
+
+  config: new Versioned({
+    version: 1,
+    schema: smtpConfigSchemaV1,
+  }),
+
+  layoutConfig: new Versioned({
+    version: 1,
+    schema: smtpLayoutConfigSchemaV1,
+  }),
+
+  contactResolution: { type: "auth-email" },
+
+  adminInstructions: `
+## SMTP Configuration
+
+Configure your SMTP server to enable email notifications:
+
+1. Enter your SMTP server **hostname** and **port** (587 for TLS, 465 for SSL)
+2. If authentication is required, provide **username** and **password**
+3. Set the **sender email address** (must be valid for your mail server)
+4. Optionally configure a **display name** for the sender
+
+> **Tip**: For Gmail, use \`smtp.gmail.com\` port 587 with an App Password.
+`.trim(),
+
+  async send({ contact, notification, strategyConfig, layoutConfig }) {
+    // Validate required config
+    if (!strategyConfig.host || !strategyConfig.fromAddress) {
+      return {
+        success: false,
+        error: "SMTP is not configured. Please configure host and fromAddress.",
+      };
+    }
+
+    // Create transporter
+    const transporter: Transporter = createTransport({
+      host: strategyConfig.host,
+      port: strategyConfig.port,
+      secure: strategyConfig.secure,
+      auth: strategyConfig.username
+        ? {
+            user: strategyConfig.username,
+            pass: strategyConfig.password,
+          }
+        : undefined,
+    });
+
+    // Construct sender field
+    const from = strategyConfig.fromName
+      ? `"${strategyConfig.fromName}" <${strategyConfig.fromAddress}>`
+      : strategyConfig.fromAddress;
+
+    // Convert markdown body to HTML (if provided)
+    const bodyHtml = notification.body ? markdownToHtml(notification.body) : "";
+
+    // Generate plain text fallback
+    const plainText = notification.body
+      ? markdownToPlainText(notification.body)
+      : notification.title;
+
+    // Wrap content in the email layout with admin customizations
+    const html = wrapInEmailLayout({
+      title: notification.title,
+      bodyHtml,
+      importance: notification.importance,
+      action: notification.action,
+      logoUrl: layoutConfig?.logoUrl,
+      primaryColor: layoutConfig?.primaryColor,
+      accentColor: layoutConfig?.accentColor,
+      footerText: layoutConfig?.footerText,
+    });
+
+    try {
+      const result = await transporter.sendMail({
+        from,
+        to: contact,
+        subject: notification.title,
+        text: plainText,
+        html,
+      });
+
+      return {
+        success: true,
+        externalId: result.messageId,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  },
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the notification strategy extension point
+    const extensionPoint = env.getExtensionPoint(
+      notificationStrategyExtensionPoint
+    );
+
+    // Register the SMTP strategy with our plugin metadata
+    extensionPoint.addStrategy(smtpStrategy, pluginMetadata);
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Notification SMTP backend.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "notification-smtp",
+});

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json"
+}