bzapper 0.7.1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c30f72803594b155b3d1e19c4f375b634de0c9da69ffed8487f598e27e281661
-  data.tar.gz: e303cafe2aea6f5174c67cc11201d52213ec7dd8290cf75357402f475693533f
+  metadata.gz: 2492fe46b1c91f8b88b673e102de183388ec0aeba9686f83de3d62b50eb4cc01
+  data.tar.gz: 57c3253532c2a83d67cbbc21b811fc05f97a2c7ac331462fc7d4b60f4bb8a0c2
 SHA512:
-  metadata.gz: 634a810f034b09f0389c1f2dc4ff95de5c13fee9c5cd1196eee55d83b644e7df03178a313a1165fde6f090556195a1ec428c8df1b18c5b8f9c7ba9439cd040c1
-  data.tar.gz: 8045dda0d3906b6c43bc60f4750891d5e754464d80fea1fdc277e7ff253cab428a5125e255faf68bb06fe43da49b18c13617f1fe016ec835c40241dcf2e49f99
+  metadata.gz: 60d10efd60798233d8c40d2f006da6d322d38af941a86d06cb148230ec6cf3a9df435a70a1db49f2630319781b76199e75fac7c2d736bdaf38a2e943279bd926
+  data.tar.gz: cfee6f2f48d55e3a40934cb509e85ac5832b42f76c1e677dd17d8f8f0f5384f0b617cc22ba25535c3375f7591ef8f959fc90a56cf3acd523696c170fab569287

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.1
+gem install bzapper -v 0.8.1
 ```
 
 Ou no `Gemfile` — **fixe a versão exata** (cada release declara se muda a superfície pública):
 
 ```ruby
-gem "bzapper", "0.7.1"
+gem "bzapper", "0.8.1"
 ```
 
 ## 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

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

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/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).

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/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.1"
+  VERSION = "0.8.1"
 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.1
+  version: 0.8.1
 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