bzapper 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c424228e334385c5d1e747d6951f6c76df26255765678d7748430642cfcb4c1
-  data.tar.gz: 3b27b1c1a0bffffa53937fe6d0f19e8486afa18ecdbe8dd08044160103413ae5
+  metadata.gz: e7438b5b975605d626f5922c69496d7adef7b4e25d792018fee18755b79d4258
+  data.tar.gz: 21d526017685778f6c373f177c74815d2de996414e7653c82ed3cda77edd7430
 SHA512:
-  metadata.gz: c071f315d70aefbaf8eb98933d36c42c2f45d2fee7b3cbdd66db0d7a141b6e978e7d65f7337d6ef2b5cdb744569fd47efe3c91cba05b8525eabf9f9234908025
-  data.tar.gz: b7e9fed41f47242ba1c0fd659c5dc0255ae3ac48a6db969be4ed38806c047ebb72b4f63800c5224f1a389d2b9e32efd374e73f9341399c0326f0c68c088c35b0
+  metadata.gz: 2606d09adbe38226e21ff480188aa23dc909c04c35fc5541c3508f27dad4b5e627f1bf7614ba34b25e95f7f5c02b0148ce853009df6e07912ace6cabeb19fe12
+  data.tar.gz: db997c1ca043ac5b3172cbd1fe9af114eb2cfc2723f3eff54e59c2581390f84dc4ba5bcc2fcc6cac81dfbfb0e544be0627b63cc9ee3b8a4495a077e0147f178e

data/README.md

