{"_id":"@cafeina_dev/ispb-participants","name":"@cafeina_dev/ispb-participants","dist-tags":{"latest":"1.2.0"},"versions":{"1.2.0":{"name":"@cafeina_dev/ispb-participants","version":"1.2.0","description":"JavaScript and TypeScript package for SPI and Pix participants, built from an internal auditable catalog derived from official Banco Central do Brasil sources","keywords":["pix","ispb","spi","banco-central","brazil","bacen","participants","catalog","dataset","fintech"],"author":{"name":"Thiago Prazeres","email":"thiago@cafeina.dev"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cafeinadesign/ispb-participants.git"},"homepage":"https://cafeinadesign.github.io/ispb-participants","bugs":{"url":"https://github.com/cafeinadesign/ispb-participants/issues"},"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"}},"scripts":{"update-catalog":"tsx scripts/update-catalog.ts","validate:catalog":"tsx scripts/validate-catalog.ts","build":"tsup","generate":"tsx scripts/generate-artifacts.ts","build:web":"tsx web/ssg.ts","test":"vitest run --exclude test/smoke-sources.test.ts","test:smoke-sources":"vitest run test/smoke-sources.test.ts","prepublishOnly":"npm run generate && npm run build && npm run build:web"},"publishConfig":{"access":"public"},"engines":{"node":">=18"},"devDependencies":{"@types/node":"^22.0.0","ajv":"^8.17.1","csv-parse":"^6.2.1","marked":"^15.0.7","tsup":"^8.0.0","tsx":"^4.21.0","typescript":"^5.0.0","vitest":"^3.0.0"},"gitHead":"4ff125432d636c64f57a517837e7f0a9e72d2a35","_id":"@cafeina_dev/ispb-participants@1.2.0","_nodeVersion":"25.9.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-56JJIxkpY9ruMkoC6q6SwxzZyUawwIZQen84xOKBtpj6FealNu8MjL02/U18Vg3z9WMvreDZ/9Xb9/HSMS4DdQ==","shasum":"dfe5283eff4d67cdb485eb6f3b2f957065991a17","tarball":"https://registry.npmjs.org/@cafeina_dev/ispb-participants/-/ispb-participants-1.2.0.tgz","fileCount":8,"unpackedSize":6074039,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAKXp0IJ4gB+doxpaSLtPDvI+1TQeQXPRhgMZESqHrNuAiBzd1vTsKYcpuIVAfIhm/x0ba3KYnsKGmLGSYIk+Rd8cg=="}]},"_npmUser":{"name":"cafeina.dev.br","email":"grupocafeinadesign@gmail.com"},"directories":{},"maintainers":[{"name":"cafeina.dev.br","email":"grupocafeinadesign@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ispb-participants_1.2.0_1777929389929_0.11383922195168816"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-04T21:16:29.795Z","1.2.0":"2026-05-04T21:16:30.122Z","modified":"2026-05-04T21:16:30.372Z"},"maintainers":[{"name":"cafeina.dev.br","email":"grupocafeinadesign@gmail.com"}],"description":"JavaScript and TypeScript package for SPI and Pix participants, built from an internal auditable catalog derived from official Banco Central do Brasil sources","homepage":"https://cafeinadesign.github.io/ispb-participants","keywords":["pix","ispb","spi","banco-central","brazil","bacen","participants","catalog","dataset","fintech"],"repository":{"type":"git","url":"git+https://github.com/cafeinadesign/ispb-participants.git"},"author":{"name":"Thiago Prazeres","email":"thiago@cafeina.dev"},"bugs":{"url":"https://github.com/cafeinadesign/ispb-participants/issues"},"license":"MIT","readme":"<img src=\"https://cafeinadesign.github.io/ispb-participants/logo.svg\" alt=\"ISPB Participants Catalog\" width=\"260\" height=\"52\">\n\n_Catálogo público derivado de fonte oficial do Banco Central_\n\n[![website](https://img.shields.io/badge/site-ispb--participants-025c75)](https://cafeinadesign.github.io/ispb-participants)\n[![npm](https://img.shields.io/npm/v/@cafeina_dev/ispb-participants)](https://www.npmjs.com/package/@cafeina_dev/ispb-participants)\n[![license code](https://img.shields.io/badge/code-MIT-blue)](./LICENSE)\n[![license data](https://img.shields.io/badge/data-ODC--By%201.0-0b7285)](./LICENSE_DATA)\n\nO ISPB Participants Catalog é um catálogo público derivado de fonte oficial do Banco Central do Brasil para participantes do SPI e do Pix. O projeto coleta, valida, normaliza, versiona e redistribui artefatos derivados, preservando distinções semânticas entre SPI, participantes ativos do Pix e instituições em processo de adesão.\n\n**Não é a fonte oficial. Não substitui a consulta oficial.**\n\n## Contagens públicas\n\nEste repositório é um catálogo **multi-dataset**. As contagens públicas devem ser lidas por dataset, usando `current/manifest.json` como fonte de verdade.\n\n- `910` refere-se **somente** a `pix_active_participants` no snapshot atual.\n- `892` refere-se a `spi_participants` no snapshot atual.\n- `21` refere-se a `pix_in_adhesion` no snapshot atual.\n- `1823` refere-se a `catalog_crosswalk` no snapshot atual.\n\nNão existe um único número genérico de manchete que represente “o tamanho total do catálogo”, porque o catálogo combina datasets com escopos semânticos diferentes e um crosswalk derivado.\n\n## Getting started\n\n```bash\nnpm install @cafeina_dev/ispb-participants\n```\n\n```ts\nimport {\n  getInstitutionByIspb,\n  getInstitutionStatusByIspb,\n  searchInstitutionsByName,\n  hasIspb,\n} from '@cafeina_dev/ispb-participants';\n\n// Lookup por ISPB\nconst inst = getInstitutionByIspb('60746948');\nconsole.log(inst?.name);          // \"BANCO BRADESCO S.A.\"\nconsole.log(inst?.inSpi);         // true\nconsole.log(inst?.inPixActive);   // true\nconsole.log(inst?.inPixAdhesion); // false\nconsole.log(inst?.matchConfidence); // \"exact_ispb\"\n\n// Status resumido\nconst status = getInstitutionStatusByIspb('60746948');\n\n// Busca por nome\nconst resultados = searchInstitutionsByName('nubank');\n\n// Checar existência\nconst existe = hasIspb('60746948'); // true\n```\n\n> [Documentação completa de getting started →](./docs/getting-started.md)\n\n## API pública\n\n| Export | Tipo | Descrição |\n|---|---|---|\n| `INSTITUTIONS` | `Record<string, InstitutionEntry>` | Índice derivado oficial e lookup-safe por ISPB — **não canônico** |\n| `SPI_PARTICIPANTS` | `SpiParticipantRecord[]` | Dataset canônico completo do SPI |\n| `PIX_ACTIVE_PARTICIPANTS` | `PixActiveParticipantRecord[]` | Dataset canônico de ativos do Pix |\n| `PIX_IN_ADHESION` | `PixInAdhesionRecord[]` | Dataset canônico de adesão ao Pix |\n| `getInstitutionByIspb(ispb)` | função | Lookup por ISPB no índice derivado |\n| `getSpiParticipantByIspb(ispb)` | função | Lookup canônico no SPI |\n| `getPixActiveParticipantByIspb(ispb)` | função | Lookup canônico no Pix ativo |\n| `getInstitutionStatusByIspb(ispb)` | função | Status resumido de participação |\n| `searchInstitutionsByName(query)` | função | Busca por nome (ascii-folded) |\n| `hasIspb(ispb)` | função | Verifica existência no índice |\n| `getMetadata()` | função | Resumo público canônico com contagens explícitas por dataset |\n| `getCatalogMetadata()` | função | Metadados completos do catálogo com as mesmas contagens explícitas |\n\n> [Referência completa da API →](./docs/api.md) | [Qual export usar? →](./docs/which-export.md)\n\n## `INSTITUTIONS` é o índice oficial de lookup por ISPB — e não um dataset canônico\n\n`INSTITUTIONS` é a camada derivada oficial para consumo por ISPB no pacote. Ela existe para que um ISPB válido extraído de um EndToEndId do Pix possa ser resolvido sem falso negativo sempre que esse ISPB aparecer explicitamente em qualquer dataset canônico.\n\nOs datasets canônicos continuam separados (`SPI_PARTICIPANTS`, `PIX_ACTIVE_PARTICIPANTS`, `PIX_IN_ADHESION`). `INSTITUTIONS` não substitui essa separação: ele só fornece um índice derivado e lookup-safe por ISPB. Cada entrada preserva marcadores explícitos de origem:\n\n```ts\ninst.inSpi         // boolean — está em spi_participants?\ninst.inPixActive   // boolean — está em pix_active_participants?\ninst.inPixAdhesion // boolean — está em pix_in_adhesion?\ninst.matchConfidence // 'exact_ispb' | 'unique_cnpj' | 'no_auto_match' | 'derived'\ninst.sourceDatasets  // datasets canônicos que contribuíram\n```\n\n**Adesão ≠ participação ativa.** Se `inPixActive` é `false` e `inPixAdhesion` é `true`, a instituição está em processo de adesão — não é participante ativo do Pix.\n\n> [Escopo semântico →](./docs/semantic-scope.md) | [Datasets →](./docs/datasets.md)\n\n## O que este projeto é\n\n- Um catálogo público derivado, com snapshots versionados, schemas explícitos, manifestos e proveniência auditável.\n- Um pacote npm público para consulta de participantes por ISPB, gerado a partir de `current/`.\n- Uma pipeline diária que coleta somente fontes oficiais públicas do Banco Central, valida os artefatos e promove `current/` apenas quando tudo passa.\n\n## O que este projeto não é\n\n- Não é a publicação oficial primária do Banco Central.\n- Não é \"dados abertos oficiais\".\n- Não mascara divergências entre SPI, participantes ativos do Pix e instituições em adesão.\n- Não faz chamadas de rede em runtime no pacote publicado.\n- Não inventa equivalências silenciosas.\n\n## Estrutura interna\n\n- `current/` — snapshot promovido mais recente e validado.\n- `snapshots/YYYY-MM-DD/` — histórico versionado de snapshots.\n- `schemas/` — JSON Schemas dos quatro datasets canônicos.\n- `sources/registry.json` — cadastro das fontes oficiais.\n- `datapackage.json` — descriptor do catálogo derivado.\n- `docs/` — documentação editorial e operacional.\n- `src/catalog/` — núcleo canônico único de tipos, normalização, validação, matching e metadados.\n- `src/generated/` — artefatos gerados consumidos pelo runtime do pacote.\n- `web/` — SSG que gera o site estático em `site/`.\n\n## Datasets canônicos\n\n| Dataset | Origem |\n|---|---|\n| `spi_participants` | Publicação oficial pública do SPI |\n| `pix_active_participants` | Publicação oficial de participantes ativos do Pix |\n| `pix_in_adhesion` | Publicação oficial de instituições em adesão ao Pix |\n| `catalog_crosswalk` | Camada derivada conservadora de ligação entre datasets |\n\n## Proveniência e atualização\n\n- Pipeline diária às 06:20 BRT.\n- `current/` só é promovido após coleta, parse, validação e escrita de artefatos bem-sucedidos.\n- Se uma fonte oficial falhar, o job falha e o último snapshot válido é preservado.\n\n> [Política de atualização →](./docs/update-policy.md) | [Proveniência →](./docs/provenance.md)\n\n## Licenças\n\n- Código do projeto e do pacote npm: [MIT](./LICENSE)\n- Artefatos derivados do catálogo e dados embutidos no bundle: [ODC-By 1.0](./LICENSE_DATA)\n- A fonte oficial permanece pertencendo ao publicador oficial, Banco Central do Brasil\n\n## Documentação\n\n- [Getting started](./docs/getting-started.md)\n- [API pública](./docs/api.md)\n- [Qual export usar?](./docs/which-export.md)\n- [Datasets](./docs/datasets.md)\n- [Escopo semântico](./docs/semantic-scope.md)\n- [Schemas](./docs/schemas.md)\n- [Contagens e escopo](./docs/counts.md)\n- [Proveniência](./docs/provenance.md)\n- [Política de atualização](./docs/update-policy.md)\n- [Licenças](./docs/licenses.md)\n- [Snapshots](./docs/snapshots.md)\n- [Changelog](./docs/changelog.md)\n- [Visão geral do catálogo](./docs/catalog.md)\n\n## Desenvolvimento\n\n```bash\nnpm run update-catalog    # coleta e promove snapshot\nnpm run validate:catalog  # valida artefatos de current/\nnpm run generate          # gera src/generated/ e docs derivados\nnpm run build:web         # gera o site estático em site/\nnpm test                  # roda testes\nnpm run build             # compila o pacote npm\n```\n","readmeFilename":"README.md","_rev":"1-96e2d83660416270a122aac414805336"}