bfocus 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 427efa66516864dfd256464bb24bbda1dad9dae5d4c4df4da9b7e5f1c4cd7d7c
-  data.tar.gz: aff4271f81c03da6ffb70e16860e594f7e6428d582d79ea56fe31cfd783f472e
+  metadata.gz: 6989b99e0788e360a77f8853de9a52f5e9628db20515a2ccbb9c57fd173e4c23
+  data.tar.gz: 3e3a8766862577d33ddf9e8bb3959b380fbd995f43e97688bd7f8bf05d3a06c2
 SHA512:
-  metadata.gz: 837084970aaf2a9ee8e4f383c74787021773a0057081ea60f8adf64512813a01abf860029d3333f5d0b624c540bfc3333367c6901f4677b8439f3b1c8d159505
-  data.tar.gz: f7a941f57940c96fc38c8d7b71dc97a545f4e8edf03d06b63c4b17da7a0c8cd6b8cc13b5220a5d1f4530fa38c2f021e88c41343831492aa11bb7a096a95ba7ab
+  metadata.gz: 337c578cf5bde255220540a83297d298a89a08f97e31f72a274a25b7614c5c9b68b9cd782a95f39382ed3b858019d42a0dd16a4fc66483a281e6e43bce1e2b18
+  data.tar.gz: 5291a2a3e6b1cd5e6fd6bd7bf9d5dfb2e3abc12aa14cccc70b9fc1d2400eba5980e56edc62e2ccfa988acff36c3afb6bff13f9180cbb2e1c27f610bdc2c45716

data/README.md

@@ -1,7 +1,7 @@
 # bfocus
 