@@ -10,13 +10,13 @@ Zero dependências de runtime (só biblioteca padrão: `net/http`, `json`, `open
 ## Instalação
 
 ```bash
-gem install bzapper -v 0.7.0
+gem install bzapper -v 0.8.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"
+gem "bzapper", "0.8.0"
 ```
 
 ## Hello world
@@ -53,6 +53,27 @@ client = Bzapper::Client.new(
 Construir o cliente não faz nenhuma chamada de rede. Um cliente pode ser compartilhado entre
 threads.
 
+### Trocar a chave sem derrubar a integração (rotação)
+
+`rotate_my_key` (admin) cria uma chave **nova** herdando papel, escopos, projeto e nome da
+antiga, e mantém a antiga funcionando por um período de graça — dá tempo de fazer o deploy sem
+janela de erro. A chave crua aparece **uma única vez**, no retorno. Depois do prazo a antiga
+responde `401 key_expired`; `revoke_in_seconds: 0` revoga na hora (padrão 86400 s, máximo 30
+dias). Chave de parceiro (bZapper Connect) roda pelo `PartnerClient#rotate_partner_connection_key`.
+
+```ruby
+rotated = client.accounts.rotate_my_key(key_id, revoke_in_seconds: 3600) # 1 h de graça
+
+rotated["api_key"]                 # a chave NOVA, crua — guarde agora, não volta
+rotated["key"]["id"]               # metadados da nova
+rotated["previous_key"]["expires_at"] # quando a antiga para de funcionar (nil se revogada já)
+rotated["old_key_expires_at"]      # o mesmo instante, no topo do retorno
+rotated["previous_key"]["rotated_to"] # id da chave que substituiu a antiga
+```
+
+Uma chave já revogada ou já vencida responde `409` (`key_already_revoked` /
+`key_already_expired`).
+
 ## Como os métodos funcionam
 
 Os métodos ficam em **recursos**, um por área da API, e se chamam como o `operationId` da
@@ -66,13 +87,13 @@ spec OpenAPI em snake_case (`sendText` → `send_text`):
 | `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.contacts` | CRM (`list_contacts`, `create_contact`, `update_contact`…), `import_contacts` (lote), `export_contacts` (CSV), 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.accounts` | perfil, chaves de API (`rotate_my_key`), marca, projetos, usuários |
 | `client.connect` | apps parceiros conectados à sua conta |
 | `client.system` | `get_health` |
 
@@ -88,6 +109,8 @@ Convenções (iguais em todos os métodos):
   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.
+* Uma exceção ao retorno: `client.contacts.export_contacts` devolve **`String`** (o CSV cru),
+  porque a rota responde `text/csv` e não JSON.
 
 ## Mensagens
 
@@ -162,6 +185,48 @@ client.contacts.contacts_check(instance_id: "…", phones: ["+5511999999999"]) #
 
 O vínculo contato ↔ projeto/número é mantido **automaticamente** pela API.
 
+### Importar em lote
+
+Até **1000** contatos por chamada, upsert por telefone: o novo entra como
+`pending_validation` (precisa de opt-in antes de campanha), o que já existe só recebe os campos
+informados — valor em branco não apaga o que está lá. Linha ruim vai para `errors` e **não**
+derruba o resto; contato suprimido/opt-out/bloqueado aparece em `skipped_rows` e nunca
+ressuscita. Tags e grupos são criados na hora. `dry_run: true` valida tudo e não grava nada.
+
+```ruby
+result = client.contacts.import_contacts(
+  contacts: [
+    { phone: "+5511999999999", name: "Ana", email: "ana@example.com", tags: %w[vip] },
+    { phone: "+5511888888888", name: "Bruno", document: "12345678900", document_type: "cpf",
+      address: { city: "São Paulo", state: "SP", country: "BR" }, groups: %w[clientes] }
+  ],
+  dry_run: true # ensaio: nada é gravado
+)
+result["created"] # => 2
+result["errors"].each { |row| warn "linha #{row['index']} (#{row['phone']}): #{row['reason']}" }
+```
+
+### Exportar em CSV
+
+`export_contacts` aceita os **mesmos filtros** do `list_contacts` (menos `offset`; use `limit`
+para limitar as linhas) e devolve o **texto do CSV** — uma `String` UTF-8, não JSON. Colunas:
+`phone,name,email,status,source,tags,groups,created_at,last_activity_at`, com tags e grupos
+unidos por `;` e instantes em RFC 3339 UTC.
+
+```ruby
+require "csv"
+
+csv = client.contacts.export_contacts(status: "active", tags: %w[vip], has_email: true,
+                                      created_after: Time.utc(2026, 1, 1), limit: 50_000)
+
+File.write("contatos.csv", csv)                       # gravar como veio
+CSV.parse(csv, headers: true) { |row| puts row["phone"] } # ou percorrer linha a linha
+```
+
+Vírgulas e aspas dentro dos campos vêm escapadas pelo servidor — não monte o CSV de novo,
+entregue o texto ao parser. Para bases muito grandes, exporte em fatias com os filtros
+(`created_after`/`created_before`, `limit`) em vez de puxar tudo de uma vez.
+
 ## Campanhas
 
 ```ruby

data/lib/bzapper/codec.rb

@@ -99,9 +99,15 @@ module Bzapper
       end
     end
 
+    # Corpo cru → texto UTF-8 (bytes inválidos trocados). É o que as rotas de texto
+    # (`text/csv`, ex.: `exportContacts`) devolvem, sem passar por JSON.
+    def utf8(raw)
+      raw.to_s.dup.force_encoding(::Encoding::UTF_8).scrub
+    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
+      text = utf8(raw)
       return [nil, text, false] if text.strip.empty?
 
       [JSON.parse(text), text, true]

data/lib/bzapper/resources/accounts.rb

@@ -34,7 +34,7 @@ module Bzapper
 
       # Revoke a tenant API key. Admin only. `DELETE /keys/{id}`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] API key ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -47,6 +47,33 @@ module Bzapper
                 timeout: timeout)
       end
 
