logos-bancos-br 0.3.0 → 0.4.0

package/README.en.md

@@ -30,17 +30,18 @@
 
 ## What this package gives you
 
-1. **The list of institutions — auto-updated.** The union, keyed by ISPB, of two Central Bank
-   lists: STR participants (every institution with a COMPE code, currently 470) and **active Pix
-   participants** (currently ~880, ~640 of which have no COMPE — fintechs, payment institutions,
-   credit unions). **1,113 institutions** in [`data/bancos.json`](data/bancos.json), with
-   official names, COMPE (when it exists), ISPB and Pix participation attributes.
-2. **Official logos.** Currently **473**, 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`) and the **institution's own official website**
-   (`direct-uri`), visually curated before shipping. Affiliates of single-brand cooperative
-   systems (Sicoob, Sicredi, Cresol, Unicred) get the system's logo via a curated brand rule.
-   Every file carries provenance: source URI, SHA-256 and date.
+1. **The list of institutions — auto-updated, in two sets.** The **main list**
+   ([`data/bancos.json`](data/bancos.json)) carries the **470 institutions with a COMPE code**
+   from the Central Bank STR participants list. The **643 Pix-only institutions** (fintechs,
+   payment institutions, cooperative affiliates — no COMPE) live in a separate dataset
+   ([`data/instituicoes-pix.json`](data/instituicoes-pix.json)) — the main list stays clean,
+   and the full Pix universe is one import away.
+2. **Official logos, deduplicated.** **473 institutions with a logo** backed by **160 distinct
+   files** (~1.7 MB): affiliates of single-brand cooperative systems (Sicoob, Sicredi, Cresol,
+   Unicred) **share one file per system**, marked `logo.source.type: "brand"`. Own logos come
+   from the public **Open Finance Brasil** directory (`openfinance`) or the **institution's own
+   official website** (`direct-uri`, visually curated). 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
@@ -49,11 +50,11 @@
    copies the assets into Flutter/Kotlin/Swift/.NET/PHP projects, CDN URLs with no install — or
    just the JSON.
 
-## Why not a hand-maintained list?
+## Why official sources?
 
-Because it rots: the Central Bank adds, renames and removes institutions throughout the year,
-and banks redesign their brands. Existing libraries ship either **data only** (no logos) or
-logos **hand-collected** from assorted websites with no traceability. The approach here:
+Hand-maintained lists rot: the Central Bank adds, renames and removes institutions throughout
+the year, and banks redesign their brands. Existing libraries ship either **data only** (no
+logos) or logos **collected from assorted websites** with no traceability. The approach here:
 
 - **Official sources, and only them** — the STR and Pix participants CSVs (updated daily by the
   Central Bank itself), the Open Finance Brasil participants directory and, for non-participants,
@@ -82,10 +83,10 @@ Requires **Node ≥ 20** for Node/CLI usage (web and React Native follow your bu
 environment). Zero runtime dependencies. Published with **npm provenance** — verify integrity
 with `npm audit signatures`.
 
-Files are named by **ISPB** (8 digits — which is what lets the ~640 COMPE-less Pix institutions
-in). Lookups accept **COMPE or ISPB**; Pix-only institutions have `compe: null` and are
-addressable by ISPB. Each bank carries a `pix` block (participation attributes, verbatim from
-the BCB list) or `null`.
+Files are named by **ISPB** (8 digits). `banks()` is the main list (COMPE holders);
+`pixInstitutions()` is the separate Pix-only set; `allInstitutions()` is both; `byIspb()`
+resolves across the two. Each institution carries a `pix` block (participation attributes,
+verbatim from the BCB list) or `null`.
 
 ```ts
 import { banks, byCompe, byIspb, logoCdnUrl } from 'logos-bancos-br';
