Genuka WA docs

Libreria TypeScript

@genuka/whatsapp — builder tipizzati, validazione e normalizzazione degli eventi.

@genuka/whatsapp non è l'ennesimo client HTTP. È lo strato che previene i 400 evitabili, rende la gestione dei webhook esaustiva in fase di compilazione e trasforma i ~200 codici di errore di Meta in sette decisioni concrete.

La libreria funziona in modo autonomo con la Cloud API di Meta, senza account Genuka. È distribuita con licenza MIT.

Installazione

npm install @genuka/whatsapp

Costruire un messaggio

Lunghezze, cardinalità e formato del numero di telefono vengono verificati prima della chiamata di rete.

import { messages } from "@genuka/whatsapp";

const choice = messages.buttons("+237 6 99 00 11 22", {
  body: "How can we help?",
  buttons: [
    { id: "order", title: "My order" },
    { id: "support", title: "A problem" },
  ],
});

Un errore di costruzione viene lanciato immediatamente, con il percorso del campo problematico:

ValidationError: interactive.buttons: must contain at most 3 items (got 4)

La finestra di 24 ore

import { sendStrategy } from "@genuka/whatsapp";

sendStrategy(contact.lastInboundAt); // "free_form" | "template"

Una chiamata di funzione, invece di un 131047 scoperto quando il tentativo è già stato fatturato.

Gestire un webhook

Meta annida tutto in entry[].changes[].value, dove il vero discriminante non è un campo ma la presenza di messages o di statuses. La libreria appiattisce tutto una volta per tutte.

import { parseWebhook, eventKey } from "@genuka/whatsapp/webhooks";

for (const event of parseWebhook(await request.json())) {
  if (await alreadyProcessed(eventKey(event))) continue;

  switch (event.kind) {
    case "message":         // in arrivo
    case "status":          // sent / delivered / read / failed / deleted
    case "template":        // approvazione, qualità, ricategorizzazione
    case "account":         // qualità del numero, limiti, sospensione
    case "user_preference": // disiscrizione dal marketing (opt-out)
    case "coexistence":     // cronologia, echi, contatti
    case "unknown":         // mai perso, sempre inoltrato
  }
}

Il parser non lancia mai eccezioni: un payload malformato produce una lista vuota. Un'eccezione qui diventerebbe un 500, e Meta reinvierebbe l'intero lotto.

Decidere cosa fare con un errore

errorClass porta la decisione, non il codice numerico.

import { WhatsAppError } from "@genuka/whatsapp";

try {
  await send(payload);
} catch (error) {
  if (!(error instanceof WhatsAppError)) throw error;

  switch (error.errorClass) {
    case "needs_template":      return resendAsTemplate();      // 131047
    case "recipient_permanent": return markUnreachable();       // 131026, 131050
    case "recipient_throttled": return requeueLater();          // 131049
    case "media":               return reuploadAndRetryOnce();  // 131052
    case "retryable":           return backoff();               // 4, 130429, 5xx
    case "config":              return alertOperator();         // 190, 133010
    case "template":            return surfaceToCustomer();     // 132xxx
    case "validation":
    case "unknown":             throw error;
  }
}

Due trasporti, un solo nucleo

Lo stesso payload costruito può viaggiare su due percorsi, con gli stessi builder, la stessa validazione e la stessa tassonomia degli errori:

// Con una chiave Genuka WA: nessun token Meta coinvolto
import { GenukaTransport } from "@genuka/whatsapp";
const transport = new GenukaTransport({ apiKey: process.env.GENUKA_WA_API_KEY! });

// Direttamente verso Meta, se hai le tue credenziali
import { MetaTransport } from "@genuka/whatsapp";
const transport = new MetaTransport({ accessToken: process.env.META_TOKEN! });

Riferimento completo

Ogni modulo ha la sua guida, tratta direttamente dal pacchetto: vivono accanto al codice che descrivono, quindi non si disallineano:

Versione della Graph API

La libreria fissa esplicitamente una versione della Graph API invece di seguire "latest". Un cambio di versione silenzioso è il modo migliore per scoprire una modifica incompatibile in produzione: cambiare DEFAULT_GRAPH_VERSION è un rilascio deliberato.

In questa pagina