+      # Rotate a tenant API key. Admin only. `POST /keys/{id}/rotate`
+      #
+      # Creates a NEW key inheriting the old one's role, scopes, project and name, and keeps the OLD
+      # key working for a grace period so a running integration does not break mid-deploy. The raw key
+      # is shown ONCE. After the deadline the old key answers `401 key_expired`. `revoke_in_seconds:
+      # 0` revokes it immediately (default 86400, max 30 days). Partner keys (bZapper Connect) rotate
+      # through `/partner/connections/{id}/rotate-key`.
+      #
+      # @param id [String] API key ID (UUID).
+      # @param revoke_in_seconds [Integer, nil] (corpo) Grace period for the OLD key. 0 revokes it
+      #   immediately.
+      # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
+      # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
+      # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
+      # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
+      # @raise [ArgumentError] parâmetro de caminho vazio, "." ou "..".
+      def rotate_my_key(id, revoke_in_seconds: UNSET, idempotency_key: nil, timeout: nil)
+        payload = compact(
+          "revoke_in_seconds" => revoke_in_seconds
+        )
+        request("POST",
+                "/keys/#{segment(id, "id")}/rotate",
+                body: payload,
+                idempotency_key: idempotency_key,
+                timeout: timeout)
+      end
+
       # Authenticated identity (+ profile when it's a user session). `GET /me`
       #
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
@@ -198,7 +225,7 @@ module Bzapper
       #
       # `api_mode` is immutable and is ignored here.
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Project ID (UUID).
       # @param name [String] (corpo)
       # @param logo_url [String, nil] (corpo)
       # @param color [String, nil] (corpo)
@@ -223,7 +250,7 @@ module Bzapper
 
       # Delete a project (admin). `DELETE /projects/{id}`
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Project ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -238,7 +265,7 @@ module Bzapper
 
       # Identity of the numbers of a specific project. `GET /projects/{id}/brand`
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Project ID (UUID).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
       # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
@@ -249,7 +276,7 @@ module Bzapper
 
       # Save the identity of a specific project's numbers (admin). `PUT /projects/{id}/brand`
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Project ID (UUID).
       # @param about [String, nil] (corpo) "About"/status — applied to all numbers.
       # @param display_name [String, nil] (corpo) Business name (kit).
       # @param logo_url [String, nil] (corpo) Logo URL (kit).
@@ -286,7 +313,7 @@ module Bzapper
       # Upload the project logo (multipart, PNG/JPEG/WebP up to 5 MB) — admin. `POST
       # /projects/{id}/logo`
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Project ID (UUID).
       # @param file [String, IO, Pathname] conteúdo do arquivo (bytes), um IO ou o caminho no disco.
       # @param filename [String, nil] nome do arquivo (padrão: o do caminho, senão "file").
       # @param content_type [String, nil] tipo MIME (padrão: application/octet-stream).
@@ -337,7 +364,7 @@ module Bzapper
       #
       # Demoting the last administrator of the account is refused (409 last_admin).
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Account user ID (UUID).
       # @param role [String] (corpo) agent = member (no billing)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
@@ -359,7 +386,7 @@ module Bzapper
       #
       # You cannot remove yourself (409 self_remove) nor the last administrator (409 last_admin).
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Account user ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).

data/lib/bzapper/resources/advanced.rb

@@ -8,7 +8,7 @@ module Bzapper
     class Advanced < Base
       # Edit the text of a sent message. `PATCH /messages/{id}`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] bZapper message ID (UUID) — the `id` returned when the message was queued.
       # @param text [String] (corpo)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
@@ -28,7 +28,7 @@ module Bzapper
 
       # Revoke a message (delete for everyone). `DELETE /messages/{id}`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] bZapper message ID (UUID) — the `id` returned when the message was queued.
       # @param for_everyone [Boolean, nil] (query)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
@@ -121,7 +121,7 @@ module Bzapper
 
       # Archive/unarchive a chat. `POST /chats/{jid}/archive`
       #
-      # @param jid [String] Group JID (…@g.us).
+      # @param jid [String] Chat JID — contact (…@s.whatsapp.net / …@lid) or group (…@g.us).
       # @param instance_id [String] (corpo)
       # @param on [Boolean] (corpo)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
@@ -143,7 +143,7 @@ module Bzapper
 
       # Pin/unpin a chat. `POST /chats/{jid}/pin`
       #
-      # @param jid [String] Group JID (…@g.us).
+      # @param jid [String] Chat JID — contact (…@s.whatsapp.net / …@lid) or group (…@g.us).
       # @param instance_id [String] (corpo)
       # @param on [Boolean] (corpo)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
@@ -165,7 +165,7 @@ module Bzapper
 
       # Mark a chat read/unread. `POST /chats/{jid}/read`
       #
-      # @param jid [String] Group JID (…@g.us).
+      # @param jid [String] Chat JID — contact (…@s.whatsapp.net / …@lid) or group (…@g.us).
       # @param instance_id [String] (corpo)
       # @param on [Boolean] (corpo)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
