logos-bancos-br 0.1.0 → 0.2.0

package/README.en.md

@@ -32,9 +32,11 @@
    Central Bank of Brazil STR participants list (currently 470), with official name, short name,
    COMPE code and ISPB, in [`data/bancos.json`](data/bancos.json). You never hand-maintain a
    bank list again.
-2. **Official logos.** Currently 107, as 256×256 PNGs (+ SVG when available), sourced from the
-   public **Open Finance Brasil** directory — where each institution publishes and maintains its
-   own brand. Every file carries provenance: source URI, SHA-256 and date.
+2. **Official logos.** Currently 152, as 256×256 PNGs (+ SVG when available), from two origins —
+   both official and identified in the dataset (`logo.source.type`): the public **Open Finance
+   Brasil** directory (`openfinance`), where each institution publishes its own brand, and the
+   **institution's own official website** (`direct-uri`), visually curated before shipping.
+   Every file carries provenance: source URI, SHA-256 and date.
 3. **Automatic updates, no manual curation.** Every Monday a GitHub Action
    ([`update-logos.yml`](.github/workflows/update-logos.yml)) rebuilds **both the list AND the
    logos** from the sources and opens a PR with the visual diff. A bank created, renamed or
@@ -50,7 +52,10 @@ and banks redesign their brands. Existing libraries ship either **data only** (n
 logos **hand-collected** from assorted websites with no traceability. The approach here:
 
 - **Official sources, and only them** — the STR participants CSV (updated daily by the Central
-  Bank itself) and the Open Finance Brasil participants directory. No images "found on Google".
+  Bank itself), the Open Finance Brasil participants directory and, for non-participants, the
+  icon the institution publishes **on its own official website** (hand-reviewed). No images
+  "found on Google" or from aggregators. Open Finance purists can filter:
+  `banks().filter(b => b.logo?.source.type === 'openfinance')`.
 - **Per-logo provenance** — `data/bancos.json` records each logo's source URI, SHA-256 of the
   original artwork and last-change date. The git diff is the audit trail.
 - **Safe matching** — automatic matches happen **only via ISPB** (= first 8 digits of the CNPJ).
@@ -58,9 +63,10 @@ logos **hand-collected** from assorted websites with no traceability. The approa
   In a banking context, a wrong logo is worse than no logo.
 - **Safe assets** — https-only downloads with size/pixel caps; SVGs redistributed only after
   sanitization (no scripts, event handlers, `foreignObject` or external references).
-- **Honest trade-off** — 107 of the 470 institutions have a logo (the Open Finance participants,
-  which cover the vast majority of accounts in Brazil). The rest are small credit unions/SCDs
-  with no officially published logo — your app picks the fallback.
+- **Honest trade-off** — 152 of the 470 institutions have a logo (all Open Finance participants
+  plus ~45 banks/payment institutions covered via official sites — the vast majority of accounts
+  in Brazil). The rest are small credit unions/SCDs/brokers — your app picks the fallback, and
+  coverage grows every release.
 
 ## Install & use
 
@@ -68,6 +74,10 @@ logos **hand-collected** from assorted websites with no traceability. The approa
 npm install logos-bancos-br
 ```
 
+Requires **Node ≥ 20** for Node/CLI usage (web and React Native follow your bundler's
+environment). Zero runtime dependencies. Published with **npm provenance** — verify integrity
+with `npm audit signatures`.
+
 Files are named by **ISPB** (8 digits). Lookups accept **COMPE or ISPB**.
 
 ```ts
@@ -78,7 +88,8 @@ byIspb('00000000');  // Banco do Brasil
 logoCdnUrl(341);     // https://cdn.jsdelivr.net/npm/logos-bancos-br@x.y.z/logos/png/60701190.png
 ```
 
-**React Native (Expo/Metro)** — static require() map (bundles all logos, ~1.3 MB):
+**React Native (Expo/Metro)** — static require() map (bundles all logos, ~1.3 MB; keys accept
+both the 4-digit COMPE and the 8-digit ISPB):
 
 ```tsx
 import logos from 'logos-bancos-br/react-native';
