Sana Module¶

Overview¶

The Sana module (located at packages/app/src/sana) provides WhatsApp bot integration for the Delta platform. It handles WhatsApp message processing, user interactions, and is deployed as a Vercel API Function within the main app.

Purpose¶

WhatsApp message handling and processing
User authentication and opt-in management
Integration with Delta's services via direct imports
Message formatting and delivery

Technology Stack¶

Runtime: Node.js with TypeScript (as part of Next.js app)
Deployment: Vercel API Functions
Testing: Jest with comprehensive test coverage
Logging: Uses Sana-specific logger
HTTP Client: Alova for WhatsApp API requests

Key Components¶

Main Service¶

Location: packages/app/src/sana/src/index.ts
Purpose: Main entry point for WhatsApp bot
Features:
WhatsApp webhook handling
Message processing pipeline
User authentication

Library Components¶

Location: packages/app/src/sana/src/lib/
Purpose: Core WhatsApp bot functionality
Features:
Logger utilities
Message processors
Helper functions

Development¶

Local Development¶

Since Sana is now part of the app package, development is integrated:

# Start the app development server (includes Sana API routes)
cd packages/app
yarn dev

Environment Setup¶

Add to packages/app/.env.local:

WhatsApp API credentials
Webhook verification token
WhatsApp business phone number
Meta API endpoints

Testing¶

Unit Tests¶

# Run all app tests (includes Sana tests)
cd packages/app
yarn test

# Run only Sana tests
yarn test src/sana

Test Configuration¶

Jest Config: jest.config.js
Test Setup: jest.setup.js
Test Files: *.test.ts files alongside source code

Build and Deployment¶

Production Build¶

# Build TypeScript
yarn run build

# The built files will be in the dist/ directory

Module Structure¶

Sana is integrated within the app's structure:

API Route: packages/app/src/app/api/sana/webhook/route.ts
Services: packages/app/src/sana/src/services/
Utilities: packages/app/src/sana/src/lib/

Configuration¶

tsconfig.json - TypeScript configuration
package.json - Dependencies and scripts
.env.local.example - Environment variables template

Dependencies¶

Sana uses the app's dependencies plus:

WhatsApp-specific¶

Alova for WhatsApp API requests
Direct imports from app services and types

Integration¶

Sana is accessed via:

API endpoint: /api/sana/webhook
Direct imports within the app

Integration Points¶

App Services: Direct access to user, notification, and other services
Database: Uses app's database helpers and Supabase client
WhatsApp API: Communicates with Meta's WhatsApp Business API

WhatsApp Features¶

Message Handling¶

Webhook verification
Message processing pipeline
Response formatting

User Management¶

WhatsApp opt-in/opt-out
User authentication via phone number
Preference management

Error Handling¶

Comprehensive error handling for API failures
Retry mechanisms with exponential backoff
Rate limiting compliance
Graceful degradation

Monitoring and Logging¶

Integration with @delta/common logger
Request/response logging
Performance metrics
Error tracking and alerting

Usage Examples¶

// In API route: packages/app/src/app/api/sana/webhook/route.ts
import { processWhatsAppMessage } from '@/sana/src/services/messageService';

// Handle incoming WhatsApp webhook
export async function POST(request: Request) {
  const body = await request.json();
  await processWhatsAppMessage(body);
  return Response.json({ status: 'ok' });
}

Best Practices¶

Error Handling: Always handle WhatsApp API errors gracefully
Rate Limiting: Respect WhatsApp API rate limits
User Privacy: Handle phone numbers and messages securely
Opt-in Management: Always verify user consent
Testing: Test webhook handling and message processing

Troubleshooting¶

Common Issues¶

Authentication Errors: Check API credentials and tokens
Rate Limiting: Implement proper retry mechanisms
Network Issues: Handle timeouts and connection errors
Data Validation: Ensure data format compliance

Debug Mode¶

Enable debug logging in development:

# Sana uses its own logger which outputs to console in development
cd packages/app
yarn dev