> ## Documentation Index
> Fetch the complete documentation index at: https://zapo.to/llms.txt
> Use this file to discover all available pages before exploring further.

# JIDs, helpers e constantes

> Construa, parseie e inspecione JIDs do WhatsApp, além de cada constante de protocolo WA_* exportada pelo root do pacote zapo-js para uso no seu código.

Um **JID** (Jabber ID) é como o WhatsApp endereça cada entidade. O `zapo` exporta um conjunto de helpers para construí-los e classificá-los, todos a partir da raiz do pacote:

```ts theme={null}
import { parsePhoneJid, isGroupJid, splitJid } from 'zapo-js'
```

<h2 id="jid-shapes">
  Formatos de JID
</h2>

| Entidade                | Exemplo                         |
| ----------------------- | ------------------------------- |
| Usuário (telefone)      | `5511999999999@s.whatsapp.net`  |
| Grupo                   | `123456789-987654@g.us`         |
| Newsletter / canal      | `120363000000000000@newsletter` |
| Status broadcast        | `status@broadcast`              |
| LID (id de privacidade) | `123456789@lid`                 |

<h2 id="building-jids">
  Construindo JIDs
</h2>

```ts theme={null}
// Número de telefone → JID de usuário
parsePhoneJid('5511999999999')        // '5511999999999@s.whatsapp.net'

// Normaliza qualquer coisa em um JID de destinatário (aceita um número ou string)
normalizeRecipientJid('5511999999999')

// Remove um sufixo de dispositivo, reduzindo ao JID base do usuário
toUserJid('5511999999999:12@s.whatsapp.net') // '5511999999999@s.whatsapp.net'

// Constrói um JID com escopo de dispositivo
buildDeviceJid('5511999999999', 's.whatsapp.net', 12)
```

<h2 id="parsing--splitting">
  Parsing e splitting
</h2>

```ts theme={null}
splitJid('5511999999999@s.whatsapp.net')  // { user, server }
parseJidFull(jid)                         // ParsedJid com a decomposição completa
parseSignalAddressFromJid(jid)            // { user, server, device }
```

<h2 id="classifying-jids">
  Classificando JIDs
</h2>

Predicados booleanos para a lógica de roteamento:

| Helper                       | Verdadeiro para            |
| ---------------------------- | -------------------------- |
| `isGroupJid(jid)`            | Grupo (`@g.us`)            |
| `isGroupOrBroadcastJid(jid)` | Grupo ou broadcast         |
| `isBroadcastJid(jid)`        | Lista de transmissão       |
| `isStatusBroadcastJid(jid)`  | `status@broadcast`         |
| `isNewsletterJid(jid)`       | Newsletter (`@newsletter`) |
| `isLidJid(jid)`              | LID (`@lid`)               |
| `isBotJid(jid)`              | Um bot (`@bot`)            |
| `isHostedDeviceJid(jid)`     | Dispositivo hospedado      |

```ts theme={null}
client.on('message', (event) => {
  if (isGroupJid(event.key.remoteJid)) {
    console.log('a group message')
  }
})
```

<h2 id="constants">
  Constantes
</h2>

O conjunto completo de constantes de protocolo é exportado como objetos `WA_*` congelados (a biblioteca usa estes em vez de enums do TypeScript). As mais usadas:

| Constante                                     | Contém                                                                           |
| --------------------------------------------- | -------------------------------------------------------------------------------- |
| `WA_DEFAULTS`                                 | Timeouts padrão, o JID de status-broadcast, o navegador de dispositivo padrão, … |
| `WA_BROWSERS`                                 | Identificadores de navegador para o fingerprint do dispositivo.                  |
| `WA_PRIVACY_CATEGORIES` / `WA_PRIVACY_VALUES` | Nomes de configurações de privacidade e valores permitidos.                      |
| `WA_DISCONNECT_REASONS` / `WA_LOGOUT_REASONS` | Strings de motivo nos eventos de conexão.                                        |
| `WA_MESSAGE_TYPES` / `WA_MESSAGE_TAGS`        | Classificação de mensagens.                                                      |
| `WA_NODE_TAGS` / `WA_XMLNS`                   | Node tags de protocolo e namespaces XML.                                         |
| `WA_APP_STATE_COLLECTIONS`                    | Nomes de coleções de app-state.                                                  |

