TCGOffers

Instalação do TCGOffers

Este guia cobre como instalar a extensão no Chrome, configurar a URL da API, rodar tudo localmente para desenvolvimento e resolver os problemas mais comuns. A extensão ainda não está publicada na Chrome Web Store: a instalação é feita a partir do código-fonte.

Sumário

Para usuários

Pré-requisitos

Obter a extensão

A extensão pode ser baixada como .zip no site (veja Instalar pelo .zip) ou gerada a partir deste repositório. Não há link de loja.

git clone <url-do-repositório> tcgoffers-extension
cd tcgoffers-extension
npm ci
make build DEV=0

make build DEV=0 gera a pasta dist/ em modo de produção, sem logs de depuração. O equivalente sem make é npm run build, que também gera o modo de produção, desde que TCGOFFERS_DEV não esteja definido como 1. Para apontar para outra API, veja Configurar a API.

A pasta dist/ é a extensão propriamente dita. Ela é o que o Chrome carrega.

Instalar pelo .zip

  1. Baixe o arquivo tcgoffers-latest.zip pelo botão Baixar extensão (.zip) da página inicial.
  2. Descompacte o arquivo em uma pasta sua, por exemplo Documentos/tcgoffers. Não apague a pasta depois: o Chrome lê a extensão dela.
  3. Abra chrome://extensions no Chrome.
  4. Ative o Modo do desenvolvedor (canto superior direito).
  5. Clique em Carregar sem compactação e selecione a pasta descompactada (a que contém manifest.json).

Para atualizar, baixe o .zip de novo, descompacte por cima da mesma pasta e clique em recarregar na extensão em chrome://extensions.

Carregar no Chrome

  1. Abra chrome://extensions.
  2. Ative o Modo do desenvolvedor (canto superior direito).
  3. Clique em Carregar sem compactação.
  4. Selecione a pasta dist/ dentro do repositório.

A extensão TCGOffers aparece na lista. Ela continua carregada enquanto a pasta dist/ existir no disco; se você apagar ou mover a pasta, o Chrome remove a extensão do carregamento.

Fixar na barra

Para ver o ícone da extensão sempre visível, clique no ícone de quebra-cabeça (Extensões) na barra do Chrome e, na linha do TCGOffers, escolha Fixar. O popup abre por esse ícone e mostra:

Página de boas-vindas (consentimento)

Logo após a primeira instalação, o Chrome abre automaticamente a página TCGOffers - Contribuir. Ela explica o que é coletado:

Clique em Contribuir. Ao aceitar, a extensão registra a instalação na API e recebe um token; a mensagem Pronto! confirma que a coleta começou. Nada é coletado nem enviado antes desse clique.

Se a página não abrir (por exemplo, você fechou a aba), clique no popup em Ativar contribuição, que abre a mesma página. Se aparecer Não foi possível ativar agora. Tente novamente., veja Solução de problemas.

Ver o painel numa página de carta

Abra uma página de carta na LigaMagic, por exemplo:

https://www.ligamagic.com.br/?view=cards%2Fcard&card=Sirocco&tipo=1

A extensão só atua em https://www.ligamagic.com.br/*. Na página da carta, aparece o painel com a tendência de 30 dias de cada edição. Se a aba já estava aberta antes da instalação ou de uma atualização, recarregue a aba (a extensão só é injetada em páginas carregadas depois dela).

Atualizar para uma nova versão

Ao receber uma nova versão do código:

git pull
npm ci          # só se as dependências mudaram
make build DEV=0

Depois:

  1. Em chrome://extensions, clique no ícone de recarregar do TCGOffers.
  2. Recarregue as abas da LigaMagic que estavam abertas.

A fila local, o consentimento e o token são mantidos: atualizar não pede o consentimento de novo. Confira a Versão no popup: ela muda para o novo build.

Desinstalar e os seus dados

Para parar de contribuir, use Parar de contribuir no popup antes de remover a extensão. Esse botão:

  1. Pede confirmação, informando quantas observações pendentes serão descartadas.
  2. Apaga os dados locais (fila, token e consentimento).
  3. Revoga a instalação na API: o token é removido e a instalação é marcada como revogada.

Depois disso, remova a extensão em chrome://extensions com Remover.

