cbf_calendario 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e9f80f797d23bf64dad179c1baf17f12c3bada78eb661eeda597bd121d0567ac
+  data.tar.gz: d5a7130a8c70bb594e014b0d82f557ab3f87e14025b9cafcec3b6db269844b0d
+SHA512:
+  metadata.gz: e161e22aaf7d4445367436f72dedc23a16b3fd4bc5adf0fdc53bf79ed818eca3481aa8f6c2a8780a201b5322b0b184ce22c84771d428ffbab0e85e029b7cbb80
+  data.tar.gz: 403ce1fcccb386a7507e2740df54dd7c008f8088005cba73cc92eb0015bc0177ad36b8f4ffd388ef0fe3b1845b468452c07f4adb0a024d5629c5a645ea8dcfd9

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## [0.3.0] - 2026-05-11
+
+- `Client#atletas_do_clube` e atalho `CbfCalendario.atletas_do_clube`
+- `Client#atleta_por_id` e atalho `CbfCalendario.atleta_por_id`
+- `Client#clube_por_id` e atalho `CbfCalendario.clube_por_id`
+- Novos erros de validação: `InvalidClubIdError` e `InvalidAthleteIdError`
+- README simplificado e atualizado com as novas funções e exemplos de retorno
+
+## [0.2.0] - 2026-05-10
+
+- `Client#partida_completa` / `Client#jogo_partida` — API `/api/cbf/jogos/:id` (mesmo escopo de dados que `show_game.rb`)
+- `CbfCalendario.estatisticas_agregadas(jogo)` e `CbfCalendario::PartidaStats`
+- `CbfCalendario::Urls` — paths e URLs da página da partida e dos times
+- `InvalidGameIdError`; cliente com `open_timeout`
+
+## [0.1.0] - 2026-05-10
+
+- Primeira publicação no RubyGems
+- `CbfCalendario::Client` com `jogos_pendentes_no_dia` e `calendario_json`
+- Atalhos no módulo `CbfCalendario`

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,605 @@
+# cbf_calendario
+
+Gem Ruby para consultar a API pública da CBF e retornar dados prontos para uso.
+
+## O que a gem faz
+
+- Lista jogos pendentes (sem placar) por dia.
+- Busca a partida completa por `id_jogo`.
+- Busca atletas por `id_clube`.
+- Busca atleta por `id_atleta`.
+- Busca clube por `id_clube`.
+- Gera estatísticas agregadas da súmula.
+- Monta URLs públicas da CBF (partida e times).
+- Retorna hashes Ruby para facilitar integração.
+
+## Instalação
+
+```ruby
+# Gemfile
+gem 'cbf_calendario', '~> 0.2'
+```
+
+```bash
+bundle install
+```
+
+Ou em script Ruby:
+
+```bash
+gem install cbf_calendario
+```
+
+```ruby
+require 'cbf_calendario'
+```
+
+## Uso rápido
+
+```ruby
+require 'cbf_calendario'
+
+jogos = CbfCalendario.jogos_pendentes_no_dia('10/05/2026')
+partida = CbfCalendario.partida_completa('832031')
+jogo = CbfCalendario.jogo_partida('832031')
+atletas = CbfCalendario.atletas_do_clube('20001')
+atleta = CbfCalendario.atleta_por_id('12345')
+clube = CbfCalendario.clube_por_id('20001')
+stats = CbfCalendario.estatisticas_agregadas(jogo)
+```
+
+## Funcionalidades principais
+
+### 1) Jogos pendentes por data
+
+Retorna apenas partidas ainda sem placar no dia informado.
+
+### 2) Partida completa por ID
+
+Consulta `GET /api/cbf/jogos/:id` e devolve o payload completo da API.
+
+### 3) Estatísticas da súmula
+
+Agrega eventos como gols, penalidades/cartões e substituições.
+
+### 4) URLs públicas da CBF
+
+Monta links da página da partida e das páginas de times.
+
+## Referência completa de funções públicas
+
+### Módulo `CbfCalendario` (atalhos)
+
+- `CbfCalendario.parse_data_br!(str)`
+- `CbfCalendario.jogos_pendentes_no_dia(data, **opts)`
+- `CbfCalendario.partida_completa(id_jogo, **opts)`
+- `CbfCalendario.jogo_partida(id_jogo, **opts)`
+- `CbfCalendario.atletas_do_clube(id_clube, **opts)`
+- `CbfCalendario.atleta_por_id(id_atleta, **opts)`
+- `CbfCalendario.clube_por_id(id_clube, **opts)`
+- `CbfCalendario.estatisticas_agregadas(jogo)`
+
+### Classe `CbfCalendario::Client`
+
+- `CbfCalendario::Client.new(base_url: ..., read_timeout: ..., open_timeout: ...)`
+- `client.jogos_pendentes_no_dia(data)`
+- `client.calendario_json(data)`
+- `client.partida_completa(id_jogo)`
+- `client.jogo_partida(id_jogo)`
+- `client.atletas_do_clube(id_clube)`
+- `client.atleta_por_id(id_atleta)`
+- `client.clube_por_id(id_clube)`
+- `CbfCalendario::Client.parse_data_br!(str)`
+- `CbfCalendario::Client.coerce_date!(data)`
+- `CbfCalendario::Client.normalize_id_jogo!(id_jogo)`
+- `CbfCalendario::Client.normalize_id_clube!(id_clube)`
+- `CbfCalendario::Client.normalize_id_atleta!(id_atleta)`
+
+### Módulo `CbfCalendario::PartidaStats`
+
+- `CbfCalendario::PartidaStats.agregadas(jogo)`
+
+### Módulo `CbfCalendario::Urls`
+
+- `CbfCalendario::Urls.slug_segment(str)`
+- `CbfCalendario::Urls.segmento_campeonato(nome)`
+- `CbfCalendario::Urls.segmento_categoria(nome_serie)`
+- `CbfCalendario::Urls.path_pagina_jogo(jogo)`
+- `CbfCalendario::Urls.url_time(campeonato_nome, categoria_nome, ano, clube_id, base: ...)`
+- `CbfCalendario::Urls.url_pagina_partida(jogo, base: ...)`
+
+### Constante
+
+- `CbfCalendario::VERSION`
+
+## Exemplos de respostas (retornos)
+
+### `CbfCalendario.parse_data_br!('25/12/2026')`
+
+```ruby
+# => #<Date: 2026-12-25 ...>
+```
+
+### `CbfCalendario.jogos_pendentes_no_dia('10/05/2026')`
+
+```ruby
+# => [
+#      {
+#        campeonato: "Campeonato Brasileiro",
+#        serie: "Série A",
+#        mandante: "Flamengo",
+#        visitante: "Bahia",
+#        placar_ou_horario: "16:00",
+#        data: "10/05/2026",
+#        data_iso: "2026-05-10",
+#        local: "Maracanã",
+#        rodada: "6",
+#        id_jogo: "832031"
+#      }
+#    ]
+```
+
+### `client.calendario_json(Date.today)`
+
+```ruby
+# => {
+#      "jogos" => {
+#        "Campeonato Brasileiro" => {
+#          "Série A" => [
+#            { "id_jogo" => 832031, "mandante" => {...}, "visitante" => {...}, ... }
+#          ]
+#        }
+#      }
+#    }
+```
+
+### `CbfCalendario.partida_completa('832031')`
+
+```ruby
+# => {
+#      "jogo" => {
+#        "id_jogo" => 832031,
+#        "mandante" => { "id" => 1, "nome" => "Flamengo", "gols" => 2, ... },
+#        "visitante" => { "id" => 2, "nome" => "Bahia", "gols" => 1, ... },
+#        "registros" => [ ... ],
+#        ...
+#      }
+#    }
+```
+
+### `CbfCalendario.jogo_partida('832031')`
+
+```ruby
+# => {
+#      "id_jogo" => 832031,
+#      "campeonato" => { "nome" => "Campeonato Brasileiro", "nome_categoria" => "Série A", "ano" => 2026 },
+#      "mandante" => { "id" => 1, "nome" => "Flamengo", ... },
+#      "visitante" => { "id" => 2, "nome" => "Bahia", ... },
+#      "registros" => [ ... ]
+#    }
+```
+
+### `CbfCalendario.atletas_do_clube('20001')`
+
+```ruby
+# => {
+#      clube_id: "20001",
+#      atletas: [
+#        {
+#          "id_atleta" => 12345,
+#          "nome_popular" => "Atleta Exemplo",
+#          "nome_completo" => "Atleta Exemplo da Silva",
+#          "posicao" => "MEI",
+#          ...
+#        }
+#      ]
+#    }
+```
+
+### `CbfCalendario.atleta_por_id('12345')`
+
+```ruby
+# => {
+#      atleta_id: "12345",
+#      atleta: {
+#        "id_atleta" => 12345,
+#        "nome_popular" => "Atleta Exemplo",
+#        "nome_completo" => "Atleta Exemplo da Silva",
+#        "posicao" => "ATA",
+#        ...
+#      }
+#    }
+```
+
+### `CbfCalendario.clube_por_id('20001')`
+
+```ruby
+# => {
+#      clube_id: "20001",
+#      clube: {
+#        "id_clube" => 20001,
+#        "nome" => "Time Exemplo",
+#        "sigla" => "TEX",
+#        "escudo" => "https://...",
+#        ...
+#      }
+#    }
+```
+
+### `CbfCalendario.estatisticas_agregadas(jogo)`
+
+```ruby
+# => {
+#      por_tipo_evento: { "GOL" => 3, "PENALIDADE" => 5 },
+#      gols_por_classificacao_sumula: { "NORMAL" => 2, "CONTRA" => 1 },
+#      gols_mandante_em_eventos: 2,
+#      gols_visitante_em_eventos: 1,
+#      cartoes_por_resultado: { "AMARELO" => 4, "VERMELHO" => 1 },
+#      total_substituicoes_mandante: 5,
+#      total_substituicoes_visitante: 4
+#    }
+```
+
+### `CbfCalendario::Urls.url_pagina_partida(jogo)`
+
+```ruby
+# => "https://www.cbf.com.br/futebol-brasileiro/jogos/campeonato-brasileiro/serie-a/2026/flamengo-x-bahia/832031"
+```
+
+### `CbfCalendario::Urls.url_time(...)`
+
+```ruby
+# => "https://www.cbf.com.br/futebol-brasileiro/times/campeonato-brasileiro/serie-a/2026/1"
+```
+
+## Tratamento de erros
+
+- `CbfCalendario::InvalidDateError`: data inválida (formato esperado: `dd/mm/aaaa`).
+- `CbfCalendario::InvalidGameIdError`: `id_jogo` inválido (somente dígitos).
+- `CbfCalendario::InvalidClubIdError`: `id_clube` inválido (somente dígitos).
+- `CbfCalendario::InvalidAthleteIdError`: `id_atleta` inválido (somente dígitos).
+- `CbfCalendario::HttpError`: erro HTTP ou payload inválido da API.
+- `CbfCalendario::Error`: classe base.
+
+## Uso em Rails (recomendado)
+
+Para produção, use em background com Active Job (ex.: Solid Queue), evitando bloquear requests web:
+
+```ruby
+class CbfCalendarioSyncJob < ApplicationJob
+  queue_as :default
+
+  def perform(data_iso: nil)
+    data = data_iso ? Date.iso8601(data_iso) : Date.current
+    CbfCalendario.jogos_pendentes_no_dia(data)
+  end
+end
+```
+
+## Requisitos
+
+- Ruby >= 3.0
+
+## Licença
+
+MIT. Veja `LICENSE.txt`.
+# cbf_calendario
+
+Cliente Ruby para a API pública da [CBF](https://www.cbf.com.br): **calendário** (jogos pendentes por dia), **partida** (`/api/cbf/jogos/:id`), **estatísticas derivadas** da súmula e **montagem de URLs** do site. Retornos em **hashes** Ruby para uso em **Rails** ou scripts.
+
+## Instalação
+
+```ruby
+# Gemfile
+gem 'cbf_calendario', '~> 0.2'
+```
+
+```bash
+bundle install
+```
+
+Em qualquer script Ruby (sem Bundler no load path):
+
+```bash
+gem install cbf_calendario
+```
+
+```ruby
+require 'cbf_calendario'
+```
+
+---
+
+## Uso direto (mesmo processo da requisição)
+
+Ideal só para testes ou endpoints muito leves. Para produção, prefira **enfileirar um job** (seção seguinte).
+
+```ruby
+require 'cbf_calendario'
+
+# Data como String dd/mm/aaaa, Date ou Time
+jogos = CbfCalendario.jogos_pendentes_no_dia('10/05/2026')
+# => [{ campeonato: "...", serie: "...", mandante: "...", ... }, ...]
+
+jogos = CbfCalendario.jogos_pendentes_no_dia(Date.current)
+
+# Cliente com opções (timeout HTTP, etc.)
+client = CbfCalendario::Client.new(read_timeout: 45)
+client.jogos_pendentes_no_dia('01/06/2026')
+
+# Payload bruto da API (Hash) para o dia
+client.calendario_json(Date.today)
+
+# Parsing de data brasileira
+CbfCalendario.parse_data_br!('25/12/2026') # => Date
+```
+
+### Partida (resultado / súmula completa da API)
+
+Mesmo endpoint usado em `show_game.rb`: **`GET /api/cbf/jogos/:id`**. O retorno é o **JSON completo** como `Hash` em Ruby (chaves **string**, igual ao JSON da CBF).
+
+```ruby
+# Payload inteiro: tipicamente { "jogo" => { ... registros, atletas, árbitros, ... } }
+payload = CbfCalendario.partida_completa('832031')
+
+jogo = payload['jogo']
+puts jogo.dig('mandante', 'nome')
+puts jogo.dig('mandante', 'gols')
+puts jogo.dig('visitante', 'gols')
+
+# Só o objeto jogo (atalho)
+jogo = CbfCalendario.jogo_partida(832031)
+
+# Estatísticas derivadas dos registros (gols por tipo, cartões, substituições…)
+stats = CbfCalendario.estatisticas_agregadas(jogo)
+# => { por_tipo_evento: {...}, gols_mandante_em_eventos: N, ... }
+
+# URLs públicas (mandante/visitante/página da partida), mesma regra do show_game
+cp = jogo['campeonato']
+ano = (cp['ano'] || jogo['ano']).to_s
+pagina = CbfCalendario::Urls.url_pagina_partida(jogo)
+mandante_url = CbfCalendario::Urls.url_time(cp['nome'], cp['nome_categoria'], ano, jogo.dig('mandante', 'id'))
+```
+
+Timeouts maiores (como no script original):
+
+```ruby
+CbfCalendario.partida_completa('832031', read_timeout: 45, open_timeout: 15)
+```
+
+Erros extras: `CbfCalendario::InvalidGameIdError` (ID inválido), `CbfCalendario::HttpError` (HTTP ou resposta sem `jogo`).
+
+---
+
+## Referência das funções públicas
+
+### Módulo `CbfCalendario` (atalhos)
+
+| Função | Descrição |
+|--------|-----------|
+| `parse_data_br!(str)` | Converte `"dd/mm/aaaa"` em `Date`. Lança `InvalidDateError`. |
+| `jogos_pendentes_no_dia(data, **opts)` | Jogos do dia **ainda sem placar** na API. `data`: `String` BR, `Date` ou `Time`. Retorna `Array<Hash>` com **chaves símbolo**. `**opts` repassa para `Client.new`. |
+| `partida_completa(id_jogo, **opts)` | `GET /api/cbf/jogos/:id` — payload JSON completo. Retorna `Hash` com **chaves string** (como o JSON). |
+| `jogo_partida(id_jogo, **opts)` | Mesmo endpoint; retorna só `payload["jogo"]` (`Hash` ou levanta erro se ausente). |
+| `estatisticas_agregadas(jogo)` | Agrega eventos da súmula (`registros`, substituições, etc.). Espera o **Hash `jogo`** vindo da API. Retorna `Hash` com **chaves símbolo**. |
+
+### Classe `CbfCalendario::Client`
+
+Construtor: `Client.new(base_url: "https://www.cbf.com.br", read_timeout: 30, open_timeout: 15)`.
+
+| Método | Descrição |
+|--------|-----------|
+| `jogos_pendentes_no_dia(data)` | Igual ao atalho do módulo. |
+| `calendario_json(data)` | Payload bruto do calendário: `GET /api/cbf/calendario/jogos/AAAA/MM/DD` (`Hash`, chaves string). |
+| `partida_completa(id_jogo)` | Payload bruto da partida (`GET /api/cbf/jogos/:id`). |
+| `jogo_partida(id_jogo)` | Somente o objeto `jogo`. |
+| `Client.parse_data_br!(str)` | Igual `CbfCalendario.parse_data_br!`. |
+| `Client.coerce_date!(data)` | Normaliza `Date` / `Time` / string `dd/mm/aaaa`. |
+| `Client.normalize_id_jogo!(id)` | Valida ID numérico (`String` de dígitos) ou levanta `InvalidGameIdError`. |
+
+### `CbfCalendario::PartidaStats`
+
+| Método | Descrição |
+|--------|-----------|
+| `agregadas(jogo)` | Implementação central das agregações; mesmo resultado que `CbfCalendario.estatisticas_agregadas(jogo)`. |
+
+Chaves típicas no **retorno** de `estatisticas_agregadas` / `PartidaStats.agregadas`:
+
+| Chave (símbolo) | Conteúdo |
+|-----------------|----------|
+| `:por_tipo_evento` | Contagem por `tipo` em `registros` (ex.: `GOL`, `PENALIDADE`). |
+| `:gols_por_classificacao_sumula` | Contagem por campo `resultado` nos eventos de gol. |
+| `:gols_mandante_em_eventos` | Gols do mandante contados nos registros `GOL`. |
+| `:gols_visitante_em_eventos` | Idem visitante. |
+| `:cartoes_por_resultado` | Contagem por `resultado` em eventos `PENALIDADE`. |
+| `:total_substituicoes_mandante` | Quantidade de substituições no mandante. |
+| `:total_substituicoes_visitante` | Idem visitante. |
+
+### `CbfCalendario::Urls` (links do site, sem HTTP)
+
+Constante: `CbfCalendario::Urls::SITE_ROOT` (`"https://www.cbf.com.br"`).
+
+| Método | Descrição |
+|--------|-----------|
+| `slug_segment(str)` | Slug à URL (remove acentos, minúsculas, hífens). |
+| `segmento_campeonato(nome)` | Segmento do campeonato na URL (ex.: `campeonato-brasileiro`). |
+| `segmento_categoria(nome_serie)` | Segmento da categoria/série (`serie-a`, `sub-20`, etc.). |
+| `path_pagina_jogo(jogo)` | Path relativo da página da partida no site. |
+| `url_pagina_partida(jogo, base: SITE_ROOT)` | URL absoluta da partida. |
+| `url_time(campeonato_nome, categoria_nome, ano, clube_id, base: SITE_ROOT)` | URL da página do clube na temporada. |
+
+O objeto `jogo`/`payload` usado em `Urls` deve ser o **Hash da API** (como em `jogo_partida`), com `campeonato`, `mandante`, `visitante`, `id_jogo`, etc.
+
+---
+
+## Rails: Solid Queue e jobs em background (recomendado)
+
+A API da CBF é chamada via rede; **não bloqueie** requisições HTTP longas no processo web (ex.: Puma). Use **[Solid Queue](https://github.com/rails/solid_queue)** (Rails 8+):
+
+1. Inclua `cbf_calendario` no `Gemfile`.
+2. Configure o adapter **`solid_queue`** para o Active Job.
+3. Implemente um **Active Job** que chama `CbfCalendario`.
+4. Rode o worker **`bin/jobs`** (processo separado do servidor web).
+
+### 1. Adapter Solid Queue
+
+No `Gemfile`, garanta a gem (no Rails 8 costuma vir por padrão; confira o guia do seu app):
+
+```ruby
+gem 'cbf_calendario'
+gem 'solid_queue'
+```
+
+`config/application.rb` (ou ambiente de produção):
+
+```ruby
+config.active_job.queue_adapter = :solid_queue
+```
+
+Em desenvolvimento e produção, mantenha `config.active_job.queue_adapter = :solid_queue` e rode `bin/jobs` quando precisar processar filas fora do ciclo de request.
+
+### 2. Job com Active Job
+
+`app/jobs/cbf_calendario_sync_job.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+class CbfCalendarioSyncJob < ApplicationJob
+  queue_as :default
+
+  # data_iso: "2026-05-10" ou nil para usar Date.current
+  def perform(data_iso: nil)
+    data =
+      if data_iso.present?
+        Date.iso8601(data_iso.to_s)
+      else
+        Date.current
+      end
+
+    jogos = CbfCalendario.jogos_pendentes_no_dia(data)
+
+    # Exemplo: persistir, notificar, cachear — adapte ao seu domínio
+    Rails.logger.info("[CBF] #{jogos.size} jogos pendentes em #{data}")
+
+    jogos.each do |jogo|
+      ExternalFixtureUpsertService.call(jogo) # seu serviço
+    end
+
+    jogos
+  rescue CbfCalendario::HttpError => e
+    Rails.logger.error("[CBF] HTTP: #{e.message}")
+    raise # deixa o Active Job aplicar retry conforme configuração
+  rescue CbfCalendario::InvalidDateError => e
+    Rails.logger.warn("[CBF] data inválida: #{e.message}")
+    raise
+  end
+end
+```
+
+Enfileirar (controller, outro job, scheduler):
+
+```ruby
+# data específica
+CbfCalendarioSyncJob.perform_later(data_iso: '2026-05-10')
+
+# “hoje” no servidor
+CbfCalendarioSyncJob.perform_later
+
+# com delay
+CbfCalendarioSyncJob.set(wait: 5.minutes).perform_later(data_iso: Date.tomorrow.iso8601)
+```
+
+### 3. Processar a fila (`bin/jobs`)
+
+Com Solid Queue, o worker padrão processa os jobs enfileirados:
+
+```bash
+bin/jobs
+```
+
+Rode em **processo separado** do `rails server` / Puma. Em produção, trate `bin/jobs` como serviço (systemd, container, Plataforma como serviço, etc.).
+
+### 4. Agendamento periódico (Solid Queue)
+
+Use o **recurring** do Solid Queue (ex.: `config/recurring.yml` no seu app) para enfileirar `CbfCalendarioSyncJob.perform_later` no horário desejado. A sintaxe e os arquivos exatos dependem da versão do Solid Queue — veja a [documentação do Solid Queue](https://github.com/rails/solid_queue) (seção *Recurring / cron*).
+
+### 5. Serviço systemd (exemplo): `bin/jobs` no ar
+
+Ajuste usuário, path e caminho do Ruby:
+
+```ini
+[Unit]
+Description=Solid Queue — processador de jobs (Rails + cbf_calendario)
+After=network.target
+
+[Service]
+Type=simple
+User=deploy
+WorkingDirectory=/var/www/seu_app/current
+Environment=RAILS_ENV=production
+ExecStart=/home/deploy/.rbenv/shims/bundle exec bin/jobs
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now solid-queue-jobs.service
+```
+
+(O nome do arquivo `.service` pode ser o que preferir; o importante é executar `bundle exec bin/jobs`.)
+
+---
+
+## API dos hashes retornados (calendário / pendentes)
+
+A tabela abaixo vale para **cada item** de `jogos_pendentes_no_dia` (chaves **símbolo**). O objeto **`jogo`** de `partida_completa` / `jogo_partida` segue o JSON da CBF (chaves **string**: `"mandante"`, `"registros"`, `"arbitros"`, etc.) — veja a referência completa acima.
+
+| Chave | Significado |
+|-------|-------------|
+| `:campeonato` | Nome do campeonato |
+| `:serie` | Série / divisão |
+| `:mandante` | Time mandante |
+| `:visitante` | Time visitante |
+| `:placar_ou_horario` | Horário previsto ou placar, se houver |
+| `:data` | Data como string na API |
+| `:data_iso` | Data no formato `YYYY-MM-DD` |
+| `:local` | Local do jogo |
+| `:rodada` | Rodada |
+| `:id_jogo` | Identificador do jogo na CBF |
+
+### Erros
+
+| Classe | Quando |
+|--------|--------|
+| `CbfCalendario::InvalidDateError` | Data em formato inválido |
+| `CbfCalendario::InvalidGameIdError` | ID de jogo não numérico |
+| `CbfCalendario::HttpError` | Falha HTTP ao chamar a API |
+| `CbfCalendario::Error` | Classe base |
+
+Em jobs, costuma-se **relançar** `HttpError` para retry exponencial; datas inválidas podem ser descartadas sem retry.
+
+### Rails: responder JSON a partir dos hashes
+
+```ruby
+def index
+  jogos = CbfCalendario.jogos_pendentes_no_dia(params.require(:data))
+  render json: jogos.map(&:stringify_keys)
+end
+```
+
+Para não bloquear o request em produção, prefira só enfileirar o job e devolver `202 Accepted`, ou ler resultado de cache/banco preenchido pelo job.
+
+---
+
+## Requisitos
+
+- Ruby >= 3.0
+
+## Licença
+
+MIT — veja [LICENSE.txt](LICENSE.txt).

data/cbf_calendario.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'lib/cbf_calendario/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'cbf_calendario'
+  spec.version       = CbfCalendario::VERSION
+  spec.authors       = ['Betbrothers']
+  spec.summary       = 'Cliente Ruby para o calendário de jogos da CBF (hashes, uso em Rails)'
+  spec.description   = <<~DESC
+    Consulta a API pública de calendário da CBF e devolve jogos pendentes (sem placar)
+    para uma data, como Array de hashes Ruby — adequado para uso em Ruby on Rails.
+  DESC
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.0'
+
+  spec.homepage = 'https://github.com/betbrothers/cbf_calendario'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['documentation_uri'] = 'https://rubydoc.info/gems/cbf_calendario'
+
+  spec.files = Dir.chdir(__dir__) do
+    %w[LICENSE.txt README.md CHANGELOG.md cbf_calendario.gemspec] + Dir['lib/**/*.rb']
+  end
+  spec.require_paths = ['lib']
+end

data/lib/cbf_calendario/client.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'json'
+require 'net/http'
+require 'openssl'
+require 'open-uri'
+require 'set'
+require 'uri'
+
+module CbfCalendario
+  class Error < StandardError; end
+  class HttpError < Error; end
+  class InvalidDateError < Error; end
+  class InvalidGameIdError < Error; end
+  class InvalidClubIdError < Error; end
+  class InvalidAthleteIdError < Error; end
+
+  class Client
+    DEFAULT_BASE = 'https://www.cbf.com.br'
+
+    attr_reader :base_url, :read_timeout, :open_timeout
+
+    def initialize(base_url: DEFAULT_BASE, read_timeout: 30, open_timeout: 15)
+      @base_url = base_url.to_s.chomp('/')
+      @read_timeout = read_timeout
+      @open_timeout = open_timeout
+    end
+
+    # GET /api/cbf/jogos/:id — resposta completa da API (mesmo conteúdo que +show_game.rb+ grava em JSON).
+    # Chaves são +String+ como no JSON original.
+    def partida_completa(id_jogo)
+      jid = Client.normalize_id_jogo!(id_jogo)
+      payload = get_json(api_path_jogo(jid))
+      raise HttpError, 'Resposta sem objeto "jogo"' unless payload['jogo'].is_a?(Hash)
+
+      payload
+    end
+
+    # Apenas +payload['jogo']+ (Hash com string keys).
+    def jogo_partida(id_jogo)
+      partida_completa(id_jogo)['jogo']
+    end
+
+    # GET /api/cbf/atletas/:id_clube — retorna hash com dados dos atletas.
+    # Saída: { clube_id: "123", atletas: [ ... ] }
+    def atletas_do_clube(id_clube)
+      cid = Client.normalize_id_clube!(id_clube)
+      payload = get_json(api_path_atletas_clube(cid))
+      atletas =
+        if payload.is_a?(Array)
+          payload
+        elsif payload.is_a?(Hash) && payload['atletas'].is_a?(Array)
+          payload['atletas']
+        else
+          raise HttpError, 'Resposta sem lista de atletas'
+        end
+
+      { clube_id: cid, atletas: atletas }
+    end
+
+    # Busca dados completos de um clube por ID.
+    # Saída: { clube_id: "123", clube: { ... } }
+    def clube_por_id(id_clube)
+      cid = Client.normalize_id_clube!(id_clube)
+      payload = buscar_clube_payload(cid)
+      clube = extrair_clube_do_payload(payload, cid)
+      raise HttpError, 'Resposta sem dados do clube' unless clube.is_a?(Hash) && !clube.empty?
+
+      { clube_id: cid, clube: clube }
+    end
+
+    # Busca dados completos de um atleta por ID.
+    # Saída: { atleta_id: "123", atleta: { ... } }
+    def atleta_por_id(id_atleta)
+      aid = Client.normalize_id_atleta!(id_atleta)
+      payload = buscar_atleta_payload(aid)
+      atleta = extrair_atleta_do_payload(payload, aid)
+      raise HttpError, 'Resposta sem dados do atleta' unless atleta.is_a?(Hash) && !atleta.empty?
+
+      { atleta_id: aid, atleta: atleta }
+    end
+
+    def self.normalize_id_jogo!(id_jogo)
+      s = id_jogo.to_s.strip
+      raise InvalidGameIdError, 'id_jogo deve conter só dígitos (ex.: 832024)' unless s.match?(/\A\d+\z/)
+
+      s
+    end
+
+    def self.normalize_id_clube!(id_clube)
+      s = id_clube.to_s.strip
+      raise InvalidClubIdError, 'id_clube deve conter só dígitos (ex.: 20001)' unless s.match?(/\A\d+\z/)
+
+      s
+    end
+
+    def self.normalize_id_atleta!(id_atleta)
+      s = id_atleta.to_s.strip
+      raise InvalidAthleteIdError, 'id_atleta deve conter só dígitos (ex.: 12345)' unless s.match?(/\A\d+\z/)
+
+      s
+    end
+
+    # Aceita Date, Time ou String "dd/mm/aaaa".
+    # Retorna Array<Hash> com símbolos como chaves, ordenado e sem IDs duplicados.
+    # Cada hash: +campeonato+, +serie+, +mandante+, +visitante+, +placar_ou_horario+,
+    # +data+, +data_iso+, +local+, +rodada+, +id_jogo+.
+    def jogos_pendentes_no_dia(data)
+      date = Client.coerce_date!(data)
+      payload = get_json(api_path_calendario(date))
+      jogos = extrair_jogos_pendentes(payload, date)
+      dedup_and_sort(jogos)
+    end
+
+    # Payload bruto da API para o dia (Hash).
+    def calendario_json(data)
+      date = Client.coerce_date!(data)
+      get_json(api_path_calendario(date))
+    end
+
+    def self.coerce_date!(data)
+      case data
+      when Date then data
+      when Time then data.to_date
+      else
+        parse_data_br!(data)
+      end
+    end
+
+    def self.parse_data_br!(str)
+      m = str.to_s.strip.match(/\A(\d{2})\/(\d{2})\/(\d{4})\z/)
+      raise InvalidDateError, 'Use dd/mm/aaaa (ex.: 15/05/2026)' unless m
+
+      day = m[1].to_i
+      month = m[2].to_i
+      year = m[3].to_i
+      Date.new(year, month, day)
+    rescue ArgumentError
+      raise InvalidDateError, 'Data inválida'
+    end
+
+    private
+
+    def api_path_calendario(data)
+      format('/api/cbf/calendario/jogos/%04d/%02d/%02d', data.year, data.month, data.day)
+    end
+
+    def api_path_jogo(id_jogo)
+      "/api/cbf/jogos/#{id_jogo}"
+    end
+
+    def api_path_atletas_clube(id_clube)
+      "/api/cbf/atletas/#{id_clube}"
+    end
+
+    def api_path_atleta(id_atleta)
+      "/api/cbf/atleta/#{id_atleta}"
+    end
+
+    def api_path_atletas_detalhes(id_atleta)
+      "/api/cbf/atletas/detalhes/#{id_atleta}"
+    end
+
+    def api_path_clube(id_clube)
+      "/api/cbf/clubes/#{id_clube}"
+    end
+
+    def api_path_time(id_clube)
+      "/api/cbf/times/#{id_clube}"
+    end
+
+    def api_path_clube_detalhes(id_clube)
+      "/api/cbf/clubes/detalhes/#{id_clube}"
+    end
+
+    def get_json(path)
+      uri = URI.join(base_url, path)
+      request_json(uri)
+    end
+
+    def request_json(uri)
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        read_timeout: read_timeout,
+        open_timeout: open_timeout,
+        use_ssl: true,
+        verify_mode: OpenSSL::SSL::VERIFY_PEER,
+        cert_store: ssl_cert_store
+      ) do |http|
+        req = Net::HTTP::Get.new(uri)
+        req['Accept'] = 'application/json'
+        res = http.request(req)
+        unless res.is_a?(Net::HTTPSuccess)
+          raise HttpError, "HTTP #{res.code}: #{res.message}"
+        end
+
+        JSON.parse(res.body)
+      end
+    end
+
+    def ssl_cert_store
+      @ssl_cert_store ||= OpenSSL::X509::Store.new.tap do |store|
+        root_pkcs7 = URI('http://crt.sectigo.com/SectigoPublicServerAuthenticationRootR46.p7c').open.read
+        OpenSSL::PKCS7.new(root_pkcs7).certificates.uniq { |c| c.to_der }.each { |c| store.add_cert(c) }
+
+        intermediate_der = URI('http://crt.sectigo.com/SectigoPublicServerAuthenticationCAOVR36.crt').open.read
+        store.add_cert(OpenSSL::X509::Certificate.new(intermediate_der))
+      end
+    end
+
+    def placar_ou_horario(jogo)
+      gm = jogo.dig('mandante', 'gols')
+      gv = jogo.dig('visitante', 'gols')
+
+      return "#{gm} x #{gv}" unless gm.nil? || gv.nil?
+
+      jogo['hora'].to_s.strip
+    end
+
+    def jogo_sem_placar?(jogo)
+      gm = jogo.dig('mandante', 'gols')
+      gv = jogo.dig('visitante', 'gols')
+      gm.nil? || gv.nil?
+    end
+
+    def extrair_jogos_pendentes(payload, data_calendario)
+      raiz = payload['jogos'] || {}
+      linhas = []
+
+      raiz.each do |campeonato, por_serie|
+        next unless por_serie.is_a?(Hash)
+
+        por_serie.each do |serie, lista|
+          next unless lista.is_a?(Array)
+
+          lista.each do |jogo|
+            next unless jogo_sem_placar?(jogo)
+
+            linhas << {
+              campeonato: campeonato.to_s.strip,
+              serie: serie.to_s.strip,
+              mandante: jogo.dig('mandante', 'nome').to_s.strip,
+              visitante: jogo.dig('visitante', 'nome').to_s.strip,
+              placar_ou_horario: placar_ou_horario(jogo),
+              data: jogo['data'].to_s.strip,
+              data_iso: data_calendario.strftime('%Y-%m-%d'),
+              local: jogo['local'].to_s.strip,
+              rodada: jogo['rodada'].to_s.strip,
+              id_jogo: jogo['id_jogo'].to_s.strip
+            }
+          end
+        end
+      end
+
+      linhas
+    end
+
+    def dedup_and_sort(linhas)
+      seen = Set.new
+      out = []
+      linhas.each do |row|
+        id = row[:id_jogo]
+        next if id.empty? || seen.include?(id)
+
+        seen.add(id)
+        out << row
+      end
+      out.sort_by { |j| [j[:campeonato], j[:serie], j[:rodada].to_i, j[:id_jogo]] }
+    end
+
+    def buscar_atleta_payload(id_atleta)
+      paths = [
+        api_path_atleta(id_atleta),
+        api_path_atletas_detalhes(id_atleta),
+        api_path_atletas_clube(id_atleta)
+      ]
+
+      errors = []
+      paths.each do |path|
+        begin
+          return get_json(path)
+        rescue HttpError => e
+          errors << "#{path}: #{e.message}"
+        end
+      end
+
+      raise HttpError, "Não foi possível buscar o atleta #{id_atleta}. Tentativas: #{errors.join(' | ')}"
+    end
+
+    def extrair_atleta_do_payload(payload, id_atleta)
+      if payload.is_a?(Hash)
+        return payload if campo_id_atleta(payload) == id_atleta
+        return payload['atleta'] if payload['atleta'].is_a?(Hash)
+        return payload
+      end
+
+      return {} unless payload.is_a?(Array)
+
+      payload.find { |item| item.is_a?(Hash) && campo_id_atleta(item) == id_atleta } ||
+        payload.find { |item| item.is_a?(Hash) } || {}
+    end
+
+    def campo_id_atleta(hash)
+      hash['id_atleta'].to_s.strip.empty? ? hash['id'].to_s.strip : hash['id_atleta'].to_s.strip
+    end
+
+    def buscar_clube_payload(id_clube)
+      paths = [
+        api_path_clube(id_clube),
+        api_path_time(id_clube),
+        api_path_clube_detalhes(id_clube)
+      ]
+
+      errors = []
+      paths.each do |path|
+        begin
+          return get_json(path)
+        rescue HttpError => e
+          errors << "#{path}: #{e.message}"
+        end
+      end
+
+      raise HttpError, "Não foi possível buscar o clube #{id_clube}. Tentativas: #{errors.join(' | ')}"
+    end
+
+    def extrair_clube_do_payload(payload, id_clube)
+      if payload.is_a?(Hash)
+        return payload if campo_id_clube(payload) == id_clube
+        return payload['clube'] if payload['clube'].is_a?(Hash)
+        return payload['time'] if payload['time'].is_a?(Hash)
+        return payload
+      end
+
+      return {} unless payload.is_a?(Array)
+
+      payload.find { |item| item.is_a?(Hash) && campo_id_clube(item) == id_clube } ||
+        payload.find { |item| item.is_a?(Hash) } || {}
+    end
+
+    def campo_id_clube(hash)
+      return hash['id_clube'].to_s.strip unless hash['id_clube'].to_s.strip.empty?
+      return hash['id_time'].to_s.strip unless hash['id_time'].to_s.strip.empty?
+
+      hash['id'].to_s.strip
+    end
+  end
+end

data/lib/cbf_calendario/partida_stats.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CbfCalendario
+  # Estatísticas derivadas dos registros da súmula (mesma lógica de +show_game.rb+).
+  module PartidaStats
+    module_function
+
+    # @param jogo [Hash] objeto +jogo+ retornado pela API (+payload['jogo']+)
+    # @return [Hash] chaves em símbolo
+    def agregadas(jogo)
+      regs = jogo['registros']
+      regs = [] unless regs.is_a?(Array)
+
+      por_tipo = regs.each_with_object(Hash.new(0)) { |r, h| h[r['tipo']] += 1 }
+
+      mid = jogo.dig('mandante', 'id').to_s
+      vid = jogo.dig('visitante', 'id').to_s
+
+      gols = regs.select { |r| r['tipo'] == 'GOL' }
+      gols_tipo = gols.each_with_object(Hash.new(0)) { |r, h| h[r['resultado'].to_s] += 1 }
+
+      gols_m = gols.count { |r| r['clube_id'].to_s == mid }
+      gols_v = gols.count { |r| r['clube_id'].to_s == vid }
+
+      pens = regs.select { |r| r['tipo'] == 'PENALIDADE' }
+      cartoes = pens.each_with_object(Hash.new(0)) { |r, h| h[r['resultado'].to_s] += 1 }
+
+      {
+        por_tipo_evento: por_tipo,
+        gols_por_classificacao_sumula: gols_tipo,
+        gols_mandante_em_eventos: gols_m,
+        gols_visitante_em_eventos: gols_v,
+        cartoes_por_resultado: cartoes,
+        total_substituicoes_mandante: (jogo.dig('mandante', 'alteracoes') || []).size,
+        total_substituicoes_visitante: (jogo.dig('visitante', 'alteracoes') || []).size
+      }
+    end
+  end
+end

data/lib/cbf_calendario/urls.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module CbfCalendario
+  # Montagem de paths e URLs públicas da CBF (mesma lógica de +show_game.rb+).
+  module Urls
+    SITE_ROOT = 'https://www.cbf.com.br'
+
+    module_function
+
+    def slug_segment(str)
+      t = str.to_s.unicode_normalize(:nfd).gsub(/\p{M}/u, '').downcase
+      t.gsub(/[^a-z0-9]+/, '-').gsub(/-+/, '-').delete_prefix('-').delete_suffix('-')
+    end
+
+    def segmento_campeonato(nome)
+      n = nome.to_s.strip
+      return 'campeonato-brasileiro' if n.match?(/\ACampeonato Brasileiro\z/i)
+      return 'copa-do-brasil' if n.match?(/\ACopa do Brasil\z/i)
+      return 'brasileiro-feminino' if n.match?(/\ABrasileiro Feminino\z/i)
+
+      slug_segment(n)
+    end
+
+    def segmento_categoria(nome_serie)
+      s = nome_serie.to_s.strip
+
+      serie = s.match(/\ASérie\s+([ABCD])\z/i)
+      return "serie-#{serie[1].downcase}" if serie
+
+      sub = s.match(/\ASub\s*-\s*(\d+)\z/i)
+      return "sub-#{sub[1]}" if sub
+
+      ax = s.match(/\A(A[12])\z/i)
+      return ax[1].downcase if ax
+
+      slug_segment(s)
+    end
+
+    # Path relativo à raiz do site (ex.: +/futebol-brasileiro/jogos/...+).
+    def path_pagina_jogo(jogo)
+      camp = jogo.dig('campeonato', 'nome')
+      serie = jogo.dig('campeonato', 'nome_categoria')
+      ano = (jogo.dig('campeonato', 'ano') || jogo['ano']).to_s
+      sm = slug_segment(jogo.dig('mandante', 'nome'))
+      sv = slug_segment(jogo.dig('visitante', 'nome'))
+      id = jogo['id_jogo']
+
+      "/futebol-brasileiro/jogos/#{segmento_campeonato(camp)}/#{segmento_categoria(serie)}/#{ano}/#{sm}-x-#{sv}/#{id}"
+    end
+
+    def url_time(campeonato_nome, categoria_nome, ano, clube_id, base: SITE_ROOT)
+      base = base.to_s.chomp('/')
+      "#{base}/futebol-brasileiro/times/#{segmento_campeonato(campeonato_nome)}/#{segmento_categoria(categoria_nome)}/#{ano}/#{clube_id}"
+    end
+
+    def url_pagina_partida(jogo, base: SITE_ROOT)
+      "#{base.to_s.chomp('/')}#{path_pagina_jogo(jogo)}"
+    end
+  end
+end

data/lib/cbf_calendario/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CbfCalendario
+  VERSION = '0.3.0'
+end

data/lib/cbf_calendario.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative 'cbf_calendario/version'
+require_relative 'cbf_calendario/client'
+require_relative 'cbf_calendario/partida_stats'
+require_relative 'cbf_calendario/urls'
+
+module CbfCalendario
+  module_function
+
+  def parse_data_br!(str)
+    Client.parse_data_br!(str)
+  end
+
+  # Atalho sem instanciar +Client+.
+  def jogos_pendentes_no_dia(data, **client_options)
+    Client.new(**client_options).jogos_pendentes_no_dia(data)
+  end
+
+  # GET /api/cbf/jogos/:id — Hash completo da API (chaves string).
+  def partida_completa(id_jogo, **client_options)
+    Client.new(**client_options).partida_completa(id_jogo)
+  end
+
+  # Somente o objeto +jogo+ do payload.
+  def jogo_partida(id_jogo, **client_options)
+    Client.new(**client_options).jogo_partida(id_jogo)
+  end
+
+  # Hash com todos os atletas do clube.
+  def atletas_do_clube(id_clube, **client_options)
+    Client.new(**client_options).atletas_do_clube(id_clube)
+  end
+
+  # Hash com os dados de um atleta específico.
+  def atleta_por_id(id_atleta, **client_options)
+    Client.new(**client_options).atleta_por_id(id_atleta)
+  end
+
+  # Hash com os dados de um clube específico.
+  def clube_por_id(id_clube, **client_options)
+    Client.new(**client_options).clube_por_id(id_clube)
+  end
+
+  # Estatísticas derivadas dos registros (+show_game.rb+).
+  def estatisticas_agregadas(jogo)
+    PartidaStats.agregadas(jogo)
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: cbf_calendario
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Betbrothers
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Consulta a API pública de calendário da CBF e devolve jogos pendentes (sem placar)
+  para uma data, como Array de hashes Ruby — adequado para uso em Ruby on Rails.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- cbf_calendario.gemspec
+- lib/cbf_calendario.rb
+- lib/cbf_calendario/client.rb
+- lib/cbf_calendario/partida_stats.rb
+- lib/cbf_calendario/urls.rb
+- lib/cbf_calendario/version.rb
+homepage: https://github.com/betbrothers/cbf_calendario
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/betbrothers/cbf_calendario
+  changelog_uri: https://github.com/betbrothers/cbf_calendario/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/cbf_calendario
+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.6.9
+specification_version: 4
+summary: Cliente Ruby para o calendário de jogos da CBF (hashes, uso em Rails)
+test_files: []