@@ -111,6 +122,23 @@ https://cdn.jsdelivr.net/npm/logos-bancos-br@0.1.0/logos/png/60701190.png
 import data from 'logos-bancos-br/data/bancos.json';
 ```
 
+### API quick reference
+
+| Import | Function | Returns |
+|---|---|---|
+| `logos-bancos-br` | `banks()` | every institution (`Bank[]`) |
+| | `byCompe(code)` | `Bank \| undefined` — `341`, `'341'` and `'0341'` are equivalent |
+| | `byIspb(ispb)` | `Bank \| undefined` |
+| | `findBank(code)` | `Bank \| undefined` — more than 4 digits is treated as ISPB |
+| | `logoCdnUrl(code, { format?, version? })` | jsDelivr URL, or `null` when there is no logo |
+| | `normalizeCompe(x)` · `normalizeIspb(x)` | `'0341'` · `'60701190'` |
+| | `version` | package version (string) |
+| `logos-bancos-br/node` | `logoPngPath(code)` · `logoSvgPath(code)` | absolute asset path, or `null` |
+| | `copyLogos({ dest, format?, by?, only? })` | copies assets into a directory (what the CLI uses) |
+| `logos-bancos-br/react-native` | `logos` (default export) | require() map keyed by COMPE4 **and** ISPB |
+
+Exported TypeScript types: `Bank`, `BankLogo`, `BankLogoSource`.
+
 ## Dataset shape
 
 ```json
@@ -135,10 +163,14 @@ redistributable; `logo: null` means the institution has no logo in the official
 
 The pipeline joins the STR list (which institutions exist) with the Open Finance directory
 (their logos), bridged by `ISPB == first 8 digits of the CNPJ`; hand-reviewed `forcedMatches`
-cover second brands (XP CCTVM, Nu Invest, Bradesco BBI…). The weekly workflow regenerates
+cover second brands (XP CCTVM, Nu Invest, Bradesco BBI…). For institutions outside Open Finance,
+discovery tools (`npm run discover` / `discover:ai`) find the icon published on the institution's
+official website — nothing ships without visual curation (brand + domain reviewed); approvals
+become `forcedUris` (`source.type: "direct-uri"`). The weekly workflow regenerates
 `data/bancos.json`, `logos/`, `PREVIEW.md` and `react-native.js` and opens a PR with the report
-and the visual PNG diff. After review and merge, a new version is published to npm. Nothing is
-edited by hand. Maintenance details: [CONTRIBUTING.md](CONTRIBUTING.md).
+and the visual PNG diff. After review and merge, the maintainer publishes a new version to npm
+(GitHub Release). Nothing is edited by hand. Maintenance details:
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Trademarks
 

package/README.md

@@ -31,8 +31,10 @@
    COMPE da lista de participantes do STR do **Banco Central** (hoje 470), com nome oficial,
    nome reduzido, código COMPE e ISPB, em [`data/bancos.json`](data/bancos.json). Você nunca
    mais mantém uma lista de bancos à mão.
-2. **Logos oficiais.** Hoje 107, em PNG 256×256 (+ SVG quando disponível), vindos do diretório
-   público do **Open Finance Brasil** — onde cada instituição publica e mantém a própria marca.
+2. **Logos oficiais.** Hoje 152, em PNG 256×256 (+ SVG quando disponível), de duas origens —
+   ambas oficiais e identificadas no dataset (`logo.source.type`): o diretório público do
+   **Open Finance Brasil** (`openfinance`), onde cada instituição publica a própria marca, e o
+   **site oficial da própria instituição** (`direct-uri`), com curadoria visual antes de entrar.
    Cada arquivo carrega proveniência: URI de origem, SHA-256 e data.
 3. **Atualização automática, sem curadoria manual.** Toda segunda-feira um GitHub Action
    ([`update-logos.yml`](.github/workflows/update-logos.yml)) reconstrói **a lista E os logos**
