feat: add email notifications for new document creation

Author: HMarzban

.env.example

@@ -231,6 +231,31 @@ WEBAPP_REPLICAS=2
 BUILD_ID=development-build
 GIT_HASH=dev
 
+# =============================================================================
+# EMAIL - Notification Service (SMTP via Nodemailer)- optional and will be removed soon
+# =============================================================================
+# Sends email notifications when new documents are created.
+# Requires: bun add nodemailer
+
+# Common settings
+EMAIL_FROM=[email protected]
+NEW_DOCUMENT_NOTIFICATION_EMAILS=[email protected],[email protected]
+APP_URL=https://yourdomain.com
+EMAIL_LOG_LEVEL=
+
+# SMTP Configuration
+# Gmail: Use App Password (not your regular password)
+# Setup guide: https://support.google.com/accounts/answer/185833
+# 1. Enable 2FA on Gmail
+# 2. Go to: https://myaccount.google.com/apppasswords
+# 3. Generate app password for "Mail"
+# 4. Use that 16-char password below
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USER=[email protected]
+SMTP_PASS=your-16-char-app-password
+SMTP_SECURE=false
+
 # =============================================================================
 # ANALYTICS & EXTERNAL SERVICES
 # =============================================================================

bun.lock

@@ -164,6 +164,27 @@ STORAGE_S3_LOG_LEVEL=
 # Security & Auth
 JWT_LOG_LEVEL=
 
+# Email
+EMAIL_LOG_LEVEL=debug
+
+# ============================================
+# Email Notifications (SMTP via Nodemailer)
+# ============================================
+
+# Common settings
+EMAIL_FROM=dev@localhost
+NEW_DOCUMENT_NOTIFICATION_EMAILS=
+APP_URL=http://localhost:3000
+
+# SMTP Configuration
+# For local testing, use Mailpit: docker run -p 1025:1025 -p 8025:8025 axllent/mailpit
+# View emails at: http://localhost:8025
+SMTP_HOST=host.docker.internal
+SMTP_PORT=1025
+SMTP_USER=
+SMTP_PASS=
+SMTP_SECURE=false
+
 # ============================================
 # Development Settings
 # ============================================

packages/hocuspocus.server/docker/config-templates/env.development

@@ -176,3 +176,24 @@ STORAGE_S3_LOG_LEVEL=
 # Security & Auth
 JWT_LOG_LEVEL=
 
+# Email
+EMAIL_LOG_LEVEL=
+
+# ============================================
+# Email Notifications (SMTP via Nodemailer)
+# ============================================
+
+# Common settings
+[email protected]
+[email protected]
+APP_URL=https://yourdomain.com
+
+# SMTP Configuration
+# Gmail: Use App Password (not your regular password)
+# Setup: https://support.google.com/accounts/answer/185833
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+[email protected]
+SMTP_PASS=your-16-char-app-password
+SMTP_SECURE=false
+

packages/hocuspocus.server/docker/config-templates/env.production

@@ -160,3 +160,22 @@ STORAGE_S3_LOG_LEVEL=
 # Security & Auth
 JWT_LOG_LEVEL=
 
+# Email
+EMAIL_LOG_LEVEL=
+
+# ============================================
+# Email Notifications (SMTP via Nodemailer)
+# ============================================
+
+# Common settings
+[email protected]
+[email protected]
+APP_URL=https://staging.yourdomain.com
+
+# SMTP Configuration
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+[email protected]
+SMTP_PASS=password
+SMTP_SECURE=false
+

packages/hocuspocus.server/docker/config-templates/env.staging

