focus_nfe 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 52bbed5033ec09928bd4361f6b81913e0592bee928238021ccf74c555482b0fd
+  data.tar.gz: b26c1868a8e89f942556332397bbb581fa60915bfdd535ceb4a71efa8eabb89d
+SHA512:
+  metadata.gz: bdae6d394dd3525988db27e7ca9eeaec95227ee5002f37f151821ef1c602d944904f45a2f51ab23ef3488ca6d566e86ba3708c1b847a370f9b67b7060f73d32c
+  data.tar.gz: cec18edbbe79d1dcb201831e1f7e07ddc1619bf33d1ce1a2e47af0d14140f04665a669937b1d8e4dd0347c36a320afe99635d92418e0314ebac5e351356f346b

data/.git-hooks/pre_push/steep.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Overcommit
+  module Hook
+    module PrePush
+      # Roda `steep check` para garantir que as assinaturas RBS em `sig/`
+      # continuam consistentes com a implementação em `lib/`.
+      class Steep < Base
+        def run
+          result = execute(%w[bundle exec steep check])
+          return :pass if result.success?
+
+          [:fail, result.stdout + result.stderr]
+        end
+      end
+    end
+  end
+end

data/.git-hooks/pre_push/yard_doc.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Overcommit
+  module Hook
+    module PrePush
+      # Garante que a documentação YARD é gerada sem warnings
+      # (`--fail-on-warning`), espelhando o job `docs` do CI.
+      class YardDoc < Base
+        def run
+          result = execute(%w[bundle exec yard doc --no-output --fail-on-warning])
+          return :pass if result.success?
+
+          [:fail, result.stdout + result.stderr]
+        end
+      end
+    end
+  end
+end

data/.gitattributes

@@ -0,0 +1 @@
+data/schemas/*.json linguist-generated=true

data/.overcommit.yml

@@ -0,0 +1,69 @@
+gemfile: false
+
+CommitMsg:
+  ALL:
+    requires_files: false
+
+  MessageFormat:
+    enabled: true
+    pattern: '\A(?:Merge|Revert|fixup!|squash!).*|\A(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([\w\-./ ]+\))?!?: .+'
+    expected_pattern_message: >-
+      A mensagem de commit deve seguir o padrão Conventional Commits:
+      <tipo>(escopo opcional): <descrição>. Tipos válidos: build, chore, ci,
+      docs, feat, fix, perf, refactor, revert, style, test.
+    sample_message: "feat(nfe): adiciona emissão de NFe"
+
+  CapitalizedSubject:
+    enabled: false
+
+  TextWidth:
+    enabled: true
+    min_subject_width: 8
+    max_subject_width: 72
+
+  TrailingPeriod:
+    enabled: true
+
+  SingleLineSubject:
+    enabled: true
+
+  EmptyMessage:
+    enabled: true
+
+PreCommit:
+  RuboCop:
+    enabled: true
+    command: ["bundle", "exec", "rubocop"]
+    on_warn: fail
+
+  TrailingWhitespace:
+    enabled: true
+    exclude:
+      - "data/schemas/**/*"
+
+  HardTabs:
+    enabled: true
+
+  MergeConflicts:
+    enabled: true
+
+  YamlSyntax:
+    enabled: true
+
+  YardCoverage:
+    enabled: true
+    min_coverage_percentage: 93
+    flags: []
+
+PrePush:
+  RSpec:
+    enabled: true
+    command: ["bundle", "exec", "rspec"]
+
+  Steep:
+    enabled: true
+    required_executable: "bundle"
+
+  YardDoc:
+    enabled: true
+    required_executable: "bundle"

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--format progress
+--color

data/.yardopts

@@ -0,0 +1,11 @@
+--readme README.md
+--markup markdown
+--charset utf-8
+--output-dir docs
+--protected
+--no-private
+--title "Focus NFe - Cliente Ruby"
+lib/**/*.rb
+-
+CHANGELOG.md
+LICENSE.txt