@@ -49,8 +51,10 @@ redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem l
 **coletados manualmente** de sites variados, sem rastreabilidade. A abordagem aqui:
 
 - **Fontes oficiais, e apenas elas** — o CSV de participantes do STR (que o próprio BCB atualiza
-  diariamente) e o diretório de participantes do Open Finance Brasil. Nenhuma imagem "achada no
-  Google".
+  diariamente), o diretório de participantes do Open Finance Brasil e, para quem não participa do
+  Open Finance, o ícone que a própria instituição publica **no site oficial dela** (revisado à
+  mão). Nenhuma imagem "achada no Google" ou de agregador. Quem quiser só a fonte Open Finance
+  filtra: `banks().filter(b => b.logo?.source.type === 'openfinance')`.
 - **Proveniência por logo** — `data/bancos.json` registra a URI de origem, o SHA-256 do arquivo
   original e a data de cada logo. O diff do git é a auditoria.
 - **Correspondência segura** — match automático **somente por ISPB** (= raiz do CNPJ).
@@ -59,9 +63,10 @@ redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem l
 - **Assets seguros** — download só via https com teto de tamanho e de pixels; SVGs
   redistribuídos apenas após sanitização (sem `script`, event handlers, `foreignObject` ou
   referências externas).
-- **Trade-off honesto** — 107 das 470 instituições têm logo (as participantes do Open Finance,
-  que cobrem a esmagadora maioria das contas do país). As demais são SCDs/cooperativas pequenas
-  sem logo oficial publicado; para elas seu app usa o fallback que preferir.
+- **Trade-off honesto** — 152 das 470 instituições têm logo (todas as participantes do Open
+  Finance + ~45 bancos e IPs cobertos pelos sites oficiais, o que inclui a esmagadora maioria
+  das contas do país). As demais são SCDs/cooperativas/corretoras pequenas; para elas seu app
+  usa o fallback que preferir — e a cobertura cresce a cada release.
 
 ## Instalação e uso
 
@@ -69,6 +74,10 @@ redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem l
 npm install logos-bancos-br
 ```
 
+Requer **Node ≥ 20** para uso via Node/CLI (em web e React Native vale o ambiente do seu
+bundler). Zero dependências de runtime. Publicado com **npm provenance** — verifique a
+integridade com `npm audit signatures`.
+
 Os arquivos são nomeados pelo **ISPB** (8 dígitos, estável e universal — inclusive para
 instituições Pix sem COMPE, no roadmap). As consultas aceitam **COMPE ou ISPB**.
 
@@ -100,6 +109,7 @@ import logos from 'logos-bancos-br/react-native'; // mapa require() estático
 <Image source={logos[codigoBanco.padStart(4, '0')]} style={{ width: 40, height: 40 }} />
 ```
 
+> As chaves do mapa aceitam o COMPE com 4 dígitos (`'0341'`) **e** o ISPB (`'60701190'`).
 > Importar esse entry adiciona **todos** os logos (~1,3 MB) ao bundle. Se preferir empacotar só
 > alguns, use o CLI abaixo e faça `require()` dos arquivos copiados.
 