@@ -25,6 +25,7 @@
   "type": "module",
   "devDependencies": {
     "@types/jsonwebtoken": "^9.0.10",
+    "@types/nodemailer": "^6.4.14",
     "@types/pg": "^8.15.6",
     "bun-types": "latest",
     "prisma": "^6.19.0"
@@ -51,6 +52,7 @@
     "ioredis": "^5.8.2",
     "jsonwebtoken": "^9.0.2",
     "mime": "^4.1.0",
+    "nodemailer": "^6.9.15",
     "pg": "^8.16.3",
     "pino": "^10.1.0",
     "pino-http": "^11.0.0",

packages/hocuspocus.server/package.json

@@ -1,5 +1,5 @@
 import type { PrismaClient } from '@prisma/client'
-import { extractUserFromToken } from '../../utils'
+import { extractUserFromToken } from '../utils/auth'
 import * as documentsService from '../services/documents.service'
 import * as mediaService from '../services/media.service'
 import { documentsControllerLogger } from '../../lib/logger'
@@ -11,7 +11,7 @@ export const getDocumentBySlug = async (c: any) => {
   const { userId } = c.req.valid('query')
   const token = c.req.header('token')
 
-  const user = extractUserFromToken(token, userId)
+  const user = await extractUserFromToken(token, userId)
 
   try {
     const doc = await documentsService.getDocumentBySlug(prisma, docName)

packages/hocuspocus.server/src/api/controllers/documents.controller.ts

@@ -0,0 +1,20 @@
+import { verifySupabaseToken } from '../../utils/jwt'
+
+/**
+ * Extract user from token for REST API controllers
+ * Used when token and userId are provided separately
+ */
+export const extractUserFromToken = async (
+  token?: string,
+  userId?: string
+): Promise<{ sub: string; email?: string; user_metadata?: any } | null> => {
+  if (!token || !userId) return null
+
+  const user = await verifySupabaseToken(token)
+
+  if (!user || user.sub !== userId) {
+    return null
+  }
+
+  return user
+}

packages/hocuspocus.server/src/api/utils/auth.ts

@@ -71,6 +71,23 @@ export const config = {
       .map((origin) => origin.trim())
       .filter(Boolean),
     rateLimitMax: parseInt(process.env.RATE_LIMIT_MAX || '100', 10)
+  },
+
+  // Email (SMTP via Nodemailer)
+  email: {
+    fromEmail: process.env.EMAIL_FROM || process.env.SMTP_USER || '[email protected]',
+    notificationEmails: (process.env.NEW_DOCUMENT_NOTIFICATION_EMAILS || '')
+      .split(',')
+      .map((email) => email.trim())
+      .filter((email) => email.length > 0 && email.includes('@')),
+    appUrl: process.env.APP_URL || 'https://docs.plus',
+    smtp: {
+      host: process.env.SMTP_HOST || '',
+      port: parseInt(process.env.SMTP_PORT || '587', 10),
+      secure: process.env.SMTP_SECURE === 'true',
+      user: process.env.SMTP_USER || '',
+      pass: process.env.SMTP_PASS || ''
+    }
   }
 } as const
 

packages/hocuspocus.server/src/config/env.ts

@@ -90,31 +90,30 @@ const configureExtensions = () => {
         const ydoc = new Y.Doc()
         Y.applyUpdate(ydoc, state)
         const meta = ydoc.getMap('metadata')
-        const commitMessage = meta.get('commitMessage') || ''
+        const commitMessageValue = meta.get('commitMessage')
+        const commitMessage = typeof commitMessageValue === 'string' ? commitMessageValue : ''
         const isDraft = meta.get('isDraft') || false
-        let firstCreation = false
 
         meta.delete('commitMessage')
 
         // If the document is draft, don't store the data
         if (isDraft) return
 
+        // Clean up draft flag after first save
         if (meta.has('isDraft')) {
           meta.delete('isDraft')
-          firstCreation = true
         }
 
         // Create a new Y.Doc to store the updated state
         Y.applyUpdate(ydoc, state)
         const newState = Y.encodeStateAsUpdate(ydoc)
 
-        // Add job to queue
+        // Add job to queue (firstCreation is determined in worker by checking DB)
         await StoreDocumentQueue.add('store-document', {
           documentName,
           state: Buffer.from(newState).toString('base64'),
           context,
-          commitMessage,
-          firstCreation
+          commitMessage
         })
       }
     })