@@ -187,7 +187,7 @@ module Bzapper
 
       # Mute/unmute a chat. `POST /chats/{jid}/mute`
       #
-      # @param jid [String] Group JID (…@g.us).
+      # @param jid [String] Chat JID — contact (…@s.whatsapp.net / …@lid) or group (…@g.us).
       # @param instance_id [String] (corpo)
       # @param on [Boolean] (corpo)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
@@ -209,7 +209,7 @@ module Bzapper
 
       # Apply/remove a label on a chat (experimental). `POST /chats/{jid}/labels`
       #
-      # @param jid [String] Group JID (…@g.us).
+      # @param jid [String] Chat JID — contact (…@s.whatsapp.net / …@lid) or group (…@g.us).
       # @param instance_id [String] (corpo)
       # @param label_id [String] (corpo)
       # @param apply [Boolean, nil] (corpo) true = apply, false = remove.
@@ -289,7 +289,7 @@ module Bzapper
 
       # Block a contact. `POST /contacts/{jid}/block`
       #
-      # @param jid [String] Group JID (…@g.us).
+      # @param jid [String] Contact JID (…@s.whatsapp.net) to block/unblock.
       # @param instance_id [String] (corpo)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
@@ -309,7 +309,7 @@ module Bzapper
 
       # Unblock a contact. `POST /contacts/{jid}/unblock`
       #
-      # @param jid [String] Group JID (…@g.us).
+      # @param jid [String] Contact JID (…@s.whatsapp.net) to block/unblock.
       # @param instance_id [String] (corpo)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).

data/lib/bzapper/resources/advisories.rb

@@ -22,7 +22,7 @@ module Bzapper
       #
       # Marks the advisory as handled; it stops being returned by `GET /advisories`.
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Advisory ID.
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).

data/lib/bzapper/resources/base.rb

@@ -27,6 +27,12 @@ module Bzapper
                                          idempotency_key: idempotency_key, timeout: timeout)
       end
 
+      # Rotas que respondem TEXTO (`text/csv`, ex.: `exportContacts`): devolve o corpo cru,
+      # sem JSON. Mesmos cabeçalhos, novas tentativas e erros do {#request}.
+      def request_text(method, path, query: nil, timeout: nil, accept: "text/csv")
+        @transport.request(method, path, query: query, timeout: timeout, accept: accept, as_text: true)
+      end
+
       def segment(value, name)
         Codec.path_segment(value, name)
       end

data/lib/bzapper/resources/campaigns.rb

@@ -107,7 +107,7 @@ module Bzapper
 
       # Get a campaign with stats and variations. `GET /campaigns/{id}`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
       # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
@@ -121,7 +121,7 @@ module Bzapper
       # Updates name, pacing, schedule and (if sent) replaces the variations. Only allowed while
       # draft/scheduled — 409 once started.
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param name [String, nil] (corpo)
       # @param pacing_profile [String, nil] (corpo)
       # @param start_at [Time, String, nil] (corpo) Future start = scheduled campaign.
@@ -148,7 +148,7 @@ module Bzapper
 
       # List recipients with per-contact delivery. `GET /campaigns/{id}/recipients`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param limit [Integer, nil] (query)
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -163,7 +163,7 @@ module Bzapper
 
       # Add (or replace) recipients. `POST /campaigns/{id}/recipients`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param recipients [Array<Hash>, nil] (corpo)
       # @param contacts [Hash, nil] (corpo) Map of phone → payload, e.g. {"+5551999198087": {"name":
       #   "Vinicius"}}.
@@ -196,7 +196,7 @@ module Bzapper
 
       # Start (or schedule) a campaign. `POST /campaigns/{id}/start`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -211,7 +211,7 @@ module Bzapper
 
       # Pause a campaign. `POST /campaigns/{id}/pause`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -226,7 +226,7 @@ module Bzapper
 
       # Resume a campaign. `POST /campaigns/{id}/resume`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -241,7 +241,7 @@ module Bzapper
 
       # Cancel a campaign. `POST /campaigns/{id}/cancel`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -256,7 +256,7 @@ module Bzapper
 
       # Simulate a campaign without sending. `POST /campaigns/{id}/dry-run`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Campaign ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).