@@ -141,6 +151,23 @@ import dados from 'logos-bancos-br/data/bancos.json';
 // todas as instituições: ispb, compe, compe4, nome oficial, nome reduzido, logo (ou null)
 ```
 
+### Referência rápida da API
+
+| Import | Função | Retorna |
+|---|---|---|
+| `logos-bancos-br` | `banks()` | todas as instituições (`Bank[]`) |
+| | `byCompe(codigo)` | `Bank \| undefined` — `341`, `'341'` e `'0341'` são equivalentes |
+| | `byIspb(ispb)` | `Bank \| undefined` |
+| | `findBank(codigo)` | `Bank \| undefined` — mais de 4 dígitos trata como ISPB |
+| | `logoCdnUrl(codigo, { format?, version? })` | URL do jsDelivr, ou `null` se não houver logo |
+| | `normalizeCompe(x)` · `normalizeIspb(x)` | `'0341'` · `'60701190'` |
+| | `version` | versão do pacote (string) |
+| `logos-bancos-br/node` | `logoPngPath(codigo)` · `logoSvgPath(codigo)` | caminho absoluto do asset, ou `null` |
+| | `copyLogos({ dest, format?, by?, only? })` | copia os assets para um diretório (o que o CLI usa) |
+| `logos-bancos-br/react-native` | `logos` (default export) | mapa `require()` com chaves COMPE4 **e** ISPB |
+
+Tipos TypeScript exportados: `Bank`, `BankLogo`, `BankLogoSource`.
+
 ## O dataset
 
 Um registro de `data/bancos.json`:
@@ -169,7 +196,9 @@ Um registro de `data/bancos.json`:
 
 - `logo.png` — PNG normalizado **256×256**, fundo transparente, `fit: contain`.
 - `logo.svg` — vetor original, presente só quando passa na sanitização.
-- `logo.source` — proveniência completa: de onde veio, hash e quando mudou.
+- `logo.source` — proveniência completa: de onde veio, hash e quando mudou. `source.type`:
+  `openfinance` (diretório Open Finance, match automático por ISPB ou revisado), `direct-uri`
+  (URL no site oficial da instituição, revisada à mão) ou `override` (arte mantida no repo).
 - `logo: null` — instituição sem logo nas fontes oficiais (use seu fallback).
 
 ## Como funciona a atualização automática
@@ -182,19 +211,23 @@ Um registro de `data/bancos.json`:
 3. **Ponte**: `ISPB == 8 primeiros dígitos do CNPJ` (é assim que o BCB os atribui na esmagadora
    maioria dos casos). Quando não bate — segundas marcas como XP CCTVM, Nu Invest, Bradesco BBI —
    entra o `forcedMatches`, revisado à mão a partir das sugestões do relatório.
-4. **Normalização**: cada arte vira PNG 256×256; o SVG original é mantido quando seguro.
-5. **Cadência**: o workflow roda **toda segunda-feira** (e sob demanda), regenera
+4. **Fora do Open Finance**: ferramentas de descoberta (`npm run discover` e `discover:ai`)
+   acham o ícone publicado no site oficial da instituição; **nada entra sem curadoria visual**
+   (o revisor confere marca e domínio) — aprovados viram `forcedUris`.
+5. **Normalização**: cada arte vira PNG 256×256; o SVG original é mantido quando seguro.
+6. **Cadência**: o workflow roda **toda segunda-feira** (e sob demanda), regenera
    `data/bancos.json`, `logos/`, `PREVIEW.md` e `react-native.js`, e **abre um PR** com o
-   relatório e o diff visual dos PNGs. Depois da revisão e merge, uma nova versão vai para o
-   npm. Nada é editado à mão.
+   relatório e o diff visual dos PNGs. Depois da revisão e merge, o mantenedor publica uma
+   nova versão no npm (Release no GitHub). Nada é editado à mão.
 
 Detalhes de manutenção (rodar o pipeline localmente, promover sugestões, overrides, denylist):
 **[CONTRIBUTING.md](CONTRIBUTING.md)**.
 
 ## Limitações conhecidas
 
-- Cobertura de logos = instituições ativas no Open Finance com URL de logo válida. Hoje são 107;
-  o número cresce conforme o ecossistema.
+- Cobertura de logos: 152 hoje (Open Finance + sites oficiais curados); cresce conforme o
+  ecossistema e a curadoria. **Sua instituição está sem logo?** Abra uma issue com o template
+  "Sugestão de match"/"Adicionar logo" apontando a URL no domínio oficial — promovemos rápido.
 - Algumas instituições publicam no diretório o logo da sua **marca de produto** (ex.: Banco CSF →
   cartão Atacadão). É a escolha oficial da própria instituição; se preferir outra arte no seu app,
   use um override local seu.