codehava-agent-kit 1.0.1 → 2.0.0

package/templates/.agent/skills/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/.agent/skills/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/.agent/skills/whatsapp-cloud-api/assets/boilerplate/nodejs/src/webhook-handler.ts

@@ -0,0 +1,175 @@
+import crypto from 'crypto';
+import { Request, Response, NextFunction } from 'express';
+import { WebhookPayload, IncomingMessage, StatusUpdate } from './types';
+
+const SAFE_CHALLENGE_RE = /^[A-Za-z0-9._-]{1,200}$/;
+
+/**
+ * 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 && SAFE_CHALLENGE_RE.test(challenge)) {
+      console.log('Webhook verified successfully');
+      res.type('text/plain').status(200).send(challenge);
+    } else {
+      console.warn('Webhook verification failed: invalid token');
+      res.status(mode === 'subscribe' && token === verifyToken ? 400 : 403).send();
+    }
+  };
+}
+
+/**
+ * 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 };
+  }
+}

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/nodejs/src/whatsapp-client.ts

@@ -0,0 +1,193 @@
+import axios, { AxiosInstance } from 'axios';
+import { WhatsAppConfig, SendMessagePayload, SendMessageResponse } from './types';
+
+export class WhatsAppClient {
+  private client: AxiosInstance;
+  private phoneNumberId: string;
+  private wabaId: string;
+
+  constructor(config: WhatsAppConfig) {
+    const version = config.graphApiVersion || 'v21.0';
+    this.phoneNumberId = config.phoneNumberId;
+    this.wabaId = config.wabaId;
+
+    this.client = axios.create({
+      baseURL: `https://graph.facebook.com/${version}`,
+      headers: {
+        Authorization: `Bearer ${config.token}`,
+        'Content-Type': 'application/json',
+      },
+    });
+  }
+
+  async sendMessage(payload: SendMessagePayload): Promise<SendMessageResponse> {
+    return this.sendWithRetry(payload);
+  }
+
+  async sendText(to: string, body: string, previewUrl = false): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'text',
+      text: { body, preview_url: previewUrl },
+    });
+  }
+
+  async sendTemplate(
+    to: string,
+    templateName: string,
+    languageCode: string,
+    components?: SendMessagePayload['template']
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'template',
+      template: {
+        name: templateName,
+        language: { code: languageCode },
+        ...components,
+      },
+    });
+  }
+
+  async sendImage(to: string, imageUrl: string, caption?: string): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'image',
+      image: { link: imageUrl, caption },
+    });
+  }
+
+  async sendDocument(
+    to: string,
+    documentUrl: string,
+    filename: string,
+    caption?: string
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'document',
+      document: { link: documentUrl, filename, caption },
+    });
+  }
+
+  async sendInteractiveButtons(
+    to: string,
+    bodyText: string,
+    buttons: Array<{ id: string; title: string }>,
+    headerText?: string,
+    footerText?: string
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'interactive',
+      interactive: {
+        type: 'button',
+        ...(headerText && { header: { type: 'text', text: headerText } }),
+        body: { text: bodyText },
+        ...(footerText && { footer: { text: footerText } }),
+        action: {
+          buttons: buttons.map((b) => ({
+            type: 'reply' as const,
+            reply: { id: b.id, title: b.title },
+          })),
+        },
+      },
+    });
+  }
+
+  async sendInteractiveList(
+    to: string,
+    bodyText: string,
+    buttonText: string,
+    sections: Array<{
+      title: string;
+      rows: Array<{ id: string; title: string; description?: string }>;
+    }>,
+    headerText?: string,
+    footerText?: string
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'interactive',
+      interactive: {
+        type: 'list',
+        ...(headerText && { header: { type: 'text', text: headerText } }),
+        body: { text: bodyText },
+        ...(footerText && { footer: { text: footerText } }),
+        action: { button: buttonText, sections },
+      },
+    });
+  }
+
+  async sendReaction(to: string, messageId: string, emoji: string): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'reaction',
+      reaction: { message_id: messageId, emoji },
+    });
+  }
+
+  async sendLocation(
+    to: string,
+    latitude: number,
+    longitude: number,
+    name?: string,
+    address?: string
+  ): Promise<SendMessageResponse> {
+    return this.sendMessage({
+      messaging_product: 'whatsapp',
+      to,
+      type: 'location',
+      location: { latitude, longitude, name, address },
+    });
+  }
+
+  async markAsRead(messageId: string): Promise<void> {
+    await this.client.post(`/${this.phoneNumberId}/messages`, {
+      messaging_product: 'whatsapp',
+      status: 'read',
+      message_id: messageId,
+    });
+  }
+
+  private async sendWithRetry(
+    payload: SendMessagePayload,
+    maxRetries = 3
+  ): Promise<SendMessageResponse> {
+    const nonRetryableCodes = [100, 131026, 131051, 132000, 132001, 132005, 133010];
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        const response = await this.client.post<SendMessageResponse>(
+          `/${this.phoneNumberId}/messages`,
+          payload
+        );
+        return response.data;
+      } catch (error: any) {
+        const errorCode = error.response?.data?.error?.code;
+        const errorMessage = error.response?.data?.error?.message || error.message;
+
+        if (nonRetryableCodes.includes(errorCode)) {
+          throw new Error(`WhatsApp API Error ${errorCode}: ${errorMessage}`);
+        }
+
+        if (attempt < maxRetries) {
+          const delay = Math.pow(2, attempt) * 1000;
+          await new Promise((resolve) => setTimeout(resolve, delay));
+          continue;
+        }
+
+        throw new Error(`WhatsApp API Error after ${maxRetries} retries: ${errorMessage}`);
+      }
+    }
+
+    throw new Error('Unexpected: retry loop exited without return or throw');
+  }
+}

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/nodejs/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/.agent/skills/whatsapp-cloud-api/assets/boilerplate/python/.env.example

@@ -0,0 +1,20 @@
+# WhatsApp Cloud API Configuration
+# Obtenha estes valores em: https://developers.facebook.com > App > WhatsApp > API Setup
+
+# Token de acesso (System User Token para producao)
+WHATSAPP_TOKEN=your_access_token_here
+
+# ID do numero de telefone (encontrado no API Setup)
+PHONE_NUMBER_ID=your_phone_number_id
+
+# ID da conta WhatsApp Business (encontrado no API Setup)
+WABA_ID=your_waba_id
+
+# App Secret (encontrado em App Settings > Basic)
+APP_SECRET=your_app_secret
+
+# Token customizado para verificacao do webhook (voce define)
+VERIFY_TOKEN=your_custom_verify_token
+
+# Porta do servidor
+PORT=3000