data/lib/bzapper/resources/connect.rb

@@ -18,7 +18,7 @@ module Bzapper
       # Disconnect a partner app (admin). The partner's key stops working immediately. `DELETE
       # /me/connections/{id}`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] Connected partner app (connection) ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).

data/lib/bzapper/resources/contacts.rb

@@ -105,6 +105,33 @@ module Bzapper
                 timeout: timeout)
       end
 
+      # Import contacts in bulk. `POST /contacts/import`
+      #
+      # Upserts up to 1000 contacts by phone in one call. A new contact is created with `source:
+      # import` and `status: pending_validation` (it needs opt-in before a campaign). An existing one
+      # has only its informed fields updated — a blank value never erases what is there. A
+      # suppressed/opted-out/blocked contact is reported in `skipped_rows` and never resurrected. Tags
+      # and groups are created on demand. A bad row is reported in `errors` and does NOT fail the rest
+      # of the call. `dry_run` validates everything and writes nothing.
+      #
+      # @param contacts [Array<Hash>] (corpo)
+      # @param dry_run [Boolean, nil] (corpo) Validates and reports without writing anything.
+      # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
+      # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
+      # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
+      # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
+      def import_contacts(contacts:, dry_run: UNSET, idempotency_key: nil, timeout: nil)
+        payload = compact(
+          "contacts" => contacts,
+          "dry_run" => dry_run
+        )
+        request("POST",
+                "/contacts/import",
+                body: payload,
+                idempotency_key: idempotency_key,
+                timeout: timeout)
+      end
+
       # Get a contact. `GET /contacts/{id}`
       #
       # @param id [String] Contact ID (UUID).
@@ -337,7 +364,7 @@ module Bzapper
       #
       # Removes the tag from the dictionary and unlinks it from every contact.
       #
-      # @param id [String] Contact ID (UUID).
+      # @param id [String] Tag ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -389,7 +416,7 @@ module Bzapper
       #
       # Removes the contact group from the dictionary and unlinks it from every contact.
       #
-      # @param id [String] Contact ID (UUID).
+      # @param id [String] Contact group ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).

