End-to-End Integration Example

To help developers consume the src/lib/sms.ts utility module, this chapter outlines a production-grade orchestration inside a Next.js Server Action or API Route lifecycle.

This model handles incoming request payloads, triggers template building, passes numbers through the normalization layer, and executes the remote BongaTech gateway dispatch.

Workflow Implementation Pattern

typescriptCopy
'use server';

import { sendSms, buildSmsTemplate } from '@/lib/sms';

interface PaymentReceiptPayload {
  customerName: string;
  phone: string;
  amount: number;
  receiptNumber: string;
}

interface ActionResponse {
  success: boolean;
  messageId?: string;
  error?: string;
}

/**
 * Server Action to process a payment confirmation and dispatch an SMS receipt via BongaTech.
 * Incorporates input sanitation, error capturing, and strict type safety.
 */
export async function handlePaymentReceiptNotification(
  payload: PaymentReceiptPayload
): Promise<ActionResponse> {
  try {
    // 1. Input Sanitization & Basic Validation
    if (!payload.customerName || !payload.phone || payload.amount <= 0 || !payload.receiptNumber) {
      return {
        success: false,
        error: 'Invalid action payload: Missing or incorrect transactional properties.'
      };
    }

    // 2. Compile the Dynamic Message Template Text Body
    const messageBody = buildSmsTemplate({
      customerName: payload.customerName,
      amount: payload.amount,
      receiptNumber: payload.receiptNumber,
    });

    // 3. Dispatch the message via the BongaTech Gateway Wrapper
    const smsResult = await sendSms(payload.phone, messageBody);

    // 4. Evaluate Gateway Status
    if (!smsResult.success) {
      console.warn(`[SMS Notification Warning] Failed routing message to ${payload.phone}: ${smsResult.error}`);
      return {
        success: false,
        error: `Notification dispatch failed: ${smsResult.error}`
      };
    }

    console.log(`[SMS Notification Success] Routed successfully. Message ID: ${smsResult.messageId}`);
    return {
      success: true,
      messageId: smsResult.messageId
    };

  } catch (error) {
    console.error('[SMS Orchestration Critical Error]:', error);
    return {
      success: false,
      error: error instanceof Error ? error.message : 'An unexpected orchestration failure occurred.'
    };
  }
}

Processing Summary Flow

When a client process invokes the execution wrapper above, the module executes the following structural operational checks:

1. State Assertion: Verifies that the internal parameter schemas comply with runtime criteria (e.g., payment amounts must exceed zero).
2. String Compilation: Merges properties into the standard multiline template literal string block.
3. Number Transformation: Passes the phone string through the digit filtering regex matrix (/\D/g) to transform localized strings into E.164 sequences (254XXXXXXXXX).
4. Network Fetch Transmission: Houses the HTTP request within structured try/catch handlers to isolate and capture system faults smoothly.