bfocus 0.1.0

data/lib/bfocus/resources/products.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Bfocus
+  module Resources
+    # Catálogo de produtos — `client.products`.
+    #
+    # Produto: `"id"`, `"slug"`, `"name"`, `"description"`, `"color"`, `"icon"`, `"is_active"`,
+    # `"sort_order"`, `"current_version"`, `"ai_level"`, `"created_at"`, `"updated_at"`.
+    class Products < Base
+      # Produtos do catálogo. `GET /products`
+      # @param include_inactive [Boolean, nil] `true` inclui os arquivados.
+      # @return [Array<Hash>]
+      def list(include_inactive: nil, timeout: nil)
+        call("GET", "/products", query: { "include_inactive" => include_inactive }, timeout: timeout)
+      end
+
+      # Um produto. `GET /products/{slug}`
+      # @return [Hash]
+      def get(slug, timeout: nil)
+        call("GET", "/products/#{segment(slug, 'slug')}", timeout: timeout)
+      end
+
+      # Cria ou atualiza um produto pelo `slug`. Só o que vier muda. `PUT /products/{slug}`
+      # @return [Hash] o produto.
+      def upsert(slug, name: UNSET, description: UNSET, color: UNSET, icon: UNSET,
+                 is_active: UNSET, sort_order: UNSET, idempotency_key: nil, timeout: nil)
+        body = compact(
+          "name" => name, "description" => description, "color" => color, "icon" => icon,
+          "is_active" => is_active, "sort_order" => sort_order
+        )
+        call("PUT", "/products/#{segment(slug, 'slug')}",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Arquiva um produto (não apaga). `DELETE /products/{slug}`
+      # @return [Hash] o produto, com `"is_active" => false`.
+      def archive(slug, idempotency_key: nil, timeout: nil)
+        call("DELETE", "/products/#{segment(slug, 'slug')}",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+    end
+  end
+end

data/lib/bfocus/resources/release_notes.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Bfocus
+  module Resources
+    # Release notes por produto — `client.release_notes`.
+    #
+    # Release note: `"id"`, `"product"`, `"version"`, `"title"`, `"description_html"`,
+    # `"audience"`, `"is_published"`, `"require_ack_internal"`, `"require_ack_external"`,
+    # `"published_at"`, `"created_at"`, `"updated_at"`.
+    class ReleaseNotes < Base
+      # Uma página de release notes. `GET /products/{slug}/release-notes`
+      # @param published [Boolean, nil] `true` só publicadas, `false` só rascunhos, `nil` todas.
+      # @return [Bfocus::Page]
+      def list(product_slug, published: nil, page: nil, page_size: nil, timeout: nil)
+        paged(base(product_slug), { "published" => published, "page" => page, "page_size" => page_size }, timeout)
+      end
+
+      # Todas as release notes do produto, página a página (`page_size` padrão 100).
+      # @return [Enumerator::Lazy<Hash>]
+      def list_all(product_slug, published: nil, page_size: 100, timeout: nil)
+        base(product_slug) # valida já, não na 1ª iteração
+        iterate do |number|
+          list(product_slug, published: published, page: number, page_size: page_size, timeout: timeout)
+        end
+      end
+
+      # Uma release note. `GET /products/{slug}/release-notes/{version}`
+      # @return [Hash]
+      def get(product_slug, version, timeout: nil)
+        call("GET", "#{base(product_slug)}/#{segment(version, 'version')}", timeout: timeout)
+      end
+
+      # Cria ou atualiza a release note de uma versão (SemVer; aceita `v` na frente).
+      # `PUT /products/{slug}/release-notes/{version}`. Com `publish: true` já publica — é o
+      # caminho para publicar direto do CI.
+      #
+      # @param audience [String] `"internal"`, `"external"` ou `"both"`.
+      # @param description_markdown [String] alternativa a `description_html` (a API converte).
+      # @return [Hash] a release note.
+      def upsert(product_slug, version, title: UNSET, description_html: UNSET,
+                 description_markdown: UNSET, audience: UNSET, require_ack_internal: UNSET,
+                 require_ack_external: UNSET, publish: UNSET, idempotency_key: nil, timeout: nil)
+        body = compact(
+          "title" => title,
+          "description_html" => description_html,
+          "description_markdown" => description_markdown,
+          "audience" => audience,
+          "require_ack_internal" => require_ack_internal,
+          "require_ack_external" => require_ack_external,
+          "publish" => publish
+        )
+        call("PUT", "#{base(product_slug)}/#{segment(version, 'version')}",
+             body: body, idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      # Publica uma release note. `POST /products/{slug}/release-notes/{version}/publish`
+      # @return [Hash] a release note.
+      def publish(product_slug, version, idempotency_key: nil, timeout: nil)
+        call("POST", "#{base(product_slug)}/#{segment(version, 'version')}/publish",
+             idempotency_key: idempotency_key, timeout: timeout)
+      end
+
+      private
+
+      def base(product_slug)
+        "/products/#{segment(product_slug, 'product_slug')}/release-notes"
+      end
+    end
+  end
+end

data/lib/bfocus/transport.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Bfocus
+  # URL de produção da API (padrão do {Client}). Em dev: `http://localhost:8000`.
+  DEFAULT_BASE_URL = "https://api.bfocus.com.br"
+  # Prefixo das rotas da API pública.
+  API_PREFIX = "/api/v1/integration"
+  # Vai em `X-Bfocus-Client` e `User-Agent`. É por ele que a API sabe qual versão da SDK a
+  # conta roda — e avisa quando uma correção exigir atualizar.
+  CLIENT_ID = "bfocus-ruby/#{VERSION}".freeze
+  # Segundos por tentativa.
+  DEFAULT_TIMEOUT = 30
+  # Novas tentativas além da primeira.
+  DEFAULT_MAX_RETRIES = 2
+
+  # Faz UMA chamada lógica: 1 tentativa + até `max_retries` novas tentativas, com os mesmos
+  # `X-Request-Id` e `Idempotency-Key`. Sem estado mutável entre chamadas (uma conexão por
+  # tentativa), então um {Client} pode ser compartilhado entre threads.
+  # @api private
+  class Transport
+    RETRY_STATUSES = [429, 502, 503, 504].freeze
+    WRITE_METHODS = %w[POST PUT PATCH DELETE].freeze
+    MAX_RETRY_AFTER = 60.0
+    MAX_BACKOFF = 8.0
+
+    # Métodos que "esperam" corpo: sem corpo, vão com `Content-Length: 0` (e sem Content-Type).
+    BODY_METHODS = %w[POST PUT PATCH].freeze
+
+    # Falhas de transporte que viram {NetworkError} (e são repetidas). `Net::OpenTimeout` e
+    # `Net::ReadTimeout` são `Timeout::Error`; `ECONNREFUSED`/`ECONNRESET` são `SystemCallError`.
+    NETWORK_ERRORS = [
+      SocketError, SystemCallError, IOError, Timeout::Error, OpenSSL::SSL::SSLError,
+      Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError, Net::ProtocolError
+    ].tap { |list| list << Zlib::Error if defined?(Zlib::Error) }.freeze
+
+    attr_reader :base_url, :timeout, :max_retries
+    # Espera entre tentativas (`#call(segundos)`). Substituível: os testes não dormem.
+    attr_accessor :sleeper
+
+    def initialize(api_key, base_url:, timeout:, max_retries:, sleeper: nil)
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, "")
+      begin
+        @uri = URI.parse(@base_url)
+      rescue URI::InvalidURIError
+        @uri = nil
+      end
+      unless @uri.is_a?(URI::HTTP) && @uri.hostname && !@uri.hostname.empty?
+        raise ArgumentError, "Bfocus::Client: base_url inválida #{base_url.inspect} (use http:// ou https://)."
+      end
+
+      @base_path = @uri.path.to_s
+      @timeout = timeout
+      @max_retries = max_retries
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+    end
+
+    # `Retry-After` em segundos (número ou data HTTP); `nil` se ausente/inválido.
+    # @return [Integer, Float, nil]
+    def self.parse_retry_after(raw)
+      return nil if raw.nil?
+
+      text = raw.to_s.strip
+      return nil if text.empty?
+
+      seconds =
+        if text.match?(/\A\d+(?:\.\d+)?\z/)
+          text.to_f
+        else
+          begin
+            Time.httpdate(text) - Time.now
+          rescue ArgumentError
+            return nil
+          end
+        end
+      return nil if seconds.nan? || seconds.infinite?
+
+      seconds = 0.0 if seconds.negative?
+      seconds == seconds.floor ? seconds.to_i : seconds
+    end
+
+    # `min(8, 0.5 × 2^tentativa)` s + jitter de até 25%.
+    def self.backoff(attempt)
+      base = [MAX_BACKOFF, 0.5 * (2**attempt)].min
+      base + (Random.rand * base * 0.25)
+    end
+
+    # Espera antes da próxima tentativa: `Retry-After` (teto 60 s) ou backoff exponencial.
+    def retry_delay(attempt, retry_after)
+      seconds = self.class.parse_retry_after(retry_after)
+      return [seconds.to_f, MAX_RETRY_AFTER].min unless seconds.nil?
+
+      self.class.backoff(attempt)
+    end
+
+    # Executa a chamada e devolve `[data, pagination]` do envelope.
+    #
+    # `body: nil` significa SEM corpo (o JSON `null` nunca é um corpo válido aqui).
+    # @raise [Bfocus::Error]
+    def request(method, path, query: nil, body: nil, idempotency_key: nil, timeout: nil)
+      method = method.to_s.upcase
+      per_try = timeout.nil? ? @timeout : timeout
+      unless per_try.is_a?(Numeric) && per_try.positive?
+        raise ArgumentError, "timeout precisa ser > 0 (segundos)."
+      end
+
+      target = @base_path + API_PREFIX + path + Codec.query_string(query)
+      request_id = SecureRandom.uuid.delete("-")
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "X-Bfocus-Client" => CLIENT_ID,
+        "User-Agent" => CLIENT_ID,
+        # Mesmo id em todas as tentativas desta chamada: é como o suporte correlaciona.
+        "X-Request-Id" => request_id
+      }
+      if WRITE_METHODS.include?(method)
+        # Mesma chave em todas as tentativas: a API devolve a resposta original
+        # (Idempotent-Replayed: true) em vez de executar de novo.
+        key = idempotency_key.to_s
+        headers["Idempotency-Key"] = key.empty? ? SecureRandom.uuid : key
+      end
+      payload = nil
+      unless body.nil?
+        payload = JSON.generate(Codec.jsonable(body))
+        headers["Content-Type"] = "application/json"
+      end
+
+      attempt = 0
+      while true # rubocop:disable Style/InfiniteLoop -- `loop` engoliria um StopIteration do sleeper
+        begin
+          status, resp_headers, raw = perform(method, target, headers, payload, per_try)
+        rescue *NETWORK_ERRORS => e
+          if attempt < @max_retries
+            @sleeper.call(self.class.backoff(attempt))
+            attempt += 1
+            next
+          end
+          raise NetworkError.new(
+            "NETWORK_ERROR: falha ao falar com #{@base_url} (#{e.class}: #{e.message})",
+            request_id: request_id
+          )
+        end
+
+        return unwrap(status, resp_headers, raw, request_id) if status.between?(200, 299)
+
+        if RETRY_STATUSES.include?(status) && attempt < @max_retries
+          @sleeper.call(retry_delay(attempt, resp_headers["retry-after"]))
+          attempt += 1
+          next
+        end
+        raise build_error(status, resp_headers, raw, request_id)
+      end
+    end
+
+    def inspect
+      "#<Bfocus::Transport base_url=#{@base_url.inspect}>"
+    end
+
+    private
+
+    def perform(method, target, headers, payload, timeout)
+      http = Net::HTTP.new(@uri.hostname, @uri.port)
+      http.use_ssl = @uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      # O Net::HTTP repete sozinho GET/PUT/DELETE uma vez em certas falhas; quem decide
+      # novas tentativas (e conta) é esta classe.
+      http.max_retries = 0
+      # Requisição genérica, e não Net::HTTP::Post/Put: sem corpo, aquelas viram `body = ""` +
+      # `Content-Type: application/x-www-form-urlencoded` por conta própria.
+      req = Net::HTTPGenericRequest.new(method, !payload.nil?, true, target, headers)
+      if payload.nil?
+        req["Content-Length"] = "0" if BODY_METHODS.include?(method)
+      else
+        req.body = payload
+      end
+      response = http.start { |conn| conn.request(req) }
+      resp_headers = {}
+      response.each_header { |name, value| resp_headers[name] = value }
+      [response.code.to_i, resp_headers, response.body.to_s]
+    end
+
+    # 2xx → `[data, pagination]`. Sem envelope JSON válido → `INVALID_RESPONSE`.
+    #
+    # Nunca devolve `nil` calado: um proxy que responde 200 com HTML (ou um corpo vazio) vira
+    # erro, não "sucesso sem dados".
+    def unwrap(status, headers, raw, sent_request_id)
+      payload, text = Codec.decode_json(raw)
+      if payload.is_a?(Hash) && payload.key?("data")
+        pagination = payload["pagination"]
+        return [payload["data"], pagination.is_a?(Hash) ? pagination : nil]
+      end
+
+      shown = text.strip[0, 200]
+      detail = shown.empty? ? " (corpo vazio)" : ": #{shown.inspect}"
+      raise Error.new(
+        "INVALID_RESPONSE (HTTP #{status}): resposta sem o envelope JSON da API#{detail}",
+        code: "INVALID_RESPONSE",
+        status: status,
+        request_id: present(headers["x-request-id"]) || sent_request_id,
+        body: payload.nil? ? present(text) : payload
+      )
+    end
+
+    # Resposta fora de 2xx → erro. `request_id`: corpo → header → o id que a SDK enviou.
+    def build_error(status, headers, raw, sent_request_id)
+      payload, text = Codec.decode_json(raw)
+      code = nil
+      human = nil
+      request_id = nil
+      validation = {}
+
+      if payload.is_a?(Hash)
+        err = payload["error"]
+        msg = payload["message"]
+        if err.is_a?(String) && !err.empty?
+          code = err
+        elsif msg.is_a?(String) && !msg.empty?
+          code = msg
+        end
+        human = msg if msg.is_a?(String) && !msg.empty? && msg != code
+        validation = payload["validation"] if payload["validation"].is_a?(Hash)
+        rid = payload["request_id"]
+        request_id = rid if rid.is_a?(String) && !rid.empty?
+      elsif !text.strip.empty?
+        human = text.strip[0, 200]
+      end
+
+      code ||= "HTTP_#{status}"
+      request_id ||= present(headers["x-request-id"]) || sent_request_id
+      retry_after = status == 429 ? self.class.parse_retry_after(headers["retry-after"]) : nil
+      required_scope = status == 403 ? present(headers["x-required-scope"]) : nil
+      required_module = status == 403 ? present(headers["x-required-module"]) : nil
+
+      message = "#{code} (HTTP #{status})"
+      message += ": #{human}" if human
+      message += " — escopo exigido: #{required_scope}" if required_scope
+      message += " — módulo exigido: #{required_module}" if required_module
+      message += " — #{validation.map { |field, why| "#{field}: #{why}" }.join('; ')}" unless validation.empty?
+      message += " — tente de novo em #{retry_after}s" unless retry_after.nil?
+
+      Error.class_for(status).new(
+        message,
+        code: code,
+        status: status,
+        request_id: request_id,
+        validation: validation,
+        retry_after: retry_after,
+        required_scope: required_scope,
+        body: payload.nil? ? present(text) : payload
+      )
+    end
+
+    def present(value)
+      text = value.to_s
+      text.empty? ? nil : text
+    end
+  end
+end

data/lib/bfocus/unset.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Bfocus
+  # Marca de argumento **não informado** — diferente de `nil`, que vai como `null` e LIMPA o
+  # campo na API. É o valor padrão dos keyword args opcionais de corpo; você nunca precisa
+  # usá-la. Existe uma única instância: {Bfocus::UNSET}.
+  class Unset
+    def inspect
+      "Bfocus::UNSET"
+    end
+    alias to_s inspect
+
+    # Continua sendo a mesma instância (comparação por identidade).
+    def dup
+      self
+    end
+
+    # Continua sendo a mesma instância (comparação por identidade).
+    def clone(freeze: true) # rubocop:disable Lint/UnusedMethodArgument
+      self
+    end
+  end
+
+  # Valor padrão dos keyword args opcionais de corpo: "não envie este campo".
+  UNSET = Unset.new.freeze
+  Unset.private_class_method :new
+end

data/lib/bfocus/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+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"
+end

data/lib/bfocus/widget.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Bfocus
+  # Assina a identidade do usuário logado para abrir o widget de atendimento do bFocus.
+  #
+  # Roda no **seu backend** (o segredo nunca vai para o navegador) e não exige chave de API
+  # nem faz rede. Devolve o HMAC-SHA256, em hexadecimal minúsculo, de
+  # `"v1:" + user_external_id + ":" + customer_external_id` (UTF-8).
+  #
+  # @param secret [String] segredo de identidade do widget (painel do bFocus).
+  # @param user_external_id [String] `external_id` do usuário no seu sistema.
+  # @param customer_external_id [String] `external_id` do cliente (empresa) desse usuário.
+  # @return [String] 64 caracteres hexadecimais minúsculos.
+  # @raise [ArgumentError] segredo vazio ou id `nil`.
+  #
+  # @example
+  #   Bfocus.sign_widget_identity(ENV.fetch("BFOCUS_WIDGET_SECRET"), "USR-1", "ERP 1042")
+  def self.sign_widget_identity(secret, user_external_id, customer_external_id)
+    raise ArgumentError, "sign_widget_identity: secret é obrigatório." if secret.nil? || secret.to_s.empty?
+    raise ArgumentError, "sign_widget_identity: user_external_id é obrigatório." if user_external_id.nil?
+    raise ArgumentError, "sign_widget_identity: customer_external_id é obrigatório." if customer_external_id.nil?
+
+    utf8 = lambda do |value|
+      text = value.to_s
+      (text.encoding == ::Encoding::BINARY ? text : text.encode(::Encoding::UTF_8)).b
+    end
+    message = "v1:".b + utf8.call(user_external_id) + ":".b + utf8.call(customer_external_id)
+    OpenSSL::HMAC.hexdigest("SHA256", utf8.call(secret), message)
+  end
+end

data/lib/bfocus.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# SDK oficial em Ruby da API pública do bFocus: clientes, produtos, release notes, base de
+# conhecimento e agentes de IA. Só biblioteca padrão (net/http, json, openssl, securerandom).
+#
+# @example
+#   require "bfocus"
+#
+#   client = Bfocus::Client.new(ENV.fetch("BFOCUS_API_KEY"))
+#   client.customers.upsert("ERP 1042", name: "Padaria Estrela")
+module Bfocus
+end
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "time"
+require "uri"
+
+require_relative "bfocus/version"
+require_relative "bfocus/unset"
+require_relative "bfocus/errors"
+require_relative "bfocus/page"
+require_relative "bfocus/codec"
+require_relative "bfocus/transport"
+require_relative "bfocus/resources/base"
+require_relative "bfocus/resources/customers"
+require_relative "bfocus/resources/products"
+require_relative "bfocus/resources/release_notes"
+require_relative "bfocus/resources/knowledge_base"
+require_relative "bfocus/resources/ai_agents"
+require_relative "bfocus/client"
+require_relative "bfocus/widget"

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: bfocus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Berni Software
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-19 00:00:00.000000000 Z
+dependencies: []
+description: Clientes, produtos, release notes, base de conhecimento e agentes de
+  IA do bFocus. Zero dependências de runtime, novas tentativas e idempotência automáticas.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/bfocus.rb
+- lib/bfocus/client.rb
+- lib/bfocus/codec.rb
+- lib/bfocus/errors.rb
+- lib/bfocus/page.rb
+- lib/bfocus/resources/ai_agents.rb
+- lib/bfocus/resources/base.rb
+- lib/bfocus/resources/customers.rb
+- lib/bfocus/resources/knowledge_base.rb
+- lib/bfocus/resources/products.rb
+- lib/bfocus/resources/release_notes.rb
+- lib/bfocus/transport.rb
+- lib/bfocus/unset.rb
+- lib/bfocus/version.rb
+- lib/bfocus/widget.rb
+homepage: https://bfocus.com.br
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://bfocus.com.br
+  source_code_uri: https://github.com/bernisoftware/bfocus-ruby
+  bug_tracker_uri: https://github.com/bernisoftware/bfocus-ruby/issues
+  documentation_uri: https://github.com/bernisoftware/bfocus-ruby#readme
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: SDK oficial da API pública do bFocus
+test_files: []