data/lib/bzapper/resources/contacts_export.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# ESCRITO À MÃO (não sai do script/generate.rb): `exportContacts` responde `text/csv`, e não
+# JSON — está fora dos casos gerados (BRIEF §6, "CSV") e tem teste próprio
+# (test/unit_test.rb, CsvExportTest). O resto do `client.contacts` é gerado
+# (lib/bzapper/resources/contacts.rb).
+
+module Bzapper
+  module Resources
+    class Contacts
+      # Export contacts as CSV. `GET /contacts/export`
+      #
+      # Devolve a base de contatos em **CSV** (`text/csv`, `Content-Disposition: attachment`) —
+      # não é JSON. Colunas:
+      # `phone,name,email,status,source,tags,groups,created_at,last_activity_at`; tags e grupos
+      # vêm unidos por `;` e os instantes em RFC 3339 UTC. Os filtros são os MESMOS do
+      # {#list_contacts} (só não há `offset`: use `limit` para limitar as linhas).
+      #
+      # O retorno é o texto do CSV, como veio do servidor (UTF-8) — passe-o a `CSV.parse` ou
+      # grave em disco. Para não carregar tudo na memória, exporte em fatias com os filtros
+      # (`created_after`/`created_before`, `limit`).
+      #
+      # @example Gravar em disco
+      #   File.write("contatos.csv", client.contacts.export_contacts(status: "active"))
+      #
+      # @example Ler linha a linha
+      #   require "csv"
+      #   CSV.parse(client.contacts.export_contacts(tags: %w[vip]), headers: true) do |row|
+      #     puts row["phone"]
+      #   end
+      #
+      # @param search [String, nil] (query) Filter by name, phone, email or document.
+      # @param tags [Array<String>, nil] (query) Tag keys (repeat the param or a CSV list).
+      # @param tags_match [String, nil] (query) Match ANY (default) or ALL of `tags`.
+      # @param groups [Array<String>, nil] (query) Contact-group keys.
+      # @param project_id [String, nil] (query) Scope by project (alternative to the X-Project-Id
+      #   header).
+      # @param instance_id [String, nil] (query) Filter by a number (instance) the contact
+      #   interacted with.
+      # @param status [String, nil] (query)
+      # @param city [String, nil] (query)
+      # @param state [String, nil] (query)
+      # @param country [String, nil] (query)
+      # @param zip [String, nil] (query)
+      # @param document [String, nil] (query)
+      # @param has_email [Boolean, nil] (query) Only contacts that have (true) or lack (false) an
+      #   email.
+      # @param last_activity_after [Time, String, nil] (query) last_message_at ≥ this instant
+      #   (RFC3339).
+      # @param last_activity_before [Time, String, nil] (query) last_message_at ≤ this instant
+      #   (RFC3339).
+      # @param created_after [Time, String, nil] (query) created_at ≥ this instant (RFC3339).
+      # @param created_before [Time, String, nil] (query) created_at ≤ this instant (RFC3339).
+      # @param sort [String, nil] (query)
+      # @param limit [Integer, nil] (query) Cap of exported rows.
+      # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
+      # @return [String] o CSV cru (UTF-8), com o cabeçalho na primeira linha.
+      # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
+      def export_contacts(search: nil, tags: nil, tags_match: nil, groups: nil, project_id: nil,
+                          instance_id: nil, status: nil, city: nil, state: nil, country: nil,
+                          zip: nil, document: nil, has_email: nil, last_activity_after: nil,
+                          last_activity_before: nil, created_after: nil, created_before: nil,
+                          sort: nil, limit: nil, timeout: nil)
+        query = {
+          "search" => search,
+          "tags" => tags,
+          "tags_match" => tags_match,
+          "groups" => groups,
+          "project_id" => project_id,
+          "instance_id" => instance_id,
+          "status" => status,
+          "city" => city,
+          "state" => state,
+          "country" => country,
+          "zip" => zip,
+          "document" => document,
+          "has_email" => has_email,
+          "last_activity_after" => last_activity_after,
+          "last_activity_before" => last_activity_before,
+          "created_after" => created_after,
+          "created_before" => created_before,
+          "sort" => sort,
+          "limit" => limit
+        }
+        request_text("GET", "/contacts/export", query: query, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/bzapper/resources/partner.rb

@@ -89,7 +89,7 @@ module Bzapper
 
       # Get one connection (status, account, numbers). `GET /partner/connections/{id}`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] Partner connection ID (UUID).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
       # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
@@ -101,7 +101,7 @@ module Bzapper
       # End a connection (revokes the key; does NOT cancel the customer's plan). `DELETE
       # /partner/connections/{id}`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] Partner connection ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -117,7 +117,7 @@ module Bzapper
       # Issue a new API key for a completed connection (the previous key stops working). `POST
       # /partner/connections/{id}/rotate-key`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] Partner connection ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).

data/lib/bzapper/resources/pools.rb

@@ -36,7 +36,7 @@ module Bzapper
 
       # Get a pool (with members). `GET /pools/{id}`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] Pool ID (UUID).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
       # @raise [Bzapper::Error] resposta fora de 2xx ou falha de rede.
@@ -47,7 +47,7 @@ module Bzapper
 
       # Add a number to the pool. `POST /pools/{id}/numbers`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] Pool ID (UUID).
       # @param instance_id [String] (corpo)
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).

data/lib/bzapper/resources/scheduling.rb

@@ -21,7 +21,7 @@ module Bzapper
 
       # Cancel a pending scheduled send. `DELETE /messages/scheduled/{id}`
       #
-      # @param id [String] parâmetro de caminho
+      # @param id [String] Scheduled message ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).

data/lib/bzapper/resources/webhooks.rb

@@ -47,7 +47,7 @@ module Bzapper
       # = true. With `secret: "regenerate"` a new secret is generated and returned ONCE in the
       # response; any other non-empty `secret` replaces it.
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Webhook ID (UUID).
       # @param url [String] (corpo)
       # @param secret [String, nil] (corpo) Empty = keep. "regenerate" = rotate (returned once).
       # @param event_types [Array<String>, nil] (corpo) Empty = all events.
@@ -76,7 +76,7 @@ module Bzapper
 
       # Remove a webhook. `DELETE /webhooks/{id}`
       #