@@ -95,8 +96,9 @@ 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, ~4 MB; keys accept both the
-4-digit COMPE and the 8-digit ISPB — Pix-only institutions by ISPB only):
+**React Native (Expo/Metro)** — static require() map (bundles the 160 distinct logos, ~1.7 MB; keys accept both
+the 4-digit COMPE and the 8-digit ISPB — Pix-only institutions by ISPB only; affiliates point at
+the shared system asset):
 
 ```tsx
 import logos from 'logos-bancos-br/react-native';
@@ -123,20 +125,23 @@ npx logos-bancos-br list
 https://cdn.jsdelivr.net/npm/logos-bancos-br@0.3.0/logos/png/60701190.png
 ```
 
-**Data only** (the bank list):
+**Data only**:
 
 ```ts
-import data from 'logos-bancos-br/data/bancos.json';
+import banks from 'logos-bancos-br/data/bancos.json';          // main list (COMPE)
+import pixOnly from 'logos-bancos-br/data/instituicoes-pix.json'; // Pix-only
 ```
 
 ### API quick reference
 
 | Import | Function | Returns |
 |---|---|---|
-| `logos-bancos-br` | `banks()` | every institution (`Bank[]`) |
+| `logos-bancos-br` | `banks()` | main list — COMPE institutions (`Bank[]`) |
+| | `pixInstitutions()` | Pix-only set (`PixInstitution[]`) |
+| | `allInstitutions()` | both sets (`Institution[]`) |
 | | `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 |
+| | `byIspb(ispb)` | `Institution \| undefined` — resolves across both sets |
+| | `findBank(code)` | `Institution \| 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) |
@@ -144,7 +149,7 @@ import data from 'logos-bancos-br/data/bancos.json';
 | | `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`, `PixInfo`.
+Exported TypeScript types: `Bank`, `PixInstitution`, `Institution`, `BankLogo`, `BankLogoSource`, `PixInfo`.
 
 ## Dataset shape
 
@@ -165,8 +170,10 @@ Exported TypeScript types: `Bank`, `BankLogo`, `BankLogoSource`, `PixInfo`.
 ```
 
 `logo.png` is a normalized transparent 256×256 PNG; `logo.svg` is the original vector when safely
-redistributable; `logo: null` means the institution has no logo in the official sources; `compe: null` marks a
-Pix-only institution (address it by ISPB); `pix: null` marks a non-Pix participant.
+redistributable; `logo: null` means no logo in the official sources; `logo.source.type: "brand"`
+marks a logo inherited from the institution's cooperative system (shared asset, `brand` says
+which); `pix: null` marks a non-Pix participant. Pix-only records (separate dataset) always have
+`compe: null`, a 14-digit `cnpj` and a `pix` block.
 
 ## How the auto-update works
 

package/README.md

@@ -30,18 +30,20 @@
 
 ## O que este pacote entrega
 
-1. **A lista de instituições — atualizada automaticamente.** A união, por ISPB, de duas listas
-   do **Banco Central**: participantes do STR (todas as instituições com código COMPE, hoje 470)
-   e **participantes ativos do Pix** (hoje ~880, das quais ~640 não têm COMPE — fintechs, IPs e
-   cooperativas). São **1.113 instituições** em [`data/bancos.json`](data/bancos.json), com nome
-   oficial, nome reduzido, COMPE (quando existe), ISPB e os atributos de participação no Pix.
-   Você nunca mais mantém uma lista de bancos à mão.
-2. **Logos oficiais.** Hoje **473**, 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.
-   Afiliadas de sistemas cooperativos de marca única (Sicoob, Sicredi, Cresol, Unicred) recebem
-   o logo do sistema por regra curada. Cada arquivo carrega proveniência: URI, SHA-256 e data.
+1. **A lista de instituições — atualizada automaticamente, em dois conjuntos.** A **lista
+   principal** ([`data/bancos.json`](data/bancos.json)) traz as **470 instituições com código
+   COMPE** da lista de participantes do STR do Banco Central. As **643 instituições só-Pix**
+   (fintechs, IPs e cooperativas afiliadas, sem COMPE) ficam num conjunto separado
+   ([`data/instituicoes-pix.json`](data/instituicoes-pix.json)) — a lista principal permanece
+   limpa e quem precisa do universo completo do Pix tem tudo. Ambos com nomes oficiais, ISPB,
+   CNPJ (só-Pix) e atributos de participação no Pix. Você nunca mais mantém uma lista de
+   instituições no seu projeto.
+2. **Logos oficiais, sem duplicação.** **473 instituições com logo** usando **160 arquivos
+   distintos** (~1,7 MB): afiliadas de sistemas cooperativos de marca única (Sicoob, Sicredi,
+   Cresol, Unicred) **compartilham um único arquivo por sistema** e são marcadas com
+   `logo.source.type: "brand"`. Logos próprios vêm do diretório público do **Open Finance
+   Brasil** (`openfinance`) ou do **site oficial da instituição** (`direct-uri`, com curadoria
+   visual). Cada arquivo carrega proveniência: URI, 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**
    a partir das fontes e abre um PR com o diff visual. Banco criado, renomeado ou extinto pelo
@@ -50,11 +52,11 @@
    copia os assets para projetos Flutter/Kotlin/Swift/.NET/PHP, URLs de CDN sem instalar nada —
    ou só o JSON.
 
-## Por que não manter uma lista à mão?
+## Por que fontes oficiais?
 
-Porque ela envelhece: o BCB inclui, renomeia e exclui instituições ao longo do ano, e os bancos
-redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem logos), ou logos
-**coletados manualmente** de sites variados, sem rastreabilidade. A abordagem aqui:
+Listas mantidas manualmente envelhecem: o BCB inclui, renomeia e exclui instituições ao longo do
+ano, e os bancos redesenham suas marcas. As bibliotecas existentes ou trazem **só dados** (sem
+logos), ou logos **coletados de sites variados**, sem rastreabilidade. A abordagem aqui:
 
 - **Fontes oficiais, e apenas elas** — os CSVs de participantes do STR e do Pix (que o próprio
   BCB atualiza diariamente), o diretório de participantes do Open Finance Brasil e, para quem não
@@ -90,12 +92,16 @@ as ~640 instituições do Pix que não têm código COMPE). As consultas aceitam
 ### JavaScript / TypeScript (Node ou web)
 
 ```ts
