# Libreria TypeScript

URL: https://wa.genuka.com/it/docs/library
Language: Italian

> @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.

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

## Installazione

```bash
npm install @genuka/whatsapp
```

## Costruire un messaggio

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

```ts
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:

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

## La finestra di 24 ore

```ts
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.

```ts
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.

```ts
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:

```ts
// 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:

* [Inviare messaggi](https://wa.genuka.com/sdk/messages)
* [Modelli](https://wa.genuka.com/sdk/templates)
* [Media](https://wa.genuka.com/sdk/media)
* [Webhook](https://wa.genuka.com/sdk/webhooks)
* [Flows](https://wa.genuka.com/sdk/flows)
* [Gestione](https://wa.genuka.com/sdk/management)
* [Coesistenza](https://wa.genuka.com/sdk/coexistence)
* [Chiamate](https://wa.genuka.com/sdk/calling)

## 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.
