bfocus 0.1.0

data/lib/bfocus/errors.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Bfocus
+  # Erro devolvido pela API do bFocus (ou de rede, em {NetworkError}).
+  #
+  # Toda resposta fora de 2xx vira um `Bfocus::Error` — ou a subclasse do status. **Use
+  # {#code} na sua lógica**: ele é estável (`CUSTOMER_NOT_FOUND`, `INTEGRATION_SCOPE_MISSING`…).
+  # O {#message} é texto para humanos e pode mudar.
+  #
+  # Argumento inválido no seu código (chave vazia, parâmetro de caminho vazio/"."/"..", `/`
+  # no `external_id` de artigo) NÃO é `Bfocus::Error`: é `ArgumentError`/`TypeError`, na hora.
+  class Error < StandardError
+    # @return [String] código estável: `body.error`, senão `body.message`, senão
+    #   `HTTP_<status>` (corpo não-JSON); `INVALID_RESPONSE` quando um 2xx chega sem o
+    #   envelope JSON da API; `NETWORK_ERROR` em falha de rede.
+    attr_reader :code
+    # @return [Integer] status HTTP (`0` em erro de rede).
+    attr_reader :status
+    # @return [String, nil] `request_id` do corpo, senão o header `X-Request-Id`, senão o
+    #   `X-Request-Id` que a SDK enviou (a API ecoa o do cliente). Informe-o ao suporte.
+    attr_reader :request_id
+    # @return [Hash{String=>String}] motivos por campo (erros de validação); `{}` quando não há.
+    attr_reader :validation
+    # @return [Integer, Float, nil] segundos do header `Retry-After` (só em 429).
+    attr_reader :retry_after
+    # @return [String, nil] escopo que faltou na chave (header `X-Required-Scope`, só em 403).
+    attr_reader :required_scope
+    # @return [Hash, String, nil] corpo da resposta decodificado, ou o texto cru se não é JSON.
+    attr_reader :body
+
+    def initialize(message = nil, code: nil, status: 0, request_id: nil, validation: nil,
+                   retry_after: nil, required_scope: nil, body: nil)
+      @code = code
+      @status = status
+      @request_id = request_id
+      @validation = validation.is_a?(Hash) ? validation.dup : {}
+      @retry_after = retry_after
+      @required_scope = required_scope
+      @body = body
+      text = message || code || self.class.name
+      text = "#{text} [request_id=#{request_id}]" if request_id && !text.include?(request_id)
+      super(text)
+    end
+
+    def inspect
+      "#<#{self.class.name} code=#{code.inspect} status=#{status.inspect} " \
+        "request_id=#{request_id.inspect}>"
+    end
+
+    STATUS_CLASSES = {} # preenchido abaixo, depois das subclasses
+    private_constant :STATUS_CLASSES
+
+    # Classe de erro para um status HTTP (5xx → {ServerError}; sem classe própria → a base).
+    # @param status [Integer]
+    # @return [Class]
+    def self.class_for(status)
+      return STATUS_CLASSES[status] if STATUS_CLASSES.key?(status)
+      return ServerError if status >= 500 && status <= 599
+
+      Error
+    end
+  end
+
+  # 401 — chave ausente, inválida ou revogada.
+  class AuthenticationError < Error; end
+
+  # 403 — chave desligada, IP não liberado, escopo faltando ({#required_scope}) ou módulo não
+  # contratado (`MODULE_NOT_CONTRACTED`: base de conhecimento e agentes de IA exigem o módulo
+  # de Atendimento).
+  class PermissionDeniedError < Error; end
+
+  # 404 — o recurso (ou a conta) não existe.
+  class NotFoundError < Error; end
+
+  # 409 — o estado atual impede a operação (ex.: `KB_ARTICLE_EMPTY`, `AI_DISABLED`).
+  class ConflictError < Error; end
+
+  # 422 — corpo ou parâmetro inválido; os motivos por campo estão em {#validation}.
+  class ValidationError < Error; end
+
+  # 429 — limite de requisições da chave; {#retry_after} diz quanto esperar.
+  class RateLimitError < Error; end
+
+  # 5xx — erro do lado da API. Informe o {#request_id}.
+  class ServerError < Error; end
+
+  # Falha de conexão ou timeout (`status == 0`, `code == "NETWORK_ERROR"`).
+  class NetworkError < Error
+    def initialize(message = nil, request_id: nil, **_ignored)
+      super(message || "NETWORK_ERROR", code: "NETWORK_ERROR", status: 0, request_id: request_id)
+    end
+  end
+
+  class Error
+    STATUS_CLASSES.merge!(
+      401 => AuthenticationError,
+      403 => PermissionDeniedError,
+      404 => NotFoundError,
+      409 => ConflictError,
+      422 => ValidationError,
+      429 => RateLimitError
+    ).freeze
+  end
+end

