Criando uma biblioteca compartilhada de links de afiliados para dois sites

Eu uso links de afiliados no vdaluz.com (Amazon Associates, Proton Partners, uma indicação da AdGuard), e o dev log do imperfectsystems.com estava prestes a precisar da mesma coisa. Eu já tinha extraído um pacote compartilhado de componentes de blog, @vdaluz/astro-blog, quando separei os dois sites. Em vez de escrever um segundo sistema de afiliados, ligeiramente diferente, para o novo site, eu também levei o tratamento de afiliados para o próprio pacote: @vdaluz/astro-affiliate.

Problema

Os links de afiliados do vdaluz.com tinham se desalinhado. Um levantamento mediu 72 posts usando 4 ou mais textos diferentes para a mesma frase de divulgação da Amazon, e o texto de divulgação de um dos programas nunca chegava a ser renderizado em lugar nenhum, apesar de estar definido na configuração. Divulgações digitadas à mão, uma por uma, não escalam, e eu estava prestes a duplicar essa mesma bagunça em um segundo site.

Investigação

O ajuste não é só “escrever um componente”, é tornar estruturalmente impossível publicar um link de afiliado sem sua divulgação. Isso significa que a exigência de divulgação precisa morar no build, não na memória de alguém para lembrar de acrescentar uma frase.

Eu optei por um formato de chave como amazon.atomicHabits ou proton.pass: nome do programa, ponto, chave do item. No markdown, um link vira [Atomic Habits](affiliate:amazon.atomicHabits). Um plugin remark percorre a AST no momento do build, resolve isso para a URL real, e confere cada programa realmente usado contra o affiliates: [amazon] do frontmatter do post. Use um link de afiliado sem declarar o programa, e o build falha com uma mensagem dizendo exatamente o que adicionar. Conformidade por construção em vez de conformidade por memória.

Solução

O pacote espelha as convenções do astro-blog quase à risca: código-fonte .ts/.astro puro, sem etapa de build, exports por caminho, sem dependências, distribuído como um tarball fixado por tag (a resolução do npm para o formato abreviado do GitHub reescreve para git+ssh, que falha em CI sem chaves SSH, então a URL do tarball é a única forma que sobrevive a um runner de CI). Cada site fornece seu próprio catálogo, tag de rastreamento e texto de divulgação via configuração; o pacote não carrega nenhum dado de afiliado próprio.

Dois tipos de programa: amazon constrói a URL a partir de um ASIN e da tag de Associates do site, links é só um mapa simples de chave para URL para tudo mais (Proton, AdGuard, o que vier a seguir). Um componente <AffiliateDisclosure> lê o array affiliates de um post e renderiza o texto certo no topo do corpo do post, acima da dobra, que é o que a FTC realmente quer: divulgação antes dos links, não escondida num rodapé.

Reflexão

A verificação tomou uma forma um pouco fora do comum. Eu empacotei o tarball de verdade e instalei no vdaluz.com como um consumidor real, depois rodei astro check e astro build contra uma página descartável exercitando cada export, o que revelou problemas reais de tipo e de runtime que um teste mockado não pegaria. Para o plugin remark especificamente, esbarrei num detalhe pequeno mas instrutivo: o suporte nativo do Node a TypeScript remove os tipos mas ainda exige resolução ESM pura, o que requer extensões .ts explícitas em imports relativos, enquanto o código-fonte do pacote deliberadamente as omite, já que isso é o correto para consumo via bundler. Um script rápido contra o código-fonte real falhou com um erro de módulo não encontrado que não tinha nada a ver com a lógica em si. A solução foi testar as partes sensíveis à extensão pelo pipeline real do Astro, e só recorrer a um script Node isolado e rápido quando o código não tem nenhuma superfície de Astro, copiando arquivos com extensões corrigidas em vez de tocar no código-fonte real.

O pacote está no ar em github.com/vdaluz/astro-affiliate, v0.1.0. O próximo passo é de fato conectá-lo aos dois sites e fazer a varredura de divulgação nos posts existentes do vdaluz.com.