-import { banks, byCompe, byIspb, logoCdnUrl } from 'logos-bancos-br';
+import { banks, pixInstitutions, allInstitutions, byCompe, byIspb, logoCdnUrl } from 'logos-bancos-br';
+
+banks();             // lista principal: 470 instituições com COMPE
+pixInstitutions();   // conjunto separado: 643 só-Pix (fintechs, IPs, afiliadas)
+allInstitutions();   // as duas juntas (1.113)
 
 byCompe(341);        // { ispb: '60701190', compe4: '0341', name: 'Itaú Unibanco S.A.', logo: {...} }
 byCompe('0260');     // Nubank — '260', 260 e '0260' são equivalentes
 byIspb('00000000');  // Banco do Brasil
-byIspb('11275560');  // RecargaPay — instituição só-Pix (compe: null), endereçável por ISPB
+byIspb('11275560');  // RecargaPay — só-Pix; byIspb resolve nos DOIS conjuntos
 
 logoCdnUrl(341);     // https://cdn.jsdelivr.net/npm/logos-bancos-br@x.y.z/logos/png/60701190.png
 
@@ -120,9 +126,9 @@ import logos from 'logos-bancos-br/react-native'; // mapa require() estático
 ```
 
 > As chaves do mapa aceitam o COMPE com 4 dígitos (`'0341'`) **e** o ISPB (`'60701190'`;
-> instituições só-Pix aparecem apenas pelo ISPB). Importar esse entry adiciona **todos** os
-> logos (~4 MB) ao bundle. Se preferir empacotar só alguns, use o CLI abaixo e faça `require()`
-> dos arquivos copiados.
+> instituições só-Pix aparecem apenas pelo ISPB; afiliadas apontam para o asset compartilhado do
+> sistema). Importar esse entry adiciona os **160 logos distintos** (~1,7 MB) ao bundle. Se
+> preferir empacotar só alguns, use o CLI abaixo e faça `require()` dos arquivos copiados.
 
 ### Node (caminho dos arquivos no disco)
 
@@ -155,22 +161,23 @@ https://cdn.jsdelivr.net/npm/logos-bancos-br@0.3.0/logos/svg/18236120.svg
 Fixe sempre uma versão (`@0.3.0`) — a correspondência COMPE→ISPB está em
 [`data/bancos.json`](data/bancos.json).
 
-### Só os dados (lista de bancos)
+### Só os dados
 
 ```ts
