@natyapp/meta

SDK TypeScript, server-side e sem estado para integrar aplicações à Meta Graph API e à WhatsApp Cloud API.

Requisitos

• Node.js 18 ou superior
• credenciais e permissões válidas da Meta
• versão da Graph API definida conscientemente pela aplicação

Instalação

npm install @natyapp/meta

Inicialização

import NatyMeta from "@natyapp/meta";

const meta = new NatyMeta({
  graphApiVersion: "v25.0",
});

O SDK não lê .env. A aplicação deve carregar e fornecer tokens em cada operação ou configurar um token padrão:

const meta = new NatyMeta({
  graphApiVersion: process.env.META_GRAPH_API_VERSION,
  accessToken: process.env.META_ACCESS_TOKEN,
});

Não coloque tokens Meta no frontend. Use este SDK no backend.

Enviar mensagem

const result = await meta.messages.sendText({
  accessToken,
  phoneNumberId,
  to: "5511999999999",
  text: "Olá!",
});

if (result.isError) throw result.isError;
console.log(result.isSuccess.messages);

Também estão disponíveis messages.sendTemplate e messages.sendInteractive.

Templates

const templates = await meta.templates.list({
  accessToken,
  wabaId,
  limit: 20,
});

Use templates.create para criar templates. Aprovação, categoria final e qualidade continuam sob controle da Meta.

Números e OAuth

await meta.phoneNumbers.getInfo({ accessToken, phoneNumberId });

await meta.auth.exchangeCodeForAccessToken({
  appId,
  appSecret,
  code,
  redirectUri,
});

await meta.auth.exchangeForLongLivedToken({
  appId,
  appSecret,
  token: shortLivedToken,
});

Webhooks

const verification = meta.webhooks.verifyChallenge({
  mode: req.query["hub.mode"],
  verifyToken: req.query["hub.verify_token"],
  challenge: req.query["hub.challenge"],
  expectedVerifyToken: process.env.META_WEBHOOK_VERIFY_TOKEN,
});

const parsed = meta.webhooks.parseWhatsAppWebhook(req.body);

Valide a assinatura usando o corpo bruto, antes de converter o JSON:

const signature = meta.webhooks.verifySignature({
  rawBody,
  signature: req.headers["x-hub-signature-256"],
  appSecret: process.env.META_APP_SECRET!,
});

O servidor HTTP, a captura do corpo bruto, deduplicação, persistência e resposta 200 rápida são responsabilidades da aplicação consumidora.

Resultados e erros

As operações retornam Either<Error, T>:

if (result.isError !== undefined) {
  console.error(result.isError.message);
  return;
}

const value = result.isSuccess;

O SDK nunca registra access tokens. Um logger compatível pode ser injetado por logger.

Contrato suportado

• NatyMeta / export default
• MetaGraphClient
• AuthModule
• MessagesModule
• PhoneNumbersModule
• TemplatesModule
• WebhooksModule
• tipos de entrada e saída desses módulos
• ILogger, consoleLogger e createPinoAdapter

Veja a referência da API.

Desenvolvimento e publicação

npm test -- --runInBand
npm run typecheck
npm run build
npm pack --dry-run

prepublishOnly executa testes e build antes de uma publicação npm.