bps-kit 1.0.1 → 1.0.2

package/templates/vault/whatsapp-cloud-api/assets/boilerplate/nodejs/src/index.ts

@@ -0,0 +1,125 @@
+import express from 'express';
+import dotenv from 'dotenv';
+import { WhatsAppClient } from './whatsapp-client';
+import { TemplateManager } from './template-manager';
+import {
+  validateHMAC,
+  rawBodyMiddleware,
+  handleWebhookVerification,
+  parseWebhookPayload,
+  extractMessageContent,
+} from './webhook-handler';
+import { WhatsAppConfig, IncomingMessage, StatusUpdate } from './types';
+
+dotenv.config();
+
+// === Configuration ===
+
+const config: WhatsAppConfig = {
+  token: process.env.WHATSAPP_TOKEN!,
+  phoneNumberId: process.env.PHONE_NUMBER_ID!,
+  wabaId: process.env.WABA_ID!,
+  appSecret: process.env.APP_SECRET!,
+  verifyToken: process.env.VERIFY_TOKEN!,
+};
+
+const whatsapp = new WhatsAppClient(config);
+const templates = new TemplateManager(config);
+
+// === Express Setup ===
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+
+// Raw body capture MUST come before express.json()
+app.use(express.json({ verify: rawBodyMiddleware }));
+
+// === Webhook Routes ===
+
+// GET - Webhook verification (Meta sends challenge)
+app.get('/webhook', handleWebhookVerification(config.verifyToken));
+
+// POST - Receive messages and status updates
+app.post('/webhook', validateHMAC(config.appSecret), async (req, res) => {
+  // Respond 200 immediately (WhatsApp requires response within 5 seconds)
+  res.sendStatus(200);
+
+  try {
+    const { messages, statuses } = parseWebhookPayload(req.body);
+
+    for (const message of messages) {
+      await handleIncomingMessage(message);
+    }
+
+    for (const status of statuses) {
+      handleStatusUpdate(status);
+    }
+  } catch (error) {
+    console.error('Error processing webhook:', error);
+  }
+});
+
+// === Message Handler ===
+
+async function handleIncomingMessage(message: IncomingMessage): Promise<void> {
+  const from = message.from;
+  const content = extractMessageContent(message);
+
+  console.log(`Message from ${from}: [${content.type}] ${content.text || content.buttonId || ''}`);
+
+  // Mark as read
+  await whatsapp.markAsRead(message.id);
+
+  // TODO: Implement your message handling logic here
+  // Example: Echo back the message
+  switch (content.type) {
+    case 'text':
+      await whatsapp.sendText(from, `Recebi sua mensagem: "${content.text}"`);
+      break;
+
+    case 'button':
+      await whatsapp.sendText(from, `Voce selecionou: ${content.text}`);
+      break;
+
+    case 'list':
+      await whatsapp.sendText(from, `Voce escolheu: ${content.text}`);
+      break;
+
+    case 'image':
+    case 'document':
+    case 'video':
+    case 'audio':
+      await whatsapp.sendText(from, `Recebi sua midia (${content.type}).`);
+      break;
+
+    default:
+      await whatsapp.sendText(from, 'Desculpe, nao entendi. Como posso ajudar?');
+      break;
+  }
+}
+
+// === Status Handler ===
+
+function handleStatusUpdate(status: StatusUpdate): void {
+  console.log(`Status update: ${status.id} -> ${status.status}`);
+
+  if (status.status === 'failed') {
+    console.error(`Message delivery failed:`, status.errors);
+  }
+}
+
+// === Health Check ===
+
+app.get('/health', (_req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+// === Start Server ===
+
+app.listen(PORT, () => {
+  console.log(`WhatsApp webhook server running on port ${PORT}`);
+  console.log(`Webhook URL: http://localhost:${PORT}/webhook`);
+  console.log(`Health check: http://localhost:${PORT}/health`);
+});
+
+export { whatsapp, templates };

package/templates/vault/whatsapp-cloud-api/assets/boilerplate/nodejs/src/template-manager.ts

@@ -0,0 +1,67 @@
+import axios, { AxiosInstance } from 'axios';
+import { WhatsAppConfig, TemplateInfo } from './types';
+
+export class TemplateManager {
+  private client: AxiosInstance;
+  private wabaId: string;
+
+  constructor(config: WhatsAppConfig) {
+    const version = config.graphApiVersion || 'v21.0';
+    this.wabaId = config.wabaId;
+
+    this.client = axios.create({
+      baseURL: `https://graph.facebook.com/${version}`,
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+        'Content-Type': 'application/json',
+      },
+    });
+  }
+
+  async listTemplates(status?: string): Promise<TemplateInfo[]> {
+    const params: Record<string, any> = { limit: 100 };
+    if (status) params.status = status;
+
+    const response = await this.client.get(`/${this.wabaId}/message_templates`, { params });
+    return response.data.data;
+  }
+
+  async createTemplate(
+    name: string,
+    category: 'MARKETING' | 'UTILITY' | 'AUTHENTICATION',
+    language: string,
+    components: Array<{
+      type: 'HEADER' | 'BODY' | 'FOOTER' | 'BUTTONS';
+      format?: string;
+      text?: string;
+      example?: Record<string, any>;
+      buttons?: Array<Record<string, any>>;
+    }>
+  ): Promise<{ id: string; status: string; category: string }> {
+    const response = await this.client.post(`/${this.wabaId}/message_templates`, {
+      name,
+      category,
+      language,
+      components,
+    });
+    return response.data;
+  }
+
+  async deleteTemplate(templateName: string): Promise<void> {
+    await this.client.delete(`/${this.wabaId}/message_templates`, {
+      data: { name: templateName },
+    });
+  }
+
+  async getApprovedTemplates(): Promise<TemplateInfo[]> {
+    return this.listTemplates('APPROVED');
+  }
+
+  async getPendingTemplates(): Promise<TemplateInfo[]> {
+    return this.listTemplates('PENDING');
+  }
+
+  async getRejectedTemplates(): Promise<TemplateInfo[]> {
+    return this.listTemplates('REJECTED');
+  }
+}

package/templates/vault/whatsapp-cloud-api/assets/boilerplate/nodejs/src/types.ts

@@ -0,0 +1,216 @@
+// WhatsApp Cloud API TypeScript Types
+
+// === Configuration ===
+
+export interface WhatsAppConfig {
+  token: string;
+  phoneNumberId: string;
+  wabaId: string;
+  appSecret: string;
+  verifyToken: string;
+  graphApiVersion?: string;
+}
+
+// === Outgoing Messages ===
+
+export interface SendMessagePayload {
+  messaging_product: 'whatsapp';
+  recipient_type?: 'individual';
+  to: string;
+  type: MessageType;
+  text?: { preview_url?: boolean; body: string };
+  template?: TemplatePayload;
+  image?: MediaPayload;
+  document?: DocumentPayload;
+  video?: MediaPayload;
+  audio?: MediaPayload;
+  location?: LocationPayload;
+  contacts?: ContactPayload[];
+  interactive?: InteractivePayload;
+  reaction?: ReactionPayload;
+  context?: { message_id: string };
+}
+
+export type MessageType =
+  | 'text' | 'template' | 'image' | 'document' | 'video'
+  | 'audio' | 'location' | 'contacts' | 'interactive'
+  | 'reaction' | 'sticker';
+
+export interface TemplatePayload {
+  name: string;
+  language: { code: string };
+  components?: TemplateComponent[];
+}
+
+export interface TemplateComponent {
+  type: 'header' | 'body' | 'button';
+  sub_type?: 'url' | 'quick_reply';
+  index?: number;
+  parameters?: TemplateParameter[];
+}
+
+export interface TemplateParameter {
+  type: 'text' | 'image' | 'document' | 'video';
+  text?: string;
+  image?: { link: string };
+  document?: { link: string; filename?: string };
+  video?: { link: string };
+}
+
+export interface MediaPayload {
+  id?: string;
+  link?: string;
+  caption?: string;
+}
+
+export interface DocumentPayload extends MediaPayload {
+  filename?: string;
+}
+
+export interface LocationPayload {
+  longitude: number;
+  latitude: number;
+  name?: string;
+  address?: string;
+}
+
+export interface ContactPayload {
+  name: { formatted_name: string; first_name?: string; last_name?: string };
+  phones?: Array<{ phone: string; type?: string }>;
+  emails?: Array<{ email: string; type?: string }>;
+}
+
+export interface InteractivePayload {
+  type: 'button' | 'list' | 'product' | 'product_list' | 'flow';
+  header?: { type: 'text' | 'image' | 'video' | 'document'; text?: string };
+  body: { text: string };
+  footer?: { text: string };
+  action: InteractiveAction;
+}
+
+export interface InteractiveAction {
+  buttons?: Array<{
+    type: 'reply';
+    reply: { id: string; title: string };
+  }>;
+  button?: string;
+  sections?: Array<{
+    title: string;
+    rows: Array<{ id: string; title: string; description?: string }>;
+  }>;
+  catalog_id?: string;
+  product_retailer_id?: string;
+  name?: string;
+  parameters?: Record<string, any>;
+}
+
+export interface ReactionPayload {
+  message_id: string;
+  emoji: string;
+}
+
+// === API Responses ===
+
+export interface SendMessageResponse {
+  messaging_product: string;
+  contacts: Array<{ input: string; wa_id: string }>;
+  messages: Array<{ id: string }>;
+}
+
+// === Webhook Events ===
+
+export interface WebhookPayload {
+  object: string;
+  entry: WebhookEntry[];
+}
+
+export interface WebhookEntry {
+  id: string;
+  changes: WebhookChange[];
+}
+
+export interface WebhookChange {
+  value: WebhookValue;
+  field: string;
+}
+
+export interface WebhookValue {
+  messaging_product: string;
+  metadata: { display_phone_number: string; phone_number_id: string };
+  contacts?: Array<{ profile: { name: string }; wa_id: string }>;
+  messages?: IncomingMessage[];
+  statuses?: StatusUpdate[];
+  errors?: WebhookError[];
+}
+
+export interface IncomingMessage {
+  from: string;
+  id: string;
+  timestamp: string;
+  type: string;
+  text?: { body: string };
+  image?: { id: string; mime_type: string; sha256: string; caption?: string };
+  document?: { id: string; mime_type: string; filename: string; caption?: string };
+  video?: { id: string; mime_type: string; caption?: string };
+  audio?: { id: string; mime_type: string };
+  location?: { latitude: number; longitude: number; name?: string; address?: string };
+  contacts?: ContactPayload[];
+  interactive?: {
+    type: 'button_reply' | 'list_reply' | 'nfm_reply';
+    button_reply?: { id: string; title: string };
+    list_reply?: { id: string; title: string; description?: string };
+    nfm_reply?: { response_json: string };
+  };
+  reaction?: { message_id: string; emoji: string };
+  context?: { from: string; id: string };
+  referral?: {
+    source_url: string;
+    source_type: string;
+    source_id: string;
+    headline?: string;
+    body?: string;
+    ctwa_clid?: string;
+  };
+}
+
+export interface StatusUpdate {
+  id: string;
+  status: 'sent' | 'delivered' | 'read' | 'failed';
+  timestamp: string;
+  recipient_id: string;
+  conversation?: {
+    id: string;
+    origin: { type: string };
+    expiration_timestamp?: string;
+  };
+  pricing?: {
+    billable: boolean;
+    pricing_model: string;
+    category: string;
+  };
+  errors?: Array<{ code: number; title: string; message: string }>;
+}
+
+export interface WebhookError {
+  code: number;
+  title: string;
+  message: string;
+  error_data?: { details: string };
+}
+
+// === Template Management ===
+
+export interface TemplateInfo {
+  name: string;
+  status: 'APPROVED' | 'PENDING' | 'REJECTED' | 'PAUSED' | 'DISABLED';
+  category: 'MARKETING' | 'UTILITY' | 'AUTHENTICATION';
+  language: string;
+  components: Array<{
+    type: string;
+    format?: string;
+    text?: string;
+    buttons?: Array<{ type: string; text: string; url?: string }>;
+  }>;
+  id: string;
+  rejected_reason?: string;
+}

package/templates/vault/whatsapp-cloud-api/assets/boilerplate/nodejs/src/webhook-handler.ts

@@ -0,0 +1,173 @@
+import crypto from 'crypto';
+import { Request, Response, NextFunction } from 'express';
+import { WebhookPayload, IncomingMessage, StatusUpdate } from './types';
+
+/**
+ * Middleware para validar assinatura HMAC-SHA256 dos webhooks do WhatsApp.
+ *
+ * A Meta assina cada request com o App Secret. Validar esta assinatura
+ * previne que requests falsificados sejam processados. Usar comparacao
+ * constant-time previne timing attacks.
+ *
+ * IMPORTANTE: Este middleware deve ser aplicado ANTES de qualquer body parser
+ * que altere o raw body (express.json() por exemplo).
+ */
+export function validateHMAC(appSecret: string) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const signature = req.headers['x-hub-signature-256'] as string;
+
+    if (!signature) {
+      console.warn('Webhook request without signature header');
+      res.sendStatus(401);
+      return;
+    }
+
+    const rawBody = (req as any).rawBody;
+    if (!rawBody) {
+      console.error('Raw body not available. Ensure rawBody middleware is configured.');
+      res.sendStatus(500);
+      return;
+    }
+
+    const expectedSignature =
+      'sha256=' +
+      crypto.createHmac('sha256', appSecret).update(rawBody).digest('hex');
+
+    const isValid = crypto.timingSafeEqual(
+      Buffer.from(signature),
+      Buffer.from(expectedSignature)
+    );
+
+    if (!isValid) {
+      console.warn('Invalid webhook signature');
+      res.sendStatus(401);
+      return;
+    }
+
+    next();
+  };
+}
+
+/**
+ * Middleware para capturar o raw body antes do JSON parse.
+ * Necessario para validacao HMAC.
+ */
+export function rawBodyMiddleware(req: Request, _res: Response, buf: Buffer): void {
+  (req as any).rawBody = buf;
+}
+
+/**
+ * Handler de verificacao do webhook (GET).
+ * A Meta envia um challenge que deve ser retornado para confirmar o endpoint.
+ */
+export function handleWebhookVerification(verifyToken: string) {
+  return (req: Request, res: Response): void => {
+    const mode = req.query['hub.mode'] as string;
+    const token = req.query['hub.verify_token'] as string;
+    const challenge = req.query['hub.challenge'] as string;
+
+    if (mode === 'subscribe' && token === verifyToken) {
+      console.log('Webhook verified successfully');
+      res.status(200).send(challenge);
+    } else {
+      console.warn('Webhook verification failed: invalid token');
+      res.sendStatus(403);
+    }
+  };
+}
+
+/**
+ * Extrai mensagens e status updates do payload do webhook.
+ */
+export function parseWebhookPayload(payload: WebhookPayload): {
+  messages: IncomingMessage[];
+  statuses: StatusUpdate[];
+} {
+  const messages: IncomingMessage[] = [];
+  const statuses: StatusUpdate[] = [];
+
+  for (const entry of payload.entry || []) {
+    for (const change of entry.changes || []) {
+      if (change.value.messages) {
+        messages.push(...change.value.messages);
+      }
+      if (change.value.statuses) {
+        statuses.push(...change.value.statuses);
+      }
+    }
+  }
+
+  return { messages, statuses };
+}
+
+/**
+ * Extrai o texto ou ID de selecao de uma mensagem recebida.
+ */
+export function extractMessageContent(message: IncomingMessage): {
+  type: string;
+  text?: string;
+  buttonId?: string;
+  listId?: string;
+  mediaId?: string;
+  location?: { latitude: number; longitude: number };
+  reaction?: { emoji: string; messageId: string };
+} {
+  switch (message.type) {
+    case 'text':
+      return { type: 'text', text: message.text?.body };
+
+    case 'interactive':
+      if (message.interactive?.type === 'button_reply') {
+        return {
+          type: 'button',
+          buttonId: message.interactive.button_reply?.id,
+          text: message.interactive.button_reply?.title,
+        };
+      }
+      if (message.interactive?.type === 'list_reply') {
+        return {
+          type: 'list',
+          listId: message.interactive.list_reply?.id,
+          text: message.interactive.list_reply?.title,
+        };
+      }
+      if (message.interactive?.type === 'nfm_reply') {
+        return {
+          type: 'flow',
+          text: message.interactive.nfm_reply?.response_json,
+        };
+      }
+      return { type: 'interactive' };
+
+    case 'image':
+      return { type: 'image', mediaId: message.image?.id };
+
+    case 'document':
+      return { type: 'document', mediaId: message.document?.id };
+
+    case 'video':
+      return { type: 'video', mediaId: message.video?.id };
+
+    case 'audio':
+      return { type: 'audio', mediaId: message.audio?.id };
+
+    case 'location':
+      return {
+        type: 'location',
+        location: message.location
+          ? { latitude: message.location.latitude, longitude: message.location.longitude }
+          : undefined,
+      };
+
+    case 'reaction':
+      return {
+        type: 'reaction',
+        reaction: message.reaction
+          ? { emoji: message.reaction.emoji, messageId: message.reaction.message_id }
+          : undefined,
+      };
+
+    default:
+      return { type: message.type };
+  }
+}