data/lib/bfocus/page.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Bfocus
+  # Uma página de resultados das listas paginadas (`customers.list`, `interactions.list`,
+  # `release_notes.list`, `kb.articles.list`). É `Enumerable` sobre {#items}.
+  #
+  # Para percorrer tudo sem controlar páginas, use o `list_all(...)` do recurso.
+  #
+  # @example
+  #   page = client.customers.list(q: "padaria", page_size: 50)
+  #   page.total          # => 123
+  #   page.map { |c| c["name"] }
+  #   page.next_page?     # => true
+  class Page
+    include Enumerable
+
+    # @return [Array<Hash{String=>Object}>] itens da página (Hash com chaves string).
+    attr_reader :items
+    # @return [Integer] número desta página (1-based).
+    attr_reader :page
+    # @return [Integer] tamanho de página usado pela API.
+    attr_reader :page_size
+    # @return [Integer] total de itens (todas as páginas).
+    attr_reader :total
+    # @return [Integer] total de páginas.
+    attr_reader :pages
+
+    def initialize(items:, page:, page_size:, total:, pages:)
+      @items = items
+      @page = page
+      @page_size = page_size
+      @total = total
+      @pages = pages
+    end
+
+    # Monta a página a partir do `data` + `pagination` do envelope da API.
+    # @api private
+    def self.from_response(data, pagination)
+      items = data.is_a?(Array) ? data : []
+      unless pagination.is_a?(Hash) # a API sempre manda; defensivo para não quebrar a iteração
+        return new(items: items, page: 1, page_size: items.size, total: items.size, pages: 1)
+      end
+
+      new(
+        items: items,
+        page: (pagination["page"] || 1).to_i,
+        page_size: (pagination["page_size"] || items.size).to_i,
+        total: (pagination["total"] || items.size).to_i,
+        pages: (pagination["pages"] || 1).to_i
+      )
+    end
+
+    def each(&block)
+      return enum_for(:each) { size } unless block
+
+      items.each(&block)
+      self
+    end
+
+    # @return [Integer] quantidade de itens NESTA página.
+    def size
+      items.size
+    end
+    alias length size
+
+    def empty?
+      items.empty?
+    end
+
+    # @return [Boolean] `true` se existe página depois desta.
+    def next_page?
+      page < pages
+    end
+
+    # @return [Hash{Symbol=>Object}] `{items:, page:, page_size:, total:, pages:}`
+    def to_h
+      { items: items, page: page, page_size: page_size, total: total, pages: pages }
+    end
+
+    def ==(other)
+      other.is_a?(Page) && to_h == other.to_h
+    end
+    alias eql? ==
+
+    def hash
+      to_h.hash
+    end
+
+    def inspect
+      "#<Bfocus::Page page=#{page}/#{pages} page_size=#{page_size} total=#{total} " \
+        "items=#{items.size}>"
+    end
+  end
+end