```ts theme={null}
import { WA_DEFAULTS, WA_LOGOUT_REASONS } from 'zapo-js'

await client.logout(WA_LOGOUT_REASONS.USER_INITIATED)
```

**Tipos** literais de string associados também são exportados para anotação: `WaPrivacyCategory`, `WaPrivacySettingName`, `WaPrivacyValue`, `WaDisconnectReason`, `WaLogoutReason`, `WaConnectionCode`, `WaStreamErrorCode`, `WaFailureReasonCode` e `ParsedJid`.

<h2 id="message-helpers">
  Helpers de mensagem
</h2>

Dois helpers para inspecionar e referenciar mensagens, exportados da raiz do pacote:

| Export                 | Assinatura                                                        | Descrição                                                                                                                                                                                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `getContentType`       | `(content?: Proto.IMessage) => keyof Proto.IMessage \| undefined` | Retorna a chave do tipo de conteúdo (`'conversation'`, `'imageMessage'`, `'extendedTextMessage'`, …) de uma mensagem, ou `undefined` para uma mensagem vazia. Pula `senderKeyDistributionMessage` para que mensagens de grupo reportem o payload real e não a piggyback da sender-key.     |
| `resolveMessageTarget` | `(ref: WaMessageTargetInput) => WaMessageKey`                     | Normaliza um target de reply/edit/reaction/revoke/pin para uma `WaMessageKey` simples. Aceita uma `WaMessageKey` explícita (retornada como está) ou um evento `message` recebido (referência com `rawNode` — sua `key` é retornada). Lança quando um evento é passado sem `key.id` válida. |

```ts theme={null}
import { getContentType, resolveMessageTarget } from 'zapo-js'

client.on('message', (event) => {
  console.log(getContentType(event.message)) // ex.: 'extendedTextMessage'
  const key = resolveMessageTarget(event)    // idêntico a event.key para eventos reais
})
```

<h2 id="other-utilities">
  Outros utilitários
</h2>

| Export                     | Propósito                                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| `proto`                    | O namespace protobuf completo — construa payloads `Proto.IMessage` brutos.                           |
| `delay(ms)`                | Sleep baseado em Promise.                                                                            |
| `parseUsyncResultEnvelope` | Parseia um envelope de resultado de IQ USync.                                                        |
| `WA_VERSION`               | A string de versão padrão embarcada do WhatsApp Web que o client anuncia quando `version` é omitido. |

<h2 id="device-identity-helpers">
  Helpers de identidade de dispositivo
</h2>

Dois helpers de baixo nível acessíveis via o subpath `zapo-js/protocol` — úteis ao escrever um plugin que precisa da mesma resolução de `deviceBrowser` / `deviceOsDisplayName` / `devicePlatform` que o client factory e o auth client usam, para que seus próprios payloads combinem com o `ClientPayload` de pareamento.

| Export                    | Assinatura                                               | Descrição                                                                                                                                                                                                                                                |
| ------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolveWaDeviceIdentity` | `(options: WaDeviceIdentityOptions) => WaDeviceIdentity` | Resolve um `{ browser, osDisplayName, platform }` totalmente populado a partir de opções brutas, aplicando os mesmos defaults que o client usa (browser cai em `WA_DEFAULTS.DEVICE_BROWSER`, nome do OS no OS de runtime, platform inferido do browser). |
| `getWaBrowserDisplayName` | `(browser: string) => string`                            | O nome legível de browser anunciado durante o pareamento (ex.: `'chrome'` → `'Chrome'`). Entradas desconhecidas são retornadas inalteradas.                                                                                                              |

```ts theme={null}
import { resolveWaDeviceIdentity, getWaBrowserDisplayName } from 'zapo-js/protocol'

const device = resolveWaDeviceIdentity({ deviceBrowser: 'firefox' })
// { browser: 'firefox', osDisplayName: '<runtime OS>', platform: '3' }
getWaBrowserDisplayName('firefox') // 'Firefox'
```