bzapper 0.7.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c424228e334385c5d1e747d6951f6c76df26255765678d7748430642cfcb4c1
+  data.tar.gz: 3b27b1c1a0bffffa53937fe6d0f19e8486afa18ecdbe8dd08044160103413ae5
+SHA512:
+  metadata.gz: c071f315d70aefbaf8eb98933d36c42c2f45d2fee7b3cbdd66db0d7a141b6e978e7d65f7337d6ef2b5cdb744569fd47efe3c91cba05b8525eabf9f9234908025
+  data.tar.gz: b7e9fed41f47242ba1c0fd659c5dc0255ae3ac48a6db969be4ed38806c047ebb72b4f63800c5224f1a389d2b9e32efd374e73f9341399c0326f0c68c088c35b0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berni Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,323 @@
+# bzapper
+
+SDK oficial em **Ruby** da API do [bZapper](https://bzapper.com.br) (WhatsApp): mensagens de
+todos os tipos (e OTP), números e QR, grupos, conversas, contatos, campanhas, webhooks com
+verificação de assinatura e o **bZapper Connect**.
+
+Zero dependências de runtime (só biblioteca padrão: `net/http`, `json`, `openssl`,
+`securerandom`) · Ruby 3.0+ · novas tentativas e idempotência automáticas.
+
+## Instalação
+
+```bash
+gem install bzapper -v 0.7.0
+```
+
+Ou no `Gemfile` — **fixe a versão exata** (cada release declara se muda a superfície pública):
+
+```ruby
+gem "bzapper", "0.7.0"
+```
+
+## Hello world
+
+```ruby
+require "bzapper"
+
+client = Bzapper::Client.new(ENV.fetch("BZAPPER_API_KEY"))
+
+sent = client.messages.send_text(to: "+5511999999999", body: "Olá do bZapper!")
+puts sent["message_id"], sent["status"] # => "queued"
+```
+
+Só `to` é obrigatório além do conteúdo: sem `instance_id`, o bZapper escolhe o número do seu
+pool (rotação + afinidade de conversa). `to` é um telefone E.164 (`+5511999999999`) ou um JID.
+
+## Autenticação
+
+Crie a chave no painel do bZapper em **Chaves de API** (`bz_live_...`). Ela vai em
+`Authorization: Bearer <chave>` em toda requisição — a SDK cuida disso. A chave já carrega o
+projeto dela; numa chave de conta, escolha o projeto com `project_id:`.
+
+```ruby
+client = Bzapper::Client.new(
+  "bz_live_...",
+  base_url: "https://api.bzapper.com.br", # padrão; em dev: "http://localhost:8080"
+  timeout: 30,                             # segundos, por tentativa
+  max_retries: 2,                          # novas tentativas além da primeira (0 desliga)
+  locale: "pt-BR",                         # Accept-Language: mensagens de erro traduzidas
+  project_id: "…"                          # X-Project-Id: escopo de projeto
+)
+```
+
+Construir o cliente não faz nenhuma chamada de rede. Um cliente pode ser compartilhado entre
+threads.
+
+## Como os métodos funcionam
+
+Os métodos ficam em **recursos**, um por área da API, e se chamam como o `operationId` da
+spec OpenAPI em snake_case (`sendText` → `send_text`):
+
+| Recurso | O que tem |
+| --- | --- |
+| `client.messages` | `send_text`, `send_image`, `send_video`, `send_document`, `send_audio`, `send_sticker`, `send_location`, `send_contact`, `send_poll`, `send_reaction`, `send_buttons`, `send_list`, `send_otp`, `mark_read`, `presence_chat` |
+| `client.scheduling` | `list_scheduled`, `cancel_scheduled` |
+| `client.instances` | números: `list_instances`, `create_instance`, `connect_instance` (QR/código), `get_instance`, `disconnect_instance`, `logout_instance`, `clear_instance_session`, `archive_instance`, proxy, filtros de entrada, conta oficial… |
+| `client.groups` | `list_groups`, `create_group`, `get_group`, `update_group`, `update_group_participants`, `group_invite_link`, `join_group`, `preview_group_invite`, `leave_group`, pedidos de entrada |
+| `client.conversations` | `list_conversations`, `conversation_history` |
+| `client.advanced` | editar/apagar/encaminhar mensagem, perfil, privacidade, arquivar/fixar/ler/silenciar chat, etiquetas, bloqueio, chamadas |
+| `client.contacts` | CRM (`list_contacts`, `create_contact`, `update_contact`…), tags, grupos de contatos, opt-in/out, supressões, `contacts_check` |
+| `client.campaigns` | `create_campaign`, `estimate_campaign`, destinatários, `dry_run_campaign`, `start/pause/resume/cancel_campaign` |
+| `client.pools` | pools de números |
+| `client.webhooks` | `create_webhook`, `update_webhook`, `test_webhook`, `list_webhook_deliveries`… |
+| `client.advisories` | avisos "atualize sua integração" |
+| `client.usage` / `client.billing` | consumo; plano, assinatura, add-ons, faturas, preços |
+| `client.accounts` | perfil, chaves de API, marca, projetos, usuários |
+| `client.connect` | apps parceiros conectados à sua conta |
+| `client.system` | `get_health` |
+
+Convenções (iguais em todos os métodos):
+
+* Parâmetros de **caminho** são posicionais (`client.instances.get_instance(id)`); **query** e
+  **corpo** são keyword args com os nomes da API (`to:`, `instance_id:`…).
+* Campo de corpo que você não passa **não é enviado**. `nil` explícito vai como `null` (num
+  PATCH, limpa o campo): `client.contacts.update_contact(id, email: nil)`.
+* Filtros de query com `nil` são omitidos; listas vão como CSV; `Time` vira ISO 8601 UTC (`Z`).
+* Toda chamada aceita `timeout:`; as escritas aceitam `idempotency_key:`.
+* O retorno é o **JSON inteiro** da resposta — `Hash`/`Array` com chaves **string**. Listas
+  vêm como `{"data" => [...], ...}` (a SDK não desembrulha, para não perder paginação e
+  metadados). Campos novos da API aparecem sem quebrar nada. `204` → `nil`.
+* Parâmetro de caminho vazio, `"."` ou `".."` → `ArgumentError` antes de qualquer requisição.
+
+## Mensagens
+
+```ruby
+to = "+5511999999999"
+m = client.messages
+
+m.send_text(to: to, body: "Pedido #42 confirmado", idempotency_key: "pedido-42")
+m.send_image(to: to, media: { url: "https://picsum.photos/600", caption: "Oi" })
+m.send_video(to: to, media: { url: "https://example.com/clip.mp4" })
+m.send_document(to: to, media: { url: "https://example.com/nota.pdf", filename: "nota.pdf" })
+m.send_audio(to: to, media: { url: "https://example.com/audio.ogg", ptt: true }) # ptt = mensagem de voz
+m.send_sticker(to: to, media: { url: "https://example.com/sticker.webp" })
+m.send_location(to: to, latitude: -23.5613, longitude: -46.6565, name: "Av. Paulista")
+m.send_contact(to: to, contact_name: "Berni Software", contact_vcard: "BEGIN:VCARD…")
+m.send_poll(to: to, name: "Pizza ou sushi?", options: %w[Pizza Sushi], selectable_count: 1)
+m.send_reaction(to: to, quoted_message_id: "ABCD1234", emoji: "👍") # emoji "" remove
+m.send_buttons(to: to, body: "Escolha:", buttons: [{ id: "a", title: "Opção A" }, { id: "b", title: "Opção B" }])
+m.send_list(to: to, body: "Cardápio:", button_text: "Abrir",
+            sections: [{ title: "Bebidas", rows: [{ id: "1", title: "Café" }, { id: "2", title: "Chá" }] }])
+
+# OTP: o código vai sozinho numa bolha (copiável); o texto de contexto é gerado se omitido.
+m.send_otp(to: to, code: "482913", expiry_minutes: 5)
+
+# Agendar: qualquer envio aceita scheduled_at (Time ou RFC 3339).
+m.send_text(to: to, body: "Lembrete", scheduled_at: Time.now + 3600)
+client.scheduling.list_scheduled
+
+# Presença ("digitando…") e confirmação de leitura
+m.presence_chat(instance_id: "…", to: to, state: "typing") # typing, recording, paused
+m.mark_read("wa_message_id", instance_id: "…", chat: "5511999999999@s.whatsapp.net")
+```
+
+**MediaInput** (`media:`): `{ url:, base64:, caption:, filename:, mimetype:, ptt: }` — use
+`url` **ou** `base64`, nunca os dois.
+
+**Botões e listas** não são confiáveis no WhatsApp (pior em grupos): a API **sempre** manda
+também um **menu de texto numerado** equivalente. Desenhe o fluxo para funcionar só com ele.
+
+## Números (instâncias) e QR
+
+```ruby
+inst = client.instances.create_instance(phone: "+5511999999999", nickname: "Vendas")
+qr = client.instances.connect_instance(inst["id"], method: "qr") # ou method: "code" (código de pareamento)
+puts qr["qr_code"] || qr["pair_code"]
+
+client.instances.get_instance(inst["id"])["status"] # => "connected"
+client.instances.list_instances["data"].each { |i| puts "#{i['phone']} #{i['status']}" }
+```
+
+## Grupos e conversas
+
+```ruby
+g = client.groups.create_group(instance_id: "…", name: "Clientes VIP", participants: ["+5511988887777"])
+client.groups.update_group_participants(g["jid"], instance_id: "…", action: "add", participants: ["+5511977776666"])
+client.groups.group_invite_link(g["jid"], instance_id: "…")
+
+client.conversations.list_conversations(instance_id: "…")
+client.conversations.conversation_history("5511999999999@s.whatsapp.net", instance_id: "…", limit: 50)
+client.advanced.archive_chat("5511999999999@s.whatsapp.net", instance_id: "…", on: true)
+```
+
+## Contatos
+
+```ruby
+c = client.contacts.create_contact(phone: "+5511999999999", name: "Ana", email: "ana@example.com")
+client.contacts.mutate_contact_tags(c["id"], add: ["vip"])
+client.contacts.list_contacts(tags: %w[vip], has_email: true, limit: 100)
+client.contacts.opt_out_contact(c["id"])
+client.contacts.contacts_check(instance_id: "…", phones: ["+5511999999999"]) # está no WhatsApp?
+```
+
+O vínculo contato ↔ projeto/número é mantido **automaticamente** pela API.
+
+## Campanhas
+
+```ruby
+camp = client.campaigns.create_campaign(
+  name: "Black Friday",
+  variations: [{ body: "Oi {{name}}, 30% hoje!", weight: 1 }],
+  pacing_profile: "conservative"
+)
+client.campaigns.add_campaign_recipients(camp["id"], contact_filter: { tags: ["vip"] })
+client.campaigns.dry_run_campaign(camp["id"])
+client.campaigns.start_campaign(camp["id"])
+```
+
+## Webhooks
+
+```ruby
+hook = client.webhooks.create_webhook(url: "https://seu.app/bzapper", event_types: ["message.received"])
+secret = hook["secret"] # mostrado uma vez — guarde
+```
+
+No seu endpoint, verifique a assinatura (`X-Bzapper-Signature: sha256=<hex>`, HMAC-SHA256 do
+**corpo cru**, comparação em tempo constante) antes de processar:
+
+```ruby
+# Rack / Rails
+raw = request.body.read
+signature = request.get_header("HTTP_X_BZAPPER_SIGNATURE")
+
+Bzapper::Webhook.verify(secret, raw, signature) # => true / false
+
+event = Bzapper::Webhook.construct_event(secret, raw, signature) # SignatureError se não confere
+event.id      # estável: use para ignorar reentregas
+event.type    # "message.received"
+event.payload # dados do evento
+
+# Ou com roteamento por tipo:
+router = Bzapper::Webhook::Router.new(secret)
+router.on("message.received") { |ev| puts ev.sender&.dig("name"), ev.payload["body"] }
+router.on("instance.banned") { |ev| alertar(ev.instance_id) }
+router.handle(raw, signature)
+```
+
+## bZapper Connect (parceiros)
+
+Seu software deixa os clientes **dele** assinarem o bZapper Pro e conectarem o WhatsApp sem
+sair do seu produto. Use o `Bzapper::PartnerClient` com a chave de **parceiro** — só no
+backend, nunca no navegador:
+
+```ruby
+partner = Bzapper::PartnerClient.new(ENV.fetch("BZAPPER_PARTNER_KEY"))
+
+# 1) backend: cria a sessão e entrega o token ao front
+session = partner.create_connect_session(
+  external_id: "cliente-42",
+  customer: { name: "Ana Souza", email: "ana@boxy.com", phone: "+5511988887777" }
+)
+# 2) front: BzapperConnect.open({ session: session["session_token"] }) → emite um `code`
+# 3) backend: troca o code pela chave do cliente
+conn = partner.exchange_connect_code(code: params[:code])
+cliente = Bzapper::Client.new(conn["api_key"])
+cliente.messages.send_text(to: "+5511999999999", body: "Conectado!")
+
+partner.list_partner_connections(status: "active")
+partner.rotate_partner_connection_key(conn["id"])
+partner.revoke_partner_connection(conn["id"])
+```
+
+Conectado, a chave do cliente responde **402 `connect_suspended`** enquanto o Pro dele estiver
+em aberto e **401 `connect_revoked`** depois que a conexão termina. O ciclo de vida chega ao
+webhook do parceiro como `connect.completed`, `connect.suspended`, `connect.resumed` e
+`connect.revoked` (mesma verificação de assinatura).
+
+Do lado do cliente, `client.connect.list_connected_apps` / `revoke_connected_app(id)` mostram e
+cortam os apps parceiros conectados.
+
+## Erros
+
+Toda resposta fora de 2xx vira um `Bzapper::Error` (alias `Bzapper::BzapperError`) — ou a
+subclasse do status. **Use `code` na sua lógica**: é estável. `message` é texto para humanos,
+traduzido conforme `locale:`, e pode mudar.
+
+```ruby
+begin
+  client.messages.send_text(to: "+5511999999999", body: "oi")
+rescue Bzapper::RateLimitError => e
+  sleep(e.retry_after || 1) # segundos do Retry-After
+rescue Bzapper::PermissionDeniedError => e
+  warn "falta o escopo #{e.required_scope}" if e.code == "insufficient_scope"
+rescue Bzapper::Error => e
+  warn "#{e.code} (HTTP #{e.status}) request_id=#{e.request_id}: #{e.message}"
+end
+```
+
+| Classe | Quando |
+| --- | --- |
+| `Bzapper::AuthenticationError` | 401 |
+| `Bzapper::PermissionDeniedError` | 403 (`required_scope` = header `X-Required-Scope`) |
+| `Bzapper::NotFoundError` | 404 |
+| `Bzapper::ConflictError` | 409 |
+| `Bzapper::ValidationError` | 400 e 422 |
+| `Bzapper::RateLimitError` | 429 (`retry_after` em segundos) |
+| `Bzapper::ServerError` | 5xx |
+| `Bzapper::NetworkError` | conexão/timeout (`status == 0`, `code == "NETWORK_ERROR"`) |
+| `Bzapper::Error` | qualquer outro status; `INVALID_RESPONSE` se um 2xx chega com corpo que não é JSON |
+
+Campos: `code` (`body.code` → `body.error` → `HTTP_<status>`), `message`, `status`,
+`request_id` (header `X-Request-Id` da resposta, senão o que a SDK enviou — **informe ao
+suporte**), `retry_after`, `required_scope`, `locale` e `body` (o corpo decodificado).
+`e.detailed_message` junta tudo numa linha.
+
+Argumento inválido no seu código (chave vazia, parâmetro de caminho vazio) **não** é
+`Bzapper::Error`: é `ArgumentError`/`TypeError`, na hora, sem requisição.
+
+## Novas tentativas e idempotência
+
+A SDK tenta de novo (até `max_retries`, padrão 2) em erro de rede/timeout, `429`, `502`, `503`
+e `504` — nada mais (um `500` ou `4xx` volta na hora). Espera o `Retry-After` quando houver
+(teto 60 s), senão `min(8, 0.5 × 2^tentativa)` s + até 25% de jitter.
+
+Cada chamada gera um `X-Request-Id` e, nas escritas (POST/PUT/PATCH/DELETE), uma
+`Idempotency-Key` — **as mesmas em todas as tentativas**. A API guarda a resposta por 24 h e,
+numa repetição, devolve a original (`Idempotent-Replayed: true`) em vez de executar de novo:
+é o que torna a nova tentativa segura (a mensagem não sai duas vezes).
+
+Para amarrar a idempotência a algo do **seu** sistema (ex.: o id do pedido), passe a sua chave:
+
+```ruby
+client.messages.send_text(to: "+5511999999999", body: "Pedido #42 confirmado", idempotency_key: "pedido-42")
+```
+
+## Versões
+
+A gem segue a versão das SDKs do bZapper (todas as linguagens saem na mesma versão). Cada
+release declara se muda a superfície pública (assinatura) ou se é só aditiva — por isso fixe a
+versão exata no `Gemfile` e atualize de propósito. `Bzapper::VERSION` vai no header
+`X-Bzapper-Client` (`bzapper-ruby/<versão>`): é por ele que o bZapper avisa **só** quem roda
+uma versão afetada por uma correção.
+
+## Exemplo
+
+[`examples/quickstart.rb`](examples/quickstart.rb):
+
+```bash
+BZAPPER_API_KEY=bz_live_... BZAPPER_TO=+5511999999999 ruby examples/quickstart.rb
+```
+
+## Desenvolvimento
+
+```bash
+bundle install
+bundle exec rake test   # conformidade (test/fixtures/conformance/cases.json) + unitários + versão
+```
+
+Os métodos em `lib/bzapper/resources/` são gerados da spec (`ruby script/generate.rb`, só no
+monorepo); a suíte falha se algum endpoint da spec ficar sem método.
+
+## Licença
+
+MIT — Berni Software.

data/lib/bzapper/client.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Bzapper
+  # Validação e montagem do transporte, comum ao {Client} e ao {PartnerClient}.
+  # @api private
+  module ClientOptions
+    private
+
+    def build_transport(api_key, base_url:, timeout:, max_retries:, locale:, project_id:, sleeper:)
+      label = self.class.name
+      raise TypeError, "#{label}: api_key precisa ser String (ex.: \"bz_live_...\")." unless api_key.is_a?(String)
+      raise ArgumentError, "#{label}: api_key é obrigatória (ex.: \"bz_live_...\")." if api_key.strip.empty?
+      unless max_retries.is_a?(Integer) && max_retries >= 0
+        raise ArgumentError, "#{label}: max_retries precisa ser um inteiro >= 0."
+      end
+      unless timeout.is_a?(Numeric) && timeout.positive?
+        raise ArgumentError, "#{label}: timeout precisa ser > 0 (segundos)."
+      end
+      if !sleeper.nil? && !sleeper.respond_to?(:call)
+        raise ArgumentError, "#{label}: sleeper precisa responder a #call(segundos)."
+      end
+
+      url = base_url.to_s.strip
+      url = DEFAULT_BASE_URL if url.empty?
+      @masked_key = api_key.length > 8 ? "#{api_key[0, 8]}..." : "..."
+      Transport.new(api_key, base_url: url, timeout: timeout, max_retries: max_retries,
+                             locale: locale, project_id: project_id, sleeper: sleeper)
+    end
+
+    public
+
+    # @return [String] URL da API (sem barra final).
+    def base_url
+      @transport.base_url
+    end
+
+    # @return [Numeric] segundos por tentativa.
+    def timeout
+      @transport.timeout
+    end
+
+    # @return [Integer] novas tentativas além da primeira.
+    def max_retries
+      @transport.max_retries
+    end
+
+    def inspect
+      "#<#{self.class.name} api_key=#{@masked_key.inspect} base_url=#{base_url.inspect}>"
+    end
+    alias to_s inspect
+  end
+
+  # Cliente da API do bZapper.
+  #
+  # Nada é chamado na rede ao construir. Pode ser compartilhado entre threads (cada tentativa
+  # abre a própria conexão). Os métodos ficam nos recursos (um por tag da spec):
+  # `messages`, `instances`, `groups`, `conversations`, `advanced`, `contacts`, `campaigns`,
+  # `scheduling`, `pools`, `webhooks`, `advisories`, `usage`, `billing`, `accounts`, `connect`
+  # e `system`.
+  #
+  # @example
+  #   client = Bzapper::Client.new(ENV.fetch("BZAPPER_API_KEY"))
+  #   client.messages.send_text(to: "5511999990000", body: "Olá!")
+  class Client
+    include ClientOptions
+    include ResourceAccessors
+
+    # @param api_key [String] chave de API (`bz_live_...`, painel → Chaves de API). Único
+    #   argumento posicional e obrigatório.
+    # @param base_url [String] URL da API, sem barra final. Padrão: produção
+    #   (`https://api.bzapper.com.br`). Em dev: `http://localhost:8080`.
+    # @param timeout [Numeric] segundos por tentativa (padrão 30).
+    # @param max_retries [Integer] novas tentativas além da primeira em erro de rede/timeout,
+    #   429, 502, 503 e 504 (padrão 2; `0` desliga).
+    # @param locale [String, nil] enviado como `Accept-Language` (mensagens de erro traduzidas).
+    # @param project_id [String, nil] enviado como `X-Project-Id` (escopo de projeto; a chave já
+    #   traz o dela).
+    # @param sleeper [#call, nil] espera entre tentativas, chamada com os segundos (padrão
+    #   `Kernel#sleep`). Serve para testes não dormirem de verdade.
+    # @raise [ArgumentError] chave vazia ou opção inválida.
+    # @raise [TypeError] chave que não é String.
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, locale: nil, project_id: nil, sleeper: nil)
+      @transport = build_transport(api_key, base_url: base_url, timeout: timeout,
+                                            max_retries: max_retries, locale: locale,
+                                            project_id: project_id, sleeper: sleeper)
+      build_resources(@transport)
+    end
+  end
+
+  # Cliente do **bZapper Connect** do lado do PARCEIRO (`/partner/*`): o software parceiro
+  # deixa os clientes DELE assinarem o bZapper Pro e conectarem o WhatsApp sem sair do produto.
+  #
+  # Autentica com a chave de parceiro — guarde-a só no **backend**, nunca no navegador. Mesmas
+  # opções, cabeçalhos, erros e novas tentativas do {Client}; os métodos (`get_partner_me`,
+  # `create_connect_session`, `exchange_connect_code`, `list_partner_connections`,
+  # `get_partner_connection`, `revoke_partner_connection`, `rotate_partner_connection_key`)
+  # ficam direto nele.
+  #
+  # @example
+  #   partner = Bzapper::PartnerClient.new(ENV.fetch("BZAPPER_PARTNER_KEY"))
+  #   session = partner.create_connect_session(external_id: "cliente-42",
+  #                                            customer: { name: "Ana", email: "ana@example.com" })
+  #   # front: BzapperConnect.open({ session }) → `code`; backend:
+  #   key = partner.exchange_connect_code(code: code)["api_key"]
+  class PartnerClient
+    include ClientOptions
+    include Resources::Requests
+    include Resources::PartnerOperations
+
+    # Todos os status de uma conexão do Connect.
+    CONNECTION_STATUSES = %w[pending_account pending_payment pending_number active suspended revoked].freeze
+
+    # Mesmas opções do {Client#initialize}.
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES, locale: nil, project_id: nil, sleeper: nil)
+      @transport = build_transport(api_key, base_url: base_url, timeout: timeout,
+                                            max_retries: max_retries, locale: locale,
+                                            project_id: project_id, sleeper: sleeper)
+    end
+  end
+end

