blcs-search

CLI para pesquisar o catálogo da Biblioteca Lúcio Craveiro da Silva (Braga) a partir do terminal.

O catálogo corre Koha 24.05. A pesquisa usa o feed RSS do OPAC (format=rss), que devolve dados estruturados — título, autor, editora, ano, ISBN, biblionumber. Disponibilidade e cotas vêm da tabela de exemplares da página de detalhe, por isso só são obtidas a pedido (--holdings / --available).

Instalação

bun install
bun run build        # gera o executável ./blcs

Ou correr directamente: bun run src/cli.ts <termos>.

Uso

blcs saramago                          # palavra-chave
blcs -a "valter hugo mãe" --sort pubdate -n 10
blcs -t "a desumanização" --available  # só com exemplar disponível
blcs -i 978-972-0-04494-5              # por ISBN
blcs show 346884                       # exemplares de um registo
blcs -t memorial --json                # saída JSON

Opção	Efeito
-t, -a, -s, -i	índice: título, autor, assunto, ISBN
-n, --limit	nº de resultados (por omissão 20; pagina sozinho acima de 50)
--sort	relevance, title, author, pubdate, popularity
--holdings	vai buscar exemplares/estado de cada resultado (1 pedido extra por registo)
--available	só registos com pelo menos um exemplar disponível (implica --holdings)
--json	saída JSON

Versão web (Cloudflare Worker)

Um Worker serve a página e a API na mesma origem — sem CORS, sem proxy externo.

bun run dev      # wrangler dev → http://localhost:8787
bun run deploy   # wrangler deploy

Rota	Devolve
GET /	página de pesquisa (HTML+JS vanilla, sem framework)
GET /api/search?q=&idx=&sort=&limit=&holdings=&available=	JSON
GET /api/record/<biblionumber>	exemplares de um registo

Travões no Worker: limit máx. 30, disponibilidade só nos primeiros 10 registos por pesquisa (cada um é um pedido extra ao catálogo), e as respostas do catálogo ficam em cache na edge — 1 h para pesquisas, 10 min para exemplares. A página é deep-linkable: ?q=saramago&idx=author.

GitHub Pages sozinho não serve para isto: o catálogo não manda cabeçalhos CORS, e o filtro do Apache exige User-Agent/Referer/Sec-Fetch-*/Accept-Encoding, que o JS do browser não pode definir (são forbidden headers). É preciso alguém do lado do servidor a fazer o pedido.

Notas sobre o servidor

• O Apache à frente do OPAC devolve 403 a opac-search.pl sem o conjunto completo de cabeçalhos de browser (User-Agent, Accept, Accept-Language, Referer, Sec-Fetch-*, Upgrade-Insecure-Requests). Estão em src/http.ts.
• robots.txt é Disallow: /. Os pedidos são serializados com 300 ms de intervalo — uso pessoal pontual, não crawling.
• Máximo de 50 registos por pedido RSS; --limit maior pagina via offset.

Testes

bun test          # parsers, contra HTML/RSS fixo — sem rede
bun run typecheck