fix(meta-ad-library): default reached countries to US

[patrickadeelino]

Contexto

O handler da Meta Ad Library no MindsDB precisava ficar mais confiável para consultas reais sobre páginas e criativos públicos, especialmente nos cenários em que o datasource não nasce com um escopo rígido pré-configurado e o recorte da busca precisa ser resolvido a partir da própria query.

Na prática, isso aparecia em dois pontos. Primeiro, o comportamento padrão de ad_reached_countries ainda permitia configurações amplas demais para o uso que estamos validando localmente, o que reduzia a previsibilidade dos resultados. Segundo, o handler precisava aceitar melhor o recorte vindo da query, sem obrigar que todo datasource já trouxesse search_page_ids ou search_terms salvos de antemão.

O que foi implementado

O PR ajusta o handler meta_ad_library para tornar o comportamento default mais aderente ao fluxo real do produto e às consultas que o Data Agent faz sobre a tabela ads.

O primeiro ajuste foi padronizar o default de ad_reached_countries para US e normalizar em runtime configurações legadas que ainda chegarem como ALL. Com isso, o handler passa a trabalhar com um recorte compatível com o fixture operacional que estamos usando e evita respostas vazias ou pouco estáveis causadas por uma configuração excessivamente ampla.

O segundo ajuste foi reforçar a resolução de escopo no momento da query. Quando o datasource não traz search_page_ids ou search_terms persistidos, o handler passa a derivar esse escopo a partir de filtros sobre page_id ou page_name, preservando a ideia de datasource aberto e deixando o recorte da consulta sob controle da própria pergunta executada.

O PR também mantém o caminho de observabilidade do handler mais explícito, registrando o request efetivo enviado para a Meta, os filtros aplicados, o comportamento de paginação e a distinção entre filtros remotos e filtros locais quando existe LIMIT combinado com condições que o provider não consegue empurrar para a API.

Arquitetura e decisões

A principal decisão foi manter o handler orientado a um datasource aberto, em vez de exigir que toda criação de connector persista um escopo fixo. Isso deixa o MindsDB mais alinhado ao uso do Data Agent, onde a pergunta do usuário deve ser capaz de determinar o recorte final por page_id ou page_name.

A normalização de ad_reached_countries foi colocada no próprio handler, em runtime, em vez de depender de migração corretiva ou recriação de conectores já existentes. Assim, o comportamento fica consistente tanto para novos datasources quanto para configurações legadas ainda presentes no ambiente.

Outra decisão importante foi preservar a diferença entre filtros que podem ser traduzidos para a API da Meta e filtros que continuam sendo aplicados localmente. O handler amplia a janela de coleta quando há filtros locais com LIMIT, mas sem perder o controle sobre custo e paginação, o que evita resultados artificialmente vazios em consultas mais específicas.

Pontos de atenção para review

Vale revisar se o default para US está coerente com o recorte de produto que queremos sustentar neste rollout e se existe algum fluxo que ainda dependa explicitamente de ALL como comportamento esperado.

Também é importante validar se a resolução de escopo a partir de page_id e page_name cobre bem os cenários principais do Data Agent sem introduzir ambiguidade entre filtros usados para buscar dados na Meta e filtros aplicados apenas localmente no handler.