Se você remover a extensão sem passar pelo botão, o Chrome apaga os dados locais (fila, token e consentimento), mas a instalação continua ativa na API até ser revogada. As observações já enviadas permanecem no histórico comunitário, sem identificação pessoal: a revogação só desliga a instalação.

Configurar a API

A extensão fala com a API em uma única URL, definida no build:

# npm
TCGOFFERS_API_BASE=https://api.tcgoffers.com npm run build

# make
make build DEV=0 API_BASE=https://api.tcgoffers.com

Além disso, o Chrome só deixa a extensão falar com origens listadas em host_permissions do public/manifest.json. Hoje estão listadas:

"host_permissions": ["https://www.ligamagic.com.br/*", "http://localhost:8090/*"]

Para apontar para outro servidor, inclua a origem da API nessa lista (por exemplo, "https://api.tcgoffers.com/*") antes de gerar o build. Sem isso, o Chrome bloqueia as requisições e a instalação não é registrada.

Para desenvolvedores

Rodar a API localmente

A API está em ../liga-insights-api (Laravel 13, com Sail). Ela sobe em http://localhost:8090, com Postgres na porta 55433 e Redis na porta 16380. Requisitos: Docker e as dependências do Sail.

cd ../liga-insights-api
cp .env.example .env
make up                 # sail up -d --build (app, Postgres e Redis)
make key-generate
make migrate && make seed

Na primeira vez, sem a pasta vendor/, instale as dependências com a imagem do Sail (é preciso docker compose build laravel.test antes):

docker run --rm -v "$PWD":/var/www/html -w /var/www/html --entrypoint composer sail-8.5/liga-insights-api install

Na extensão, make api-up sobe a API se ela não estiver respondendo (ele chama make -C ../liga-insights-api up).

Build de desenvolvimento

make build gera o build de desenvolvimento por padrão (DEV=1): logs de depuração com o prefixo [liga] e um rodapé de desenvolvimento no painel. Para o build de produção, use DEV=0.

make install    # npm ci
make build      # dist/ em modo de desenvolvimento

make dev faz tudo de uma vez: sobe a API se preciso, gera o build de desenvolvimento e começa a acompanhar os dados locais.

Acompanhar os dados enviados (check e watch)

Recarregar sem clicar (reload)

Para o Chrome de teste headless, make reload gera o build de desenvolvimento, reinicia o Chrome e carrega o novo dist/ sem cliques. Use make chrome para subir esse Chrome, make chrome-stop para encerrá-lo e make chrome-visible apenas se quiser acompanhar a navegação em uma janela visível (ele rouba o foco).

Testes e CI

npm test             # Vitest + jsdom
npm run typecheck    # tsc --noEmit
npm run ci           # typecheck, testes e build, como na CI
make ci              # o mesmo que npm run ci

Depois de qualquer mudança de código, rode npm run build (ou npm run ci): o Chrome carrega a extensão de dist/, então testes verdes não bastam para ver a mudança no navegador.

Testes end-to-end

make e2e                # build de desenvolvimento e checagem do painel numa página de carta (padrão: Counterspell)
make e2e CARD=Stifle    # outra carta
KEEP=1 make e2e         # não limpa nada, para depurar
make e2e-clean          # remove o que sobrou de uma execução interrompida

make e2e usa um Chrome for Testing próprio, com perfil temporário e a porta 9223. Ao terminar, limpa o Chrome, o perfil, os logs e a instalação de teste registrada na API. Se a execução for interrompida (Ctrl+C, queda da API), rode make e2e-clean. Não rode make e2e-clean enquanto um make e2e estiver em andamento.

Na primeira vez, o Chrome for Testing é baixado para ~/.cache/tcgoffers/cft com make chrome-install. Para limpar esse cache e o perfil headless persistente, use make clean-all; make clean remove apenas dist/, coverage/, o cache do Vitest e os restos do e2e.

Alertas no Telegram (lojistas)

Os alertas de variação de preço pelo Telegram são configurados no próprio popup da extensão e no painel da página da carta. O passo a passo e as regras estão na seção Alertas no Telegram (lojistas) do README.

Solução de problemas

O painel não aparece na página da carta.

A API está inacessível.

Erro 429 ao ativar (INSTALLS_PER_HOUR).

A extensão não atualiza depois de um novo build.