data/lib/bzapper/codec.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Bzapper
+  # Codificação de caminho, query e corpo. Sem estado; nada aqui faz rede.
+  # @api private
+  module Codec
+    module_function
+
+    UNRESERVED = /[^A-Za-z0-9\-._~]/n.freeze
+
+    # Percent-encode de um valor inteiro (tudo fora de `A-Z a-z 0-9 - . _ ~`), em UTF-8.
+    def escape(value)
+      text = value.to_s
+      text = text.encode(::Encoding::UTF_8) unless text.encoding == ::Encoding::BINARY
+      text.b.gsub(UNRESERVED) { |byte| format("%%%02X", byte.ord) }.force_encoding(::Encoding::US_ASCII)
+    end
+
+    # Percent-encode de UM segmento de caminho (`abc 1` → `abc%201`, `/` → `%2F`). JIDs
+    # (`5511999990000@s.whatsapp.net`) passam como vieram, só codificados.
+    #
+    # Vazio, `"."` e `".."` são recusados antes de qualquer requisição: o cliente HTTP (ou um
+    # proxy) resolveria `%2E%2E` como navegação de caminho e chamaria outra rota.
+    # @raise [ArgumentError]
+    def path_segment(value, name)
+      raise ArgumentError, "#{name} é obrigatório." if value.nil? || value.equal?(UNSET)
+
+      text = value.to_s
+      raise ArgumentError, "#{name} não pode ser vazio." if text.empty?
+      raise ArgumentError, "#{name} não pode ser #{text.inspect}." if [".", ".."].include?(text)
+
+      escape(text)
+    end
+
+    # `Time`/`DateTime` → ISO 8601 em UTC com `Z` (microssegundos só quando houver).
+    def iso_utc(time)
+      time = time.getutc
+      text = time.strftime("%Y-%m-%dT%H:%M:%S")
+      text += format(".%06d", time.usec) unless time.usec.zero?
+      "#{text}Z"
+    end
+
+    # Valor de query: booleanos como `true`/`false`, datas em ISO 8601 UTC com `Z`, listas
+    # como CSV (`style: form, explode: false` da spec), string passa como veio.
+    def query_value(value)
+      case value
+      when Array then value.map { |item| query_value(item) }.join(",")
+      when true then "true"
+      when false then "false"
+      when Time then iso_utc(value)
+      else
+        if defined?(::DateTime) && value.is_a?(::DateTime)
+          iso_utc(value.to_time)
+        elsif defined?(::Date) && value.is_a?(::Date)
+          "#{value.strftime('%Y-%m-%d')}T00:00:00Z"
+        else
+          value.to_s
+        end
+      end
+    end
+
+    # `?a=1&b=2` com os pares informados (`nil` é omitido); `""` se não sobra nenhum.
+    def query_string(query)
+      return "" if query.nil? || query.empty?
+
+      pairs = query.each_with_object([]) do |(key, value), acc|
+        next if value.nil? || value.equal?(UNSET)
+
+        acc << "#{escape(key)}=#{escape(query_value(value))}"
+      end
+      pairs.empty? ? "" : "?#{pairs.join('&')}"
+    end
+
+    # Corpo só com o que o usuário informou: {UNSET} sai; `nil` fica e vira `null`.
+    def compact(fields)
+      fields.reject { |_key, value| value.equal?(UNSET) }
+    end
+
+    # Converte o corpo para tipos JSON: chaves viram string, `UNSET` em Hash some, datas viram
+    # ISO 8601 (instantes em UTC com `Z`).
+    def jsonable(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, item), out|
+          next if item.equal?(UNSET)
+
+          out[key.to_s] = jsonable(item)
+        end
+      when Array then value.map { |item| jsonable(item) }
+      when Time then iso_utc(value)
+      when Symbol then value.to_s
+      else
+        if defined?(::DateTime) && value.is_a?(::DateTime)
+          iso_utc(value.to_time)
+        elsif defined?(::Date) && value.is_a?(::Date)
+          value.strftime("%Y-%m-%d")
+        else
+          value
+        end
+      end
+    end
+
+    # Texto UTF-8 (bytes inválidos trocados) → `[json_ou_nil, texto, é_json?]`.
+    def decode_json(raw)
+      text = raw.to_s.dup.force_encoding(::Encoding::UTF_8).scrub
+      return [nil, text, false] if text.strip.empty?
+
+      [JSON.parse(text), text, true]
+    rescue JSON::ParserError
+      [nil, text, false]
+    end
+  end
+end