data/lib/bfocus/resources/ai_agents.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Bfocus
+  module Resources
+    # Agentes de IA — `client.ai_agents`. Exige o módulo de Atendimento.
+    #
+    # Agente: `"id"`, `"name"`, `"product"` (`{"id", "slug", "name", "is_active"}`), `"active"`,
+    # `"persona"`, `"scope"`, `"avatar_url"`, `"created_at"`, `"updated_at"`.
+    class AIAgents < Base
+      # Agentes de IA da conta. `GET /ai-agents`
+      # @return [Array<Hash>]
+      def list(timeout: nil)
+        call("GET", "/ai-agents", timeout: timeout)
+      end
+
+      # Um agente. `GET /ai-agents/{agent_id}`
+      # @return [Hash]
+      def get(agent_id, timeout: nil)
+        call("GET", "/ai-agents/#{segment(agent_id, 'agent_id')}", timeout: timeout)
+      end
+
+      # Testa a resposta do agente a uma mensagem (consome IA da conta).
+      # `POST /ai-agents/{agent_id}/preview`
+      #
+      # @param history [Array<Hash>] turnos anteriores, `[{role: "customer"|"bot", content: "…"}]`
+      #   (até 20).
+      # @return [Hash] `"action"` (`answer`, `handoff` ou `refuse`), `"answer_html"`,
+      #   `"escalated"`, `"refused"`, `"handoff_reason"`, `"confidence"`, `"topic"`, `"guards"`,
+      #   `"citations"`, `"sources"`, `"collected"`, `"missing"`.
+      def preview(agent_id, message, history: UNSET, idempotency_key: nil, timeout: nil)
+        body = compact("message" => message, "history" => history)
+        call("POST", "/ai-agents/#{segment(agent_id, 'agent_id')}/preview",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/bfocus/resources/base.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Bfocus
+  # Recursos da API pública: `customers`, `products`, `release_notes`, `kb`, `ai_agents`.
+  #
+  # Convenções (iguais em todos os métodos):
+  #
+  # * Obrigatórios são posicionais; opcionais são keyword args.
+  # * Campos de corpo opcionais têm padrão {Bfocus::UNSET} — não informado = não enviado.
+  #   `nil` explícito vai como `null` e **limpa** o campo na API.
+  # * Filtros de query com `nil` são omitidos.
+  # * Toda chamada aceita `timeout:` (segundos, por tentativa); as escritas aceitam
+  #   `idempotency_key:` (senão a SDK gera uma e a repete nas novas tentativas).
+  # * O retorno é o `data` da resposta: `Hash`/`Array` com chaves **string**, exatamente como a
+  #   API devolve (campos novos aparecem sem quebrar nada). Listas paginadas devolvem {Page}.
+  module Resources
+    # @api private
+    class Base
+      def initialize(transport)
+        @transport = transport
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      def call(method, path, query: nil, body: nil, idempotency_key: nil, timeout: nil)
+        data, _pagination = @transport.request(
+          method, path,
+          query: query, body: body, idempotency_key: idempotency_key, timeout: timeout
+        )
+        data
+      end
+
+      def paged(path, query, timeout)
+        data, pagination = @transport.request("GET", path, query: query, timeout: timeout)
+        Page.from_response(data, pagination)
+      end
+
+      # Enumerator::Lazy que busca página por página (cada uma é uma chamada lógica nova) e
+      # para quando `page >= pages` ou a página vem vazia.
+      def iterate(&fetch)
+        Enumerator.new do |yielder|
+          number = 1
+          while true # rubocop:disable Style/InfiniteLoop
+            current = fetch.call(number)
+            current.items.each { |item| yielder << item }
+            break if current.items.empty? || current.page >= current.pages
+
+            number += 1
+          end
+        end.lazy
+      end
+
+      def segment(value, name)
+        Codec.path_segment(value, name)
+      end
+
+      def compact(fields)
+        Codec.compact(fields)
+      end
+    end
+  end
+end

data/lib/bfocus/resources/customers.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Bfocus
+  module Resources
+    # Contatos (pessoas) de um cliente — `client.customers.contacts`.
+    #
+    # Contato: `"id"`, `"external_id"`, `"name"`, `"role"`, `"email"`, `"phone"`, `"notes"`,
+    # `"is_primary"`, `"created_at"`, `"updated_at"`.
+    class CustomerContacts < Base
+      # Contatos do cliente. `GET /customers/{external_id}/contacts`
+      # @return [Array<Hash>]
+      def list(external_id, timeout: nil)
+        call("GET", "/customers/#{segment(external_id, 'external_id')}/contacts", timeout: timeout)
+      end
+
+      # Cria ou atualiza um contato pelo `external_id` dele. Só o que vier muda; `nil` limpa.
+      # `PUT /customers/{external_id}/contacts/{contact_external_id}`
+      # @return [Hash] o contato.
+      def upsert(external_id, contact_external_id, name: UNSET, role: UNSET, email: UNSET,
+                 phone: UNSET, notes: UNSET, is_primary: UNSET, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        cext = segment(contact_external_id, "contact_external_id")
+        body = compact(
+          "name" => name, "role" => role, "email" => email, "phone" => phone,
+          "notes" => notes, "is_primary" => is_primary
+        )
+        call("PUT", "/customers/#{ext}/contacts/#{cext}",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Remove um contato. `DELETE /customers/{external_id}/contacts/{contact_external_id}`
+      # @return [Hash] `{"deleted" => true}`
+      def delete(external_id, contact_external_id, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        cext = segment(contact_external_id, "contact_external_id")
+        call("DELETE", "/customers/#{ext}/contacts/#{cext}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+
+    # Produtos vinculados a um cliente — `client.customers.products`.
+    #
+    # Produto vinculado: `"id"`, `"slug"`, `"name"`, `"is_active"`.
+    class CustomerProducts < Base
+      # Produtos do cliente. `GET /customers/{external_id}/products`
+      # @return [Array<Hash>]
+      def list(external_id, timeout: nil)
+        call("GET", "/customers/#{segment(external_id, 'external_id')}/products", timeout: timeout)
+      end
+
+      # Vincula um produto ao cliente (idempotente). `PUT /customers/{external_id}/products/{slug}`
+      # @return [Hash] o produto vinculado.
+      def attach(external_id, product_slug, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        slug = segment(product_slug, "product_slug")
+        call("PUT", "/customers/#{ext}/products/#{slug}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Desvincula um produto. `DELETE /customers/{external_id}/products/{slug}`
+      # @return [Hash] `{"deleted" => true}`
+      def detach(external_id, product_slug, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        slug = segment(product_slug, "product_slug")
+        call("DELETE", "/customers/#{ext}/products/#{slug}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+
+    # Histórico de interações de um cliente — `client.customers.interactions`.
+    #
+    # Interação: `"id"`, `"content"`, `"is_internal"`, `"author_kind"`, `"author_name"`,
+    # `"created_at"`.
+    class CustomerInteractions < Base
+      # Uma página de interações. `GET /customers/{external_id}/interactions`
+      # @return [Bfocus::Page]
+      def list(external_id, page: nil, page_size: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        paged("/customers/#{ext}/interactions", { "page" => page, "page_size" => page_size }, timeout)
+      end
+
+      # Todas as interações, página a página (`page_size` padrão 100).
+      # @return [Enumerator::Lazy<Hash>]
+      def list_all(external_id, page_size: 100, timeout: nil)
+        segment(external_id, "external_id") # valida já, não na 1ª iteração
+        iterate { |number| list(external_id, page: number, page_size: page_size, timeout: timeout) }
+      end
+
+      # Registra uma interação (nota) no cliente. `POST /customers/{external_id}/interactions`
+      #
+      # @param content [String] texto/HTML da interação.
+      # @param is_internal [Boolean] nota interna (padrão da API: `true`).
+      # @param author_email [String, nil] e-mail de um usuário do bFocus para constar como autor.
+      # @return [Hash] a interação.
+      def create(external_id, content, is_internal: UNSET, author_email: UNSET,
+                 idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        body = compact("content" => content, "is_internal" => is_internal, "author_email" => author_email)
+        call("POST", "/customers/#{ext}/interactions",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+
+    # Clientes (empresas) — `client.customers`. Sub-recursos: {#contacts}, {#products},
+    # {#interactions}.
+    #
+    # Cliente: `"id"`, `"external_id"`, `"name"`, `"document"`, `"email"`, `"phone"`,
+    # `"website"`, `"notes"`, `"custom_fields"` (lista de `{"key", "label", "type", "value",
+    # "visibility"}`), `"is_active"`, `"created_at"`, `"updated_at"`.
+    class Customers < Base
+      # @return [CustomerContacts]
+      attr_reader :contacts
+      # @return [CustomerProducts]
+      attr_reader :products
+      # @return [CustomerInteractions]
+      attr_reader :interactions
+
+      def initialize(transport)
+        super
+        @contacts = CustomerContacts.new(transport)
+        @products = CustomerProducts.new(transport)
+        @interactions = CustomerInteractions.new(transport)
+      end
+
+      # Cria ou atualiza um cliente pelo `external_id` do seu sistema. `PUT /customers/{external_id}`
+      #
+      # Só os campos informados mudam; `nil` limpa. `custom_fields` (lista de
+      # `{key:, label:, type:, value:, options:}`), quando enviado, **substitui** a lista inteira.
+      # @return [Hash] o cliente.
+      def upsert(external_id, name: UNSET, document: UNSET, email: UNSET, phone: UNSET,
+                 website: UNSET, notes: UNSET, custom_fields: UNSET, idempotency_key: nil, timeout: nil)
+        ext = segment(external_id, "external_id")
+        body = compact(
+          "name" => name, "document" => document, "email" => email, "phone" => phone,
+          "website" => website, "notes" => notes, "custom_fields" => custom_fields
+        )
+        call("PUT", "/customers/#{ext}", body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Um cliente. `GET /customers/{external_id}`
+      # @return [Hash]
+      def get(external_id, timeout: nil)
+        call("GET", "/customers/#{segment(external_id, 'external_id')}", timeout: timeout)
+      end
+
+      # Uma página de clientes. `GET /customers`
+      #
+      # @param q [String, nil] busca por nome/documento/e-mail.
+      # @param updated_since [Time, DateTime, Date, String, nil] só os alterados a partir deste
+      #   instante (`Time` vira ISO 8601 UTC com `Z`; string passa como veio).
+      # @return [Bfocus::Page]
+      def list(q: nil, updated_since: nil, page: nil, page_size: nil, timeout: nil)
+        query = { "q" => q, "updated_since" => updated_since, "page" => page, "page_size" => page_size }
+        paged("/customers", query, timeout)
+      end
+
+      # Todos os clientes, página a página (`page_size` padrão 100). Ideal para sincronização
+      # incremental: guarde o instante da última rodada e passe em `updated_since`.
+      # @return [Enumerator::Lazy<Hash>]
+      def list_all(q: nil, updated_since: nil, page_size: 100, timeout: nil)
+        iterate do |number|
+          list(q: q, updated_since: updated_since, page: number, page_size: page_size, timeout: timeout)
+        end
+      end
+
+      # Exclui um cliente. `DELETE /customers/{external_id}`
+      # @return [Hash] `{"deleted" => true}`
+      def delete(external_id, idempotency_key: nil, timeout: nil)
+        call("DELETE", "/customers/#{segment(external_id, 'external_id')}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/bfocus/resources/knowledge_base.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Bfocus
+  module Resources
+    # Artigos da base de conhecimento — `client.kb.articles`. Exige o módulo de Atendimento
+    # (sem ele: `PermissionDeniedError` com `code == "MODULE_NOT_CONTRACTED"`).
+    #
+    # Artigo (resumo — `list`, `list_all`, `batch_upsert`): `"id"`, `"external_id"`,
+    # `"product"`, `"title"`, `"excerpt"`, `"status"`, `"origin"`, `"published_at"`,
+    # `"created_at"`, `"updated_at"`. Artigo completo (`get`, `upsert`, `publish`,
+    # `unpublish`): o resumo + `"body_html"`.
+    class KBArticles < Base
+      # Limite da API por requisição de {#batch_upsert}; a SDK divide acima disso.
+      BATCH_SIZE = 100
+
+      # Uma página de artigos (resumo, sem `body_html`). `GET /kb/articles`
+      #
+      # @param product [String, nil] slug do produto.
+      # @param status [String, nil] `"draft"` ou `"published"`.
+      # @param q [String, nil] busca no título e no texto.
+      # @param updated_since [Time, DateTime, Date, String, nil]
+      # @return [Bfocus::Page]
+      def list(product: nil, status: nil, q: nil, updated_since: nil, page: nil, page_size: nil, timeout: nil)
+        query = {
+          "product" => product, "status" => status, "q" => q, "updated_since" => updated_since,
+          "page" => page, "page_size" => page_size
+        }
+        paged("/kb/articles", query, timeout)
+      end
+
+      # Todos os artigos (com os filtros), página a página (`page_size` padrão 100).
+      # @return [Enumerator::Lazy<Hash>]
+      def list_all(product: nil, status: nil, q: nil, updated_since: nil, page_size: 100, timeout: nil)
+        iterate do |number|
+          list(product: product, status: status, q: q, updated_since: updated_since,
+               page: number, page_size: page_size, timeout: timeout)
+        end
+      end
+
+      # Um artigo (com `body_html`). `GET /kb/articles/{external_id}`
+      # @return [Hash]
+      def get(external_id, timeout: nil)
+        call("GET", "/kb/articles/#{article_id(external_id)}", timeout: timeout)
+      end
+
+      # Cria ou atualiza um artigo pelo `external_id` (sem `/`; use `:`).
+      # `PUT /kb/articles/{external_id}`. `product: nil` (explícito) torna o artigo global;
+      # `status: "published"` publica.
+      # @return [Hash] o artigo completo.
+      def upsert(external_id, title: UNSET, body_html: UNSET, body_markdown: UNSET,
+                 product: UNSET, status: UNSET, idempotency_key: nil, timeout: nil)
+        body = compact(
+          "title" => title, "body_html" => body_html, "body_markdown" => body_markdown,
+          "product" => product, "status" => status
+        )
+        call("PUT", "/kb/articles/#{article_id(external_id)}",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Cria/atualiza **qualquer quantidade** de artigos. `POST /kb/articles/batch`
+      #
+      # A SDK divide em lotes de 100 (limite da API), envia em sequência e devolve UM
+      # resultado: `"results"` na ordem enviada e contadores somados. Falha de um item não
+      # derruba os outros (`"ok" => false` + `"error"` no resultado dele). Lista vazia devolve
+      # o resultado zerado sem chamar a API.
+      #
+      # Cada item (Hash, chaves string ou símbolo) precisa de `external_id`; os demais campos
+      # seguem a regra do {#upsert} (ausente = não muda; `product: nil` = global).
+      #
+      # Se um lote falhar por inteiro (rede, 429 esgotado…), o erro sobe e os lotes anteriores
+      # já foram aplicados — rodar de novo é seguro (é upsert).
+      #
+      # @param idempotency_key [String, nil] o 1º lote usa a chave como veio; os seguintes,
+      #   `"<chave>:<n>"` (n = 2, 3, …). Sem chave, cada lote gera a sua.
+      # @return [Hash] `{"results" => [{"external_id", "ok", "action", "error", "article"}, …],
+      #   "created", "updated", "unchanged", "failed"}`
+      def batch_upsert(articles, idempotency_key: nil, timeout: nil)
+        if articles.is_a?(Hash) || !articles.respond_to?(:each_with_index)
+          raise TypeError, "articles precisa ser uma lista de Hash."
+        end
+
+        items = articles.each_with_index.map { |article, index| batch_item(article, index) }
+        outcome = { "results" => [], "created" => 0, "updated" => 0, "unchanged" => 0, "failed" => 0 }
+        user_key = idempotency_key.to_s
+        items.each_slice(BATCH_SIZE).with_index(1) do |chunk, number|
+          key = user_key.empty? ? nil : user_key
+          key = "#{key}:#{number}" if key && number > 1
+          data = call("POST", "/kb/articles/batch",
+                      body: { "articles" => chunk }, idempotency_key: key, timeout: timeout)
+          merge_outcome(outcome, data)
+        end
+        outcome
+      end
+
+      # Publica um artigo. `POST /kb/articles/{external_id}/publish`
+      # @return [Hash] o artigo completo.
+      def publish(external_id, idempotency_key: nil, timeout: nil)
+        call("POST", "/kb/articles/#{article_id(external_id)}/publish",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Volta um artigo para rascunho. `POST /kb/articles/{external_id}/unpublish`
+      # @return [Hash] o artigo completo.
+      def unpublish(external_id, idempotency_key: nil, timeout: nil)
+        call("POST", "/kb/articles/#{article_id(external_id)}/unpublish",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Exclui um artigo. `DELETE /kb/articles/{external_id}`
+      # @return [Hash] `{"deleted" => true}`
+      def delete(external_id, idempotency_key: nil, timeout: nil)
+        call("DELETE", "/kb/articles/#{article_id(external_id)}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      private
+
+      def article_id(external_id)
+        Codec.path_segment(external_id, "external_id", allow_slash: false)
+      end
+
+      def batch_item(article, index)
+        raise TypeError, "articles[#{index}] precisa ser um Hash." unless article.is_a?(Hash)
+
+        item = article.each_with_object({}) do |(key, value), out|
+          out[key.to_s] = value unless value.equal?(UNSET)
+        end
+        ext = item["external_id"]
+        unless ext.is_a?(String) && !ext.empty?
+          raise ArgumentError, "articles[#{index}]: external_id é obrigatório."
+        end
+        if ext.include?("/")
+          raise ArgumentError, "articles[#{index}]: external_id não aceita '/' — use ':' (#{ext.inspect})"
+        end
+
+        item
+      end
+
+      def merge_outcome(outcome, data)
+        return unless data.is_a?(Hash)
+
+        data.each do |field, value|
+          if field == "results"
+            outcome["results"].concat(value) if value.is_a?(Array)
+          elsif value.is_a?(Integer)
+            outcome[field] = outcome[field].to_i + value
+          else # campo novo não numérico: preservado (o último lote vence)
+            outcome[field] = value
+          end
+        end
+      end
+    end
+
+    # Base de conhecimento — `client.kb` (artigos em {#articles}). Exige o módulo de
+    # Atendimento.
+    class KnowledgeBase < Base
+      # @return [KBArticles]
+      attr_reader :articles
+
+      def initialize(transport)
+        super
+        @articles = KBArticles.new(transport)
+      end
+
+      # Busca semântica/textual nos artigos publicados. `GET /kb/search`
+      #
+      # @param q [String] pergunta ou termos.
+      # @param product [String, nil] slug do produto para restringir.
+      # @param limit [Integer, nil] máximo de resultados (padrão da API: 5; máximo 20).
+      # @return [Array<Hash>] `{"id", "external_id", "title", "excerpt"}`
+      def search(q, product: nil, limit: nil, timeout: nil)
+        call("GET", "/kb/search", query: { "q" => q, "product" => product, "limit" => limit }, timeout: timeout)
+      end
+    end
+  end
+end