-SDK oficial em **Ruby** da API pública do [bFocus](https://bfocus.com.br): clientes, produtos,
-release notes, base de conhecimento e agentes de IA.
+SDK oficial em **Ruby** da API pública do [bFocus](https://bfocus.com.br): clientes, pessoas,
+produtos, release notes, base de conhecimento e agentes de IA.
 
 Zero dependências de runtime (só biblioteca padrão: `net/http`, `json`, `openssl`,
 `securerandom`) · Ruby 3.0+ · novas tentativas e idempotência automáticas.
@@ -93,8 +93,8 @@ Construir o cliente não faz nenhuma chamada de rede. O cliente não guarda esta
   escrita aceitam `idempotency_key:` (veja [Novas tentativas](#novas-tentativas-e-idempotência)).
 - Datas (`updated_since`) aceitam `Time`/`DateTime` — convertidos para ISO 8601 em UTC com `Z` —,
   `Date` (meia-noite UTC) ou string, que passa como veio.
-- Hashes de entrada (`custom_fields`, itens do `batch_upsert`, `history`) aceitam chaves símbolo
-  ou string.
+- Hashes de entrada (`custom_fields`, itens do `batch_upsert`/`customers.batch`/`people.batch`,
+  `history`) aceitam chaves símbolo ou string.
 
 ## Clientes
 
@@ -139,6 +139,143 @@ client.customers.interactions.list_all("ERP 1042").each do |i|
 end
 ```
 
+### Identificadores extras
+
+Ligue o id de **outro sistema seu** (CRM, loja, app…) ao mesmo cadastro: depois disso o cliente (ou
+a pessoa) é encontrado por qualquer um dos ids. É idempotente (ligar de novo não muda nada). Se o id
+já pertence a outro cadastro, a API recusa com `Bfocus::ConflictError` e `code == "IDENTIFIER_IN_USE"`.
+
+```ruby
+cliente = client.customers.identifiers.add("erp-1042", "crm-88", label: "CRM") # label é opcional
+cliente["identifiers"] # => [{"external_id" => "crm-88", "label" => "CRM", "source" => "api"}]
+client.customers.identifiers.remove("erp-1042", "crm-88")
+
+client.people.identifiers.add("app-77", "crm-p5")
+client.people.identifiers.remove("app-77", "crm-p5")
+```
+
+## Pessoas
+
+As pessoas (usuários do seu sistema) de cada cliente, em `client.people`. O `external_id` da pessoa
+é o mesmo `user_external_id` que você assina para o [widget](#identidade-do-widget).
+
+```ruby
+pessoa = client.people.upsert(
+  "erp-1042", "app-77",
+  name: "Paula Reis", email: "paula@padaria.example", role: "Financeiro", is_primary: true,
+  extra_emails: ["paula.reis@pessoal.example"]
+)
+pessoa["status"] # => "created", "updated" ou "unchanged"
+
+client.people.list("erp-1042")            # todas as pessoas do cliente
+client.people.delete("erp-1042", "app-77") # retira o acesso; a pessoa continua no histórico
+client.people.upsert("erp-1042", "app-77", access: true) # devolve o acesso
+```
+
+- **Nunca duplica.** O e-mail (ou o telefone) acha a pessoa que já chegou por e-mail, pelo widget
+  ou por outro sistema, e ela é **adotada** (ganha o seu `external_id`).
+- A mesma pessoa enviada com **outro cliente** é **transferida** para ele.
+- Como no resto da SDK, só o que você passa muda; `nil` limpa (`phone: nil`).
+- Campos: `name`, `email`, `phone`, `role`, `access` (pode usar o atendimento), `is_primary`
+  (contato principal), `extra_emails`, `extra_phones`.
+
+## Lotes — `customers.batch` e `people.batch`
+
+Até **500 itens por chamada** (`Bfocus::BATCH_MAX`). Acima disso a SDK lança `ArgumentError` antes
+de qualquer requisição — ela não divide sozinha, porque o `index` de cada resultado é a posição no
+lote que **você** enviou. Divida assim:
+
+```ruby
+clientes = meus_clientes.map do |c|
+  { external_id: "erp-#{c.id}", name: c.nome, document: c.cnpj, email: c.email }
+end
+
+clientes.each_slice(Bfocus::BATCH_MAX) do |fatia|
+  resultado = client.customers.batch(fatia)
+  resultado["results"].each do |item|
+    next unless item["status"] == "error"
+
+    warn "#{fatia[item['index']][:external_id]}: #{item['error']} (HTTP #{item['code']})"
+  end
+end
+```
+
+- Cada item de `customers.batch` é `external_id` + os campos do `customers.upsert`.
+- Cada item de `people.batch` é **plano**: `customer_external_id` + `external_id` (da pessoa) + os
+  campos do `people.upsert`.
+- Retorno: `results` (um por item: `index`, `status` — `created`/`updated`/`unchanged`/`error` —,
+  `external_id`, `merged_into`, `error` com o código estável e `code` com o status HTTP do item) +
+  `summary` (`created`, `updated`, `unchanged`, `error`).
+- **Um erro não desfaz os outros**: confira `summary["error"]` e registre os itens com erro.
+- Lista vazia devolve o resultado zerado sem fazer requisição.
+- `idempotency_key:` vale para o lote inteiro (um lote = uma chamada).
+
+## Sincronizar clientes e usuários do seu sistema
+
+**Ids com o prefixo do sistema, sem `:`.** Use `-` como separador — `erp-1042` para clientes,
+`app-77` para pessoas — ou UUIDs puros: vários sistemas seus convivem no mesmo bFocus sem colisão. A
+assinatura do widget recusa `:` (é o separador dela), então não use `:` em nenhum `external_id` de
+cliente ou pessoa.
+
+**Carga inicial (no deploy):** clientes em fatias de 500 → vincule cada um ao produto → pessoas em
+fatias de 500.
+
+```ruby
+def carga_inicial(client, clientes, usuarios)
+  clientes.each_slice(Bfocus::BATCH_MAX) do |fatia|
+    r = client.customers.batch(fatia.map { |c| { external_id: "erp-#{c.id}", name: c.nome } })
+    registrar_erros(r, fatia) if r["summary"]["error"].positive?
+  end
+
+  clientes.each { |c| client.customers.products.attach("erp-#{c.id}", "erp-cloud") }
+
+  usuarios.each_slice(Bfocus::BATCH_MAX) do |fatia|
+    itens = fatia.map do |u|
+      { customer_external_id: "erp-#{u.cliente_id}", external_id: "app-#{u.id}",
+        name: u.nome, email: u.email }
+    end
+    r = client.people.batch(itens)
+    registrar_erros(r, fatia) if r["summary"]["error"].positive?
+  end
+end
+```
+
+**Depois, no dia a dia**, espelhe cada evento do seu sistema:
+
+| No seu sistema | No bFocus |
+| --- | --- |
+| criou/alterou cliente | `customers.upsert` |
+| criou/alterou usuário | `people.upsert` |
+| excluiu/desativou usuário | `people.delete` |
+| excluiu cliente | `customers.delete` |
+
+Vincule o cliente ao produto com `customers.products.attach`. Se a resposta trouxer `merged_into`,
+o cadastro foi unificado em outro: atualize o id do seu lado.
+
+**Nunca bloqueie a requisição do seu usuário esperando o bFocus.** Enfileire (job/outbox) e tente de
+novo com backoff; a SDK já repete 429/5xx com a mesma `Idempotency-Key`, e a fila cobre
+indisponibilidades longas.
+
+```ruby
+# app/jobs/bfocus_sync_usuario_job.rb (ActiveJob; o mesmo vale para Sidekiq etc.)
+class BfocusSyncUsuarioJob < ApplicationJob
+  retry_on Bfocus::NetworkError, Bfocus::RateLimitError, Bfocus::ServerError,
+           wait: :polynomially_longer, attempts: 10
+
+  def perform(usuario_id)
+    u = Usuario.find(usuario_id)
+    if u.ativo?
+      BFOCUS.people.upsert("erp-#{u.cliente_id}", "app-#{u.id}", name: u.nome, email: u.email)
+    else
+      BFOCUS.people.delete("erp-#{u.cliente_id}", "app-#{u.id}")
+    end
+  end
+end
+
+# no model, depois de salvar — a requisição do usuário não espera o bFocus:
+after_commit { BfocusSyncUsuarioJob.perform_later(id) }
+```
+
 ## Produtos
 
 ```ruby
@@ -273,6 +410,11 @@ Todos são `Hash` com chaves string (campos novos podem aparecer a qualquer mome
 | Contato (`customers.contacts.*`) | `id`, `external_id`, `name`, `role`, `email`, `phone`, `notes`, `is_primary`, `created_at`, `updated_at` |
 | Produto vinculado (`customers.products.*`) | `id`, `slug`, `name`, `is_active` |
 | Interação (`customers.interactions.*`) | `id`, `content`, `is_internal`, `author_kind`, `author_name`, `created_at` |
+| Pessoa (`people.list`, `delete`) | `external_id` (pode ser `nil`), `name`, `email`, `phone`, `role`, `access`, `is_primary`, `customer_external_id` |
+| Pessoa gravada (`people.upsert`) | a pessoa + `status` (`created`/`updated`/`unchanged`) |
+| Cliente com identificadores (`customers.identifiers.add`, `remove`) | o cliente + `identifiers` (lista de `{external_id, label, source}`) |
+| Identificadores da pessoa (`people.identifiers.add`, `remove`) | `external_id`, `identifiers` (lista de `{external_id, label, source}`) |
+| Lote (`customers.batch`, `people.batch`) | `results` (lista de `{index, status, external_id, merged_into, error, code}`; `status` ∈ `created`/`updated`/`unchanged`/`error`), `summary` (`{created, updated, unchanged, error}`) |
 | Produto (`products.*`) | `id`, `slug`, `name`, `description`, `color`, `icon`, `is_active`, `sort_order`, `current_version`, `ai_level`, `created_at`, `updated_at` |
 | Release note (`release_notes.*`) | `id`, `product`, `version`, `title`, `description_html`, `audience`, `is_published`, `require_ack_internal`, `require_ack_external`, `published_at`, `created_at`, `updated_at` |
 | Artigo — resumo (`kb.articles.list`, `list_all`) | `id`, `external_id`, `product`, `title`, `excerpt`, `status`, `origin`, `published_at`, `created_at`, `updated_at` |
@@ -374,6 +516,28 @@ assinatura = Bfocus.sign_widget_identity(
 # que abre o widget.
 ```
 
+### Identidade do widget v2 (com validade)
+
+A v2 carimba o instante na assinatura, então uma assinatura vazada deixa de valer sozinha:
+
+```ruby
+user_hash = Bfocus.sign_widget_identity_v2(
+  ENV.fetch("BFOCUS_WIDGET_SECRET"),
+  "app-77",   # user_external_id: sem ":" (é o separador; a API recusa)
+  "erp-1042"  # customer_external_id: a empresa dele
+)
+# => "v2.<ts>.<hex>", ex.: "v2.1789000000.9c1e…"
+
+# instante explícito (segundos unix, não ms; ou Time) — útil em testes:
+Bfocus.sign_widget_identity_v2(segredo, "app-77", "erp-1042", now: 1_789_000_000)
+```
+
+- `hex` = HMAC-SHA256 em hex minúsculo de `"v2:<ts>:<user_external_id>:<customer_external_id>"`.
+- Vale de **7 dias atrás até 5 minutos à frente**: gere a cada renderização da página, **nunca
+  guarde**. Vai no mesmo lugar da v1 (`userHash` do widget).
+- O id do usuário não pode ter `:` (`ArgumentError`) — use `-` como separador (`app-77`).
+- A v1 continua aceita.
+
 ## Versões
 
 **Fixe a versão exata** (`gem "bfocus", "0.1.0"` no `Gemfile`) e suba de uma versão para a outra

data/lib/bfocus/client.rb

@@ -11,8 +11,10 @@ module Bfocus
   #   client.customers.upsert("ERP 1042", name: "Padaria Estrela")
   class Client
     # @return [Resources::Customers] clientes (empresas), com `.contacts`, `.products` e
-    #   `.interactions`.
+    #   `.interactions` e `.identifiers`.
     attr_reader :customers
+    # @return [Resources::People] pessoas (usuários) dos clientes, com `.identifiers`.
+    attr_reader :people
     # @return [Resources::Products] catálogo de produtos.
     attr_reader :products
     # @return [Resources::ReleaseNotes] release notes por produto.
@@ -52,6 +54,7 @@ module Bfocus
       @transport = Transport.new(api_key, base_url: url, timeout: timeout,
                                           max_retries: max_retries, sleeper: sleeper)
       @customers = Resources::Customers.new(@transport)
+      @people = Resources::People.new(@transport)
       @products = Resources::Products.new(@transport)
       @release_notes = Resources::ReleaseNotes.new(@transport)
       @kb = Resources::KnowledgeBase.new(@transport)

data/lib/bfocus/resources/base.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
 module Bfocus
-  # Recursos da API pública: `customers`, `products`, `release_notes`, `kb`, `ai_agents`.
+  # Máximo de itens por chamada de `customers.batch` e `people.batch`. Acima disso a SDK lança
+  # `ArgumentError` antes de qualquer requisição — ela NÃO divide sozinha, porque o `"index"` de
+  # cada resultado é a posição no lote que você enviou. Divida com `each_slice(Bfocus::BATCH_MAX)`.
+  BATCH_MAX = 500
+
+  # Recursos da API pública: `customers`, `people`, `products`, `release_notes`, `kb`, `ai_agents`.
   #
   # Convenções (iguais em todos os métodos):
   #
@@ -61,6 +66,42 @@ module Bfocus
       def compact(fields)
         Codec.compact(fields)
       end
+
+      # Resultado de um lote vazio (sem requisição).
+      def empty_batch_result
+        { "results" => [], "summary" => { "created" => 0, "updated" => 0, "unchanged" => 0, "error" => 0 } }
+      end
+
+      # Valida a lista de um lote (`customers.batch`/`people.batch`) antes de qualquer
+      # requisição e devolve os itens como Hash de chaves string (sem {UNSET}).
+      # @raise [TypeError] não é lista ou item não é Hash.
+      # @raise [ArgumentError] mais de {Bfocus::BATCH_MAX} itens.
+      def batch_items(items, op)
+        if items.is_a?(Hash) || !items.respond_to?(:each_with_index) || !items.respond_to?(:size)
+          raise TypeError, "#{op}: items precisa ser uma lista de Hash."
+        end
+        if items.size > BATCH_MAX
+          raise ArgumentError, "#{op} aceita até #{BATCH_MAX} itens por chamada (recebeu #{items.size}); " \
+                               "divida em lotes de #{BATCH_MAX}."
+        end
+
+        items.each_with_index.map do |item, index|
+          raise TypeError, "#{op}: items[#{index}] precisa ser um Hash." unless item.is_a?(Hash)
+
+          item.each_with_object({}) do |(key, value), out|
+            out[key.to_s] = value unless value.equal?(UNSET)
+          end
+        end
+      end
+
+      # Campo de id obrigatório num item de lote: String (ou número) não vazia.
+      # @raise [ArgumentError]
+      def batch_id!(item, field, op, index)
+        value = item[field]
+        return value unless value.nil? || value.to_s.empty?
+
+        raise ArgumentError, "#{op}: items[#{index}].#{field} é obrigatório."
+      end
     end
   end
 end

data/lib/bfocus/resources/customers.rb

@@ -101,8 +101,37 @@ module Bfocus
       end
     end
 
+    # Identificadores extras de um cliente — `client.customers.identifiers`: liga o id de OUTRO
+    # sistema seu (CRM, loja…) ao mesmo cadastro, que passa a ser encontrado por qualquer um deles.
+    #
+    # Retorno: o cliente + `"identifiers"` (lista de `{"external_id", "label", "source"}`).
+    # Id que já pertence a outro cadastro: `ConflictError` com `code == "IDENTIFIER_IN_USE"`.
+    class CustomerIdentifiers < Base
+      # Liga `extra_id` ao cliente (idempotente).
+      # `PUT /customers/{external_id}/identifiers/{extra_id}`
+      #
+      # @param label [String, nil] rótulo livre (ex.: `"CRM"`). Não informado = sem corpo.
+      # @return [Hash] o cliente com `"identifiers"`.
+      def add(external_id, extra_id, label: UNSET, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        extra = segment(extra_id, "extra_id")
+        body = label.equal?(UNSET) ? nil : { "label" => label }
+        call("PUT", "/customers/#{ext}/identifiers/#{extra}",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Desliga `extra_id` do cliente. `DELETE /customers/{external_id}/identifiers/{extra_id}`
+      # @return [Hash] o cliente com `"identifiers"`.
+      def remove(external_id, extra_id, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        extra = segment(extra_id, "extra_id")
+        call("DELETE", "/customers/#{ext}/identifiers/#{extra}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+
     # Clientes (empresas) — `client.customers`. Sub-recursos: {#contacts}, {#products},
-    # {#interactions}.
+    # {#interactions}, {#identifiers}.
     #
     # Cliente: `"id"`, `"external_id"`, `"name"`, `"document"`, `"email"`, `"phone"`,
     # `"website"`, `"notes"`, `"custom_fields"` (lista de `{"key", "label", "type", "value",
@@ -114,12 +143,15 @@ module Bfocus
       attr_reader :products
       # @return [CustomerInteractions]
       attr_reader :interactions
+      # @return [CustomerIdentifiers]
+      attr_reader :identifiers
 
       def initialize(transport)
         super
         @contacts = CustomerContacts.new(transport)
         @products = CustomerProducts.new(transport)
         @interactions = CustomerInteractions.new(transport)
+        @identifiers = CustomerIdentifiers.new(transport)
       end
 
       # Cria ou atualiza um cliente pelo `external_id` do seu sistema. `PUT /customers/{external_id}`
@@ -137,6 +169,31 @@ module Bfocus
         call("PUT", "/customers/#{ext}", body: body, idempotency_key: idempotency_key, timeout: timeout)
       end
 
+      # Cria/atualiza até {Bfocus::BATCH_MAX} (500) clientes numa chamada. `POST /customers/batch`
+      #
+      # Cada item (Hash, chaves string ou símbolo) tem `external_id` (obrigatório) e os mesmos
+      # campos do {#upsert}, com a mesma regra: ausente = não muda; `nil` limpa.
+      #
+      # A SDK **não divide** o lote: mais de 500 itens lança `ArgumentError` antes de qualquer
+      # requisição (use `items.each_slice(Bfocus::BATCH_MAX)`); o `"index"` de cada resultado é
+      # a posição no lote enviado. Um item com erro não desfaz os outros. Lista vazia devolve o
+      # resultado zerado sem chamar a API.
+      #
+      # @return [Hash] `{"results" => [{"index", "status", "external_id", "merged_into", "error",
+      #   "code"}, …], "summary" => {"created", "updated", "unchanged", "error"}}` —
+      #   `"status"` ∈ `created`/`updated`/`unchanged`/`error`; `"error"` é o código estável e
+      #   `"code"` o status HTTP do item.
+      # @raise [ArgumentError] mais de 500 itens ou item sem `external_id`.
+      # @raise [TypeError] `items` não é lista de Hash.
+      def batch(items, idempotency_key: nil, timeout: nil)
+        list = batch_items(items, "customers.batch")
+        return empty_batch_result if list.empty?
+
+        list.each_with_index { |item, index| batch_id!(item, "external_id", "customers.batch", index) }
+        call("POST", "/customers/batch",
+             body: { "items" => list }, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
       # Um cliente. `GET /customers/{external_id}`
       # @return [Hash]
       def get(external_id, timeout: nil)

data/lib/bfocus/resources/people.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Bfocus
+  module Resources
+    # Identificadores extras de uma pessoa — `client.people.identifiers`: liga o id de OUTRO
+    # sistema seu ao mesmo cadastro.
+    #
+    # Retorno: `{"external_id", "identifiers" => [{"external_id", "label", "source"}, …]}`.
+    # Id que já pertence a outro cadastro: `ConflictError` com `code == "IDENTIFIER_IN_USE"`.
+    class PersonIdentifiers < Base
+      # Liga `extra_id` à pessoa (idempotente). `PUT /people/{person_external_id}/identifiers/{extra_id}`
+      #
+      # @param label [String, nil] rótulo livre. Não informado = sem corpo.
+      # @return [Hash]
+      def add(person_external_id, extra_id, label: UNSET, idempotency_key: nil, timeout: nil)
+        pid = segment(person_external_id, "person_external_id")
+        extra = segment(extra_id, "extra_id")
+        body = label.equal?(UNSET) ? nil : { "label" => label }
+        call("PUT", "/people/#{pid}/identifiers/#{extra}",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Desliga `extra_id` da pessoa. `DELETE /people/{person_external_id}/identifiers/{extra_id}`
+      # @return [Hash]
+      def remove(person_external_id, extra_id, idempotency_key: nil, timeout: nil)
+        pid = segment(person_external_id, "person_external_id")
+        extra = segment(extra_id, "extra_id")
+        call("DELETE", "/people/#{pid}/identifiers/#{extra}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+
+    # Pessoas (usuários do seu sistema) de um cliente — `client.people`. Sub-recurso:
+    # {#identifiers}.
+    #
+    # Pessoa: `"external_id"` (pode ser `nil` para quem chegou por e-mail/widget sem id),
+    # `"name"`, `"email"`, `"phone"`, `"role"`, `"access"`, `"is_primary"`,
+    # `"customer_external_id"`. O `upsert` devolve também `"status"`
+    # (`"created"`/`"updated"`/`"unchanged"`).
+    #
+    # O `external_id` da pessoa é o mesmo `user_external_id` assinado no widget — por isso não
+    # pode ter `:` (use outro separador, ex.: `"app-77"`).
+    class People < Base
+      # @return [PersonIdentifiers]
+      attr_reader :identifiers
+
+      def initialize(transport)
+        super
+        @identifiers = PersonIdentifiers.new(transport)
+      end
+
+      # Cria ou atualiza uma pessoa do cliente pelo `external_id` dela.
+      # `PUT /customers/{customer_external_id}/people/{person_external_id}`
+      #
+      # Só o que vier muda; `nil` limpa. O e-mail (ou telefone) acha a pessoa que já chegou por
+      # outro caminho e ela é adotada, nunca duplicada; se ela estava em outro cliente, é
+      # transferida. `access: true` devolve o acesso retirado por {#delete}.
+      #
+      # @param access [Boolean] pode abrir chamados/usar o widget.
+      # @param is_primary [Boolean] contato principal do cliente.
+      # @param extra_emails [Array<String>] e-mails adicionais.
+      # @param extra_phones [Array<String>] telefones adicionais.
+      # @return [Hash] a pessoa + `"status"`.
+      def upsert(customer_external_id, person_external_id, name: UNSET, email: UNSET, phone: UNSET,
+                 role: UNSET, access: UNSET, is_primary: UNSET, extra_emails: UNSET, extra_phones: UNSET,
+                 idempotency_key: nil, timeout: nil)
+        cid = segment(customer_external_id, "customer_external_id")
+        pid = segment(person_external_id, "person_external_id")
+        person = compact(
+          "name" => name, "email" => email, "phone" => phone, "role" => role, "access" => access,
+          "is_primary" => is_primary, "extra_emails" => extra_emails, "extra_phones" => extra_phones
+        )
+        call("PUT", "/customers/#{cid}/people/#{pid}",
+             body: { "person" => person }, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Pessoas do cliente. `GET /customers/{customer_external_id}/people`
+      # @return [Array<Hash>]
+      def list(customer_external_id, timeout: nil)
+        call("GET", "/customers/#{segment(customer_external_id, 'customer_external_id')}/people",
+             timeout: timeout)
+      end
+
+      # Retira o acesso da pessoa (ela continua no histórico).
+      # `DELETE /customers/{customer_external_id}/people/{person_external_id}`
+      # @return [Hash] a pessoa, com `"access" => false`.
+      def delete(customer_external_id, person_external_id, idempotency_key: nil, timeout: nil)
+        cid = segment(customer_external_id, "customer_external_id")
+        pid = segment(person_external_id, "person_external_id")
+        call("DELETE", "/customers/#{cid}/people/#{pid}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Cria/atualiza até {Bfocus::BATCH_MAX} (500) pessoas numa chamada. `POST /people/batch`
+      #
+      # Cada item (Hash plano, chaves string ou símbolo): `customer_external_id` e `external_id`
+      # (da pessoa), ambos obrigatórios, + os campos do {#upsert} (ausente = não muda; `nil`
+      # limpa). No fio vira `{"customer_external_id" => …, "person" => {"external_id" => …, …}}`.
+      #
+      # A SDK **não divide** o lote: mais de 500 itens lança `ArgumentError` antes de qualquer
+      # requisição (use `items.each_slice(Bfocus::BATCH_MAX)`); o `"index"` de cada resultado é
+      # a posição no lote enviado. Um item com erro não desfaz os outros. Lista vazia devolve o
+      # resultado zerado sem chamar a API.
+      #
+      # @return [Hash] `{"results" => [{"index", "status", "external_id", "merged_into", "error",
+      #   "code"}, …], "summary" => {"created", "updated", "unchanged", "error"}}`
+      # @raise [ArgumentError] mais de 500 itens ou item sem `customer_external_id`/`external_id`.
+      # @raise [TypeError] `items` não é lista de Hash.
+      def batch(items, idempotency_key: nil, timeout: nil)
+        list = batch_items(items, "people.batch")
+        return empty_batch_result if list.empty?
+
+        wire = list.each_with_index.map do |item, index|
+          customer = batch_id!(item, "customer_external_id", "people.batch", index)
+          batch_id!(item, "external_id", "people.batch", index)
+          { "customer_external_id" => customer, "person" => item.reject { |key, _| key == "customer_external_id" } }
+        end
+        call("POST", "/people/batch",
+             body: { "items" => wire }, idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/bfocus/version.rb

@@ -3,5 +3,5 @@
 module Bfocus
   # Versão da gem. O `scripts/release-sdks.sh` do monorepo bumpa esta linha por regex e o
   # `bfocus.gemspec` lê daqui — mantenha o formato exato `VERSION = "X.Y.Z"`.
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/bfocus/widget.rb

@@ -27,4 +27,53 @@ module Bfocus
     message = "v1:".b + utf8.call(user_external_id) + ":".b + utf8.call(customer_external_id)
     OpenSSL::HMAC.hexdigest("SHA256", utf8.call(secret), message)
   end
+
+  # Identidade do widget **v2 (com validade)**: como {sign_widget_identity}, mas carimbada com o
+  # instante. Roda no seu backend, sem rede e sem chave de API.
+  #
+  # Devolve `"v2.<ts>.<hex>"`: `ts` = segundos unix inteiros do instante (padrão: agora) e `hex`
+  # = HMAC-SHA256, em hexadecimal minúsculo, de
+  # `"v2:" + ts + ":" + user_external_id + ":" + customer_external_id` (UTF-8). A API aceita de
+  # 7 dias atrás até 5 minutos à frente — gere a cada renderização da página, nunca guarde. Vai
+  # no mesmo lugar da v1 (`userHash` do widget); a v1 continua aceita.
+  #
+  # @param secret [String] segredo de identidade do widget (painel do bFocus).
+  # @param user_external_id [String] `external_id` do usuário (a pessoa) no seu sistema — sem
+  #   `:` (é o separador; a API recusa).
+  # @param customer_external_id [String] `external_id` do cliente (empresa). Prefira `-` a `:` nos
+  #   seus ids (ex.: `"erp-1042"`).
+  # @param now [Integer, Time, nil] instante da assinatura: segundos unix (não ms) ou `Time`.
+  #   Padrão: agora.
+  # @return [String] `"v2.<ts>.<64 hex>"`.
+  # @raise [ArgumentError] segredo vazio, id `nil`, `:` no id do usuário, instante negativo ou de
+  #   tipo inválido.
+  #
+  # @example
+  #   Bfocus.sign_widget_identity_v2(ENV.fetch("BFOCUS_WIDGET_SECRET"), "app-77", "erp-1042")
+  #   # => "v2.<ts>.<hex>"
+  def self.sign_widget_identity_v2(secret, user_external_id, customer_external_id, now: nil)
+    raise ArgumentError, "sign_widget_identity_v2: secret é obrigatório." if secret.nil? || secret.to_s.empty?
+    raise ArgumentError, "sign_widget_identity_v2: user_external_id é obrigatório." if user_external_id.nil?
+    raise ArgumentError, "sign_widget_identity_v2: customer_external_id é obrigatório." if customer_external_id.nil?
+    if user_external_id.to_s.include?(":")
+      raise ArgumentError, "sign_widget_identity_v2: user_external_id não pode ter ':' (é o separador; " \
+                           "a API recusa) — use outro, ex.: \"app-77\": #{user_external_id.to_s.inspect}"
+    end
+
+    ts = case now
+         when nil then Time.now.to_i
+         when Time then now.to_i
+         when Integer then now
+         else
+           raise ArgumentError, "sign_widget_identity_v2: now precisa ser Integer (segundos unix) ou Time."
+         end
+    raise ArgumentError, "sign_widget_identity_v2: now não pode ser negativo (#{ts})." if ts.negative?
+
+    utf8 = lambda do |value|
+      text = value.to_s
+      (text.encoding == ::Encoding::BINARY ? text : text.encode(::Encoding::UTF_8)).b
+    end
+    message = "v2:#{ts}:".b + utf8.call(user_external_id) + ":".b + utf8.call(customer_external_id)
+    "v2.#{ts}.#{OpenSSL::HMAC.hexdigest('SHA256', utf8.call(secret), message)}"
+  end
 end

data/lib/bfocus.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# SDK oficial em Ruby da API pública do bFocus: clientes, produtos, release notes, base de
+# SDK oficial em Ruby da API pública do bFocus: clientes, pessoas, produtos, release notes, base de
 # conhecimento e agentes de IA. Só biblioteca padrão (net/http, json, openssl, securerandom).
 #
 # @example
@@ -26,6 +26,7 @@ require_relative "bfocus/codec"
 require_relative "bfocus/transport"
 require_relative "bfocus/resources/base"
 require_relative "bfocus/resources/customers"
+require_relative "bfocus/resources/people"
 require_relative "bfocus/resources/products"
 require_relative "bfocus/resources/release_notes"
 require_relative "bfocus/resources/knowledge_base"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bfocus
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Berni Software
@@ -28,6 +28,7 @@ files:
 - lib/bfocus/resources/base.rb
 - lib/bfocus/resources/customers.rb
 - lib/bfocus/resources/knowledge_base.rb
+- lib/bfocus/resources/people.rb
 - lib/bfocus/resources/products.rb
 - lib/bfocus/resources/release_notes.rb
 - lib/bfocus/transport.rb