-      # @param id [String] Instance ID (UUID).
+      # @param id [String] Webhook ID (UUID).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).
@@ -91,7 +91,7 @@ module Bzapper
 
       # Send a signed sample event to this webhook and report the result. `POST /webhooks/{id}/test`
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Webhook ID (UUID).
       # @param event_type [String, nil] (corpo) Event type of the sample (default a generic one).
       # @param idempotency_key [String, nil] chave de idempotência (senão a SDK gera uma).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
@@ -111,7 +111,7 @@ module Bzapper
 
       # Latest deliveries of a webhook. `GET /webhooks/{id}/deliveries`
       #
-      # @param id [String] Resource ID (UUID).
+      # @param id [String] Webhook ID (UUID).
       # @param limit [Integer, nil] (query) 1–200 (default 50).
       # @param timeout [Numeric, nil] segundos por tentativa (padrão: o do cliente).
       # @return [Hash, Array, nil] o JSON da resposta, inteiro (nil em 204).

data/lib/bzapper/transport.rb

@@ -96,8 +96,12 @@ module Bzapper
     # Executa a chamada e devolve o JSON decodificado da resposta (`nil` sem corpo).
     #
     # `body: nil` significa SEM corpo JSON; `multipart:` é um {Upload}.
+    #
+    # `accept:` troca o `Accept` (padrão `application/json`) e `as_text: true` devolve o corpo
+    # CRU em texto, sem passar por JSON — é o caminho das rotas `text/csv` (`exportContacts`).
     # @raise [Bzapper::Error]
-    def request(method, path, query: nil, body: nil, multipart: nil, idempotency_key: nil, timeout: nil)
+    def request(method, path, query: nil, body: nil, multipart: nil, idempotency_key: nil, timeout: nil,
+                accept: nil, as_text: false)
       method = method.to_s.upcase
       per_try = timeout.nil? ? @timeout : timeout
       unless per_try.is_a?(Numeric) && per_try.positive?
@@ -108,7 +112,7 @@ module Bzapper
       request_id = SecureRandom.uuid.delete("-")
       headers = {
         "Authorization" => "Bearer #{@api_key}",
-        "Accept" => "application/json",
+        "Accept" => accept || "application/json",
         "X-Bzapper-Client" => CLIENT_ID,
         "User-Agent" => CLIENT_ID,
         # Mesmo id em todas as tentativas desta chamada: é como o suporte correlaciona.
@@ -146,7 +150,10 @@ module Bzapper
           )
         end
 
-        return decode(status, resp_headers, raw, request_id) if status.between?(200, 299)
+        if status.between?(200, 299)
+          # Texto: o corpo volta como veio (o `INVALID_RESPONSE` do §4 não vale aqui).
+          return as_text ? Codec.utf8(raw) : decode(status, resp_headers, raw, request_id)
+        end
 
         if RETRY_STATUSES.include?(status) && attempt < @max_retries
           @sleeper.call(retry_delay(attempt, resp_headers["retry-after"]))

data/lib/bzapper/version.rb

@@ -3,5 +3,5 @@
 module Bzapper
   # Versão da gem. O `scripts/release-sdks.sh` do monorepo bumpa a linha abaixo por regex
   # (ancorada no início da linha) e o `bzapper.gemspec` lê daqui — não mude o formato dela.
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/bzapper.rb

@@ -26,5 +26,7 @@ require_relative "bzapper/codec"
 require_relative "bzapper/upload"
 require_relative "bzapper/transport"
 require_relative "bzapper/resources"
+# Escrito à mão: `exportContacts` responde CSV, fora dos métodos gerados.
+require_relative "bzapper/resources/contacts_export"
 require_relative "bzapper/client"
 require_relative "bzapper/webhook"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bzapper
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Berni Software
@@ -31,6 +31,7 @@ files:
 - lib/bzapper/resources/campaigns.rb
 - lib/bzapper/resources/connect.rb
 - lib/bzapper/resources/contacts.rb
+- lib/bzapper/resources/contacts_export.rb
 - lib/bzapper/resources/conversations.rb
 - lib/bzapper/resources/groups.rb
 - lib/bzapper/resources/instances.rb