-import dados from 'logos-bancos-br/data/bancos.json';
-// todas as instituições: ispb, compe/compe4 (ou null p/ só-Pix), nomes oficiais,
-// pix (atributos de participação, ou null) e logo (ou null)
+import bancos from 'logos-bancos-br/data/bancos.json';            // lista principal (COMPE)
+import soPix from 'logos-bancos-br/data/instituicoes-pix.json';   // só-Pix (sem COMPE)
 ```
 
 ### Referência rápida da API
 
 | Import | Função | Retorna |
 |---|---|---|
-| `logos-bancos-br` | `banks()` | todas as instituições (`Bank[]`) |
+| `logos-bancos-br` | `banks()` | lista principal — instituições com COMPE (`Bank[]`) |
+| | `pixInstitutions()` | só-Pix, sem COMPE (`PixInstitution[]`) |
+| | `allInstitutions()` | os dois conjuntos (`Institution[]`) |
 | | `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 |
+| | `byIspb(ispb)` | `Institution \| undefined` — resolve nos dois conjuntos |
+| | `findBank(codigo)` | `Institution \| 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) |
@@ -178,7 +185,7 @@ import dados from 'logos-bancos-br/data/bancos.json';
 | | `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`, `PixInfo`.
+Tipos TypeScript exportados: `Bank`, `PixInstitution`, `Institution`, `BankLogo`, `BankLogoSource`, `PixInfo`.
 
 ## O dataset
 
@@ -219,10 +226,12 @@ Um registro de `data/bancos.json`:
   `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).
-- `compe`/`compe4: null` — instituição só-Pix (sem código COMPE); endereçe por ISPB.
-- `pix` — atributos verbatim da lista de participantes ativos do Pix do BCB (tipo de
-  participação no SPI e no Pix, modalidade, tipo de instituição, autorizada pelo BCB);
-  `null` quando a instituição não é participante ativa do Pix.
+- `logo.source.type: "brand"` — logo herdado do sistema cooperativo (campo `brand` diz qual,
+  ex.: `"SICOOB"`); o arquivo é **compartilhado** entre as afiliadas do sistema.
+- `pix` — atributos verbatim da lista de participantes ativos do Pix do BCB; `null` quando a
+  instituição não é participante ativa.
+- Em `instituicoes-pix.json`, cada registro tem `compe: null`, `cnpj` (14 dígitos) e `pix`
+  sempre presente.
 
 ## Como funciona a atualização automática
 
@@ -237,7 +246,8 @@ Um registro de `data/bancos.json`:
    entra o `forcedMatches`, revisado à mão a partir das sugestões do relatório.
 4. **Sistemas cooperativos**: afiliadas que carregam a marca do sistema no nome oficial
    (Sicoob, Sicredi, Cresol, Unicred) recebem o logo do sistema por regra curada — explícita e
-   auditável, não semelhança fuzzy.
+   auditável, não semelhança fuzzy — e **compartilham um único arquivo por marca** (nada de
+   centenas de cópias do mesmo PNG).
 5. **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`.
@@ -252,10 +262,10 @@ Detalhes de manutenção (rodar o pipeline localmente, promover sugestões, over
 
 ## Limitações conhecidas
 
-- Cobertura de logos: 473 de 1.113 hoje (Open Finance + regra de marca cooperativa + 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.
+- Cobertura de logos: 473 de 1.113 instituições (153 na lista principal; o restante são
+  afiliadas com logo de sistema e só-Pix); 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.