data/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/)
+e versionamento em [SemVer](https://semver.org/lang/pt-BR/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-07-03
+
+Primeira versão pública. Cliente Ruby não-oficial para a API da
+[Focus NFe](https://focusnfe.com.br), sem dependências de runtime (apenas a
+stdlib).
+
+### Cliente e configuração
+
+- `FocusNfe::Client` com dois modos que coexistem: configuração global
+  (`FocusNfe.configure`) para aplicações de uma empresa só, e instâncias
+  independentes para cenários multi-empresa.
+- Dois tokens da Focus NFe separados: `Configuration#token_empresa`
+  (emissão/consulta de documentos e gestão por empresa) e
+  `Configuration#token_conta` (consultas auxiliares e gestão de empresas). O
+  cliente mantém uma conexão por token e roteia cada recurso para a correta;
+  acessar um recurso sem o token exigido levanta `ConfigurationError` antes de
+  qualquer ida à rede.
+- Ambientes `:homologacao` e `:producao`, resolvidos para a URL base correta.
+- `timeout`, `logger` e adaptador HTTP configuráveis; adaptador padrão sobre
+  `net/http`, sem gems externas.
+- Erros tipados por status HTTP (`FocusNfe::Errors::*`) a partir de
+  `FocusNfe::Error`, com o corpo da resposta preservado.
+
+### Documentos emitidos
+
+- Recursos `nfe`, `nfce`, `nfse`, `nfse_nacional`, `cte`, `cte_os`, `mdfe`,
+  `nfcom`, `dce` e `nfgas`.
+- Operações fiscais conforme cada documento: `emitir`, `consultar`, `cancelar`,
+  `inutilizar`, carta de correção e demais eventos, além de download dos XMLs
+  e do DANFE/DACTE quando disponível.
+- Eventos próprios do MDF-e: `Mdfe#encerrar`, `Mdfe#incluir_condutor` e
+  `Mdfe#incluir_dfe`, devolvendo `Modelos::Documento`.
+- Respostas devolvidas como `Modelos::Documento` (e `Modelos::Inutilizacao`
+  para inutilizações).
+
+### Documentos recebidos
+
+- Recursos `nfes_recebidas`, `ctes_recebidas` e `nfses_nacionais_recebidas`.
+- Listagem com sincronização incremental paginada (`Modelos::Pagina`),
+  consulta, manifestação do destinatário, eventos e download dos XMLs
+  (documento e eventos).
+
+### APIs auxiliares (token da conta)
+
+- Consultas somente leitura `ceps`, `municipios`, `cfops`, `cnaes`, `ncms` e
+  `cnpjs`.
+
+### APIs de gestão
+
+- `empresas` (token da conta) para cadastro e manutenção de empresas.
+- `webhooks`, `emails_bloqueados` e `backups` (token da empresa).
+
+### Webhooks inbound
+
+- `FocusNfe::Webhook.parse(raw_body)` devolve um `Modelos::Documento`.
+- `FocusNfe::Webhook.autenticado?(headers:, authorization:, authorization_header:)`
+  valida a chamada comparando o header recebido com o `authorization` do
+  gatilho em tempo constante. Inclui `Modelos::Documento.from_payload` e o erro
+  `Errors::WebhookError`.
+
+### Validação client-side (opt-in)
+
+- Esquemas de campos (`FocusNfe::Esquemas::*`) derivados de
+  `campos.focusnfe.com.br` e empacotados em `data/schemas/`, com validação
+  opcional na emissão (`emitir(..., validar: true)`).
+
+### Qualidade
+
+- Assinaturas de tipo RBS (`sig/`) verificadas por Steep e documentação YARD em
+  português nas APIs públicas.

data/CLAUDE.md

@@ -0,0 +1,118 @@
+# CLAUDE.md
+
+Guidance for Claude Code when working in this repository.
+
+## What this is
+
+Unofficial Ruby gem: a client for the [Focus NFe](https://focusnfe.com.br) API (Brazilian electronic
+fiscal documents — NFe, NFCe, NFSe, CTe, MDFe, NFCom, DCe, …). Early stage: most of the gem is still
+to be built; the substantive existing code is the field-scraping tooling (*Field schemas* below).
+
+## Coding conventions
+
+### Identifier language (hybrid: English plumbing, Portuguese domain)
+
+Dividing question: **does the identifier name something in the Focus NFe / SEFAZ fiscal domain?**
+Yes → **Portuguese**. The gem's own machinery → **English**.
+
+- **English (gem plumbing, not in the API):** classes/modules (`Client`, `Configuration`, `Connection`,
+  `Response`, `Adapter`, `Authentication`, `Error`, `Errors::*`); structural methods (`configure`,
+  `connection`, `call`, `get`/`post`/`put`/`delete`, `validate!`, `success?`, `from_response`,
+  `class_for`); infra config & HTTP terms (`environment`, `timeout`, `logger`, `http_adapter`, `headers`,
+  `path`, `params`, `body`, `status`, `url`); all internal vars, private methods, constants.
+- **Portuguese (the API's own vocabulary):** resource accessors / fiscal operations mapping 1:1 to API
+  actions (`nfe`, `nfce`, `nfse`, `cte`, `mdfe`, `emitir`, `consultar`, `cancelar`, `inutilizar`,
+  `justificativa`, `referencia`); **payload field names verbatim from the schemas — never translated**
+  (`natureza_operacao`, `cnpj_emitente`, `valor_total`, …).
+- **Domain values stay Portuguese even behind an English key:** `config.environment = :homologacao`
+  (`:producao`/`:homologacao`); fiscal statuses like `"autorizado"`/`"cancelado"`.
+- Debated boundaries: `environment` is English (resolves the base URL; `ambiente` is not an API field);
+  `referencia` is Portuguese (the API's `ref`).
+
+General Ruby/gem best practices: `frozen_string_literal`, double-quoted strings, Ruby 3.3 target (`.rubocop.yml`).
+
+### Comments
+
+- **No unnecessary comments** — names carry intent; no narration, restatement, or banner/section comments.
+- **Only YARD docs allowed**, on public classes/modules/methods, with type tags (`@param`, `@return`,
+  `@raise`). **Prose in Portuguese**; type references use the real English identifier (`@return [FocusNfe::Configuration]`).
+- A genuinely non-obvious *why* (workaround, external constraint) goes in the method's YARD doc, not inline.
+
+## TDD (mandatory — hard rule)
+
+Red → Green → Refactor for every behavior. **No production code without a failing spec first** (new
+classes, methods, branches arrive test-first; each bug fix starts with a reproducing spec).
+
+- **RSpec** under `spec/`, mirroring `lib/` (`spec/focus_nfe/recursos/nfe_spec.rb`, …).
+- HTTP never hit for real — stub with **WebMock** (VCR for recorded interactions if useful). Cover both
+  `:homologacao` and `:producao` base URLs.
+- `bundle exec rake` (RSpec + RuboCop) must stay green before any commit.
+
+## Commands
+
+- `bin/setup` — install deps; then `bundle exec overcommit --install` (git hooks, see below).
+- `bin/console` — IRB with the gem loaded.
+- `bin/rspec` / `bin/rubocop` — binstubs (faster than `bundle exec`). `bin/rubocop -a` auto-corrects.
+- `bundle exec rake` — default; runs **RSpec + RuboCop**. Keep green before committing.
+- `bundle exec rake ci` — roda **localmente todas as verificações do CI** (`.github/workflows/ci.yml`):
+  specs, RuboCop, Steep, YARD (`--fail-on-warning`), cobertura de docs e schemas atualizados. Continua
+  mesmo se um passo falhar e imprime um resumo no fim — pegue o CI quebrado antes de enviar ao GitHub.
+- `bundle exec rake steep` — **Steep** type-check (`sig/` vs `lib/`). Standalone, *not* in default rake;
+  CI gates it in a `typecheck` job. See *Type signatures*.
+- `bundle exec rake pull_fields` — regenerate field schemas into `data/schemas/`.
+- `bundle exec rake coverage:open` — open SimpleCov HTML report (generate first via `bin/rspec`/`rake spec`;
+  configured atop `spec/spec_helper.rb`, line+branch; `coverage/` git-ignored).
+- `bundle exec rake install` / `release` — build/publish (gemspec metadata still has TODOs).
+
+CI (`.github/workflows/ci.yml`) pins Ruby `4.0.2`; gemspec requires `>= 3.3.0`.
+
+## Git hooks / commits (overcommit + Conventional Commits)
+
+Managed by [overcommit](https://github.com/sds/overcommit) (`.overcommit.yml`); activate once with
+`bundle exec overcommit --install`. After editing `.overcommit.yml`, re-sign: `bundle exec overcommit --sign`.
+
+- **pre-commit** — `rubocop` on changed files + whitespace/tab/merge-conflict/YAML checks.
+- **pre-push** — full `rspec` suite.
+- **commit-msg** — [Conventional Commits](https://www.conventionalcommits.org): `<tipo>(escopo)!: <descrição>`.
+  Types: `build`, `chore`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `revert`, `style`, `test`.
+  Subject ≤ 72 cols, no trailing period (`Merge`/`Revert`/`fixup!`/`squash!` exempt).
+
+## Field schemas (source of truth for API fields)
+
+The request/field layer is derived from `campos.focusnfe.com.br`, not hand-transcribed.
+
+- `tools/pull_fields.rb` fetches each page, extracts the embedded `__NEXT_DATA__` JSON
+  (`props.pageProps.json.object_attributes`), and writes `data/schemas/schema_<name>.json` per document
+  type (URL map at the top of the script).
+- Each entry: `{ name, description, type, required, tag }`, optionally `enum`, `reforma_tributaria`, and a
+  nested `collection` (with `collection_type`). `name` = JSON field the API expects; `tag` = XML tag;
+  `type` encodes Brazilian fiscal type/length (`String[1-60]`, `Integer[1-9]`, `Decimal[13.2]`, `Coleção[0-500]`).
+- `data/schemas/` is git-tracked and packaged (gemspec `git ls-files`); powers opt-in client-side validation
+  (`FocusNfe::Esquemas::*`, `emitir(..., validar: true)`).
+
+**Never edit `data/schemas/*.json` by hand** — generated by `rake pull_fields`. To change a schema, edit the
+source / `tools/pull_fields.rb`, rerun, and commit the regenerated output. CI's `schemas` job regenerates on
+every PR and fails on any diff.
+
+## Type signatures (RBS + Steep)
+
+Hand-written RBS under `sig/`, checked by Steep — `steep check` must stay green (CI `typecheck` job, Ruby 3.4;
+local `bundle exec rake steep`, standalone to keep the 3.3–4.0 matrix fast). `Steepfile` has one `target :lib`
+checking `lib` against `sig` with stdlib `json`, `uri`, `net-http`, `timeout` (no `rbs_collection` — zero
+runtime deps). `sig/` is packaged with the gem; `Steepfile`/`rbs_collection.*` are excluded via the gemspec
+reject-list.
+
+- **`sig/` mirrors `lib/`, one file per `.rb`.** Keep in sync — a new class/method/branch arrives with its
+  signature. **Hand-written, never generated** (`rbs prototype` loses overloads, self-types, `define_method`'d methods).
+- **Typing boundary mirrors the naming rule:** gem plumbing is **precise** (`Response#status: Integer`,
+  `raw_body: String?`, `Configuration`/`Connection`/`Adapter` shapes, `Campo`'s parsed type/size); the
+  **fiscal payload/JSON domain is `untyped`** (`Response#body`, `Documento` fields & `#dados`, every
+  `**dados`/`**opcoes`/`**filtros`, raw-body returns of auxiliary/recebidas/management resources). When unsure
+  at a payload boundary, widen to `Hash[untyped, untyped]`/`untyped`.
+- **Mixins use RBS self-types:** each `Recursos::Concerns::*` is `module X : FocusNfe::Recursos::Base` so Steep
+  resolves the host's private `connection`/`caminho_*`/`esquemas_extras`.
+- **No `# steep:ignore`** (the comment rule allows only YARD). When Steep can't follow the code (e.g.
+  `define_method` doesn't rebind `self`), **restructure to explicit methods** instead of silencing — why
+  `HTTP::Connection`'s verbs and `Modelos::Documento`'s readers are written out. For stdlib nil-narrowing,
+  capture into a local and guard.
+- `Ruby::UnannotatedEmptyCollection` (empty `{}`) is disabled in `Steepfile`.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"focus_nfe" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["wilfisonbatista@gmail.com"](mailto:"wilfisonbatista@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 wilfison
+
+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.