discolike-python

discolike-python é o SDK e CLI oficial em Python para a API DiscoLike, um mecanismo de busca empresarial que indexa mais de 80 milhões de sites de negócios em todo o mundo, em 50 idiomas. O repositório inclui dois pacotes: discolike (a biblioteca SDK) e discolike-cli (a interface de linha de comando, que depende do SDK). Ambos exigem Python 3.10+. O SDK fornece um cliente tipado (Discolike) e uma contraparte assíncrona (AsyncDiscolike) para interagir com a API da DiscoLike. As principais capacidades incluem descobrir empresas semelhantes por texto de ICP, frases, stack de tecnologia, geografia e mais de 40 outros filtros; contar segmentos antes de extraí-los; associar nomes de empresas desorganizados (com telefone, cidade e estado opcionais) a domínios em modo único ou em lote via CSV; enriquecer listas de domínios em CSV com conjuntos de dados da DiscoLike; segmentar automaticamente listas de domínios; validar listas de domínios contra definições de ICP; recuperar perfis completos de empresas com firmografia, pontuações, dados de crescimento, redirecionamentos, fornecedores e subsidiárias; pesquisar, consultar, associar e descobrir contatos em empresas-alvo; e executar pesquisas DiscoGen sobre conjuntos de domínios com busca na web habilitada. A autenticação suporta três métodos: signup (abre uma conta a partir de e-mail e nome sem navegador, com o proprietário confirmando por e-mail), login OAuth (fluxo de código de autorização PKCE baseado em navegador com redirecionamento de loopback, ou modo headless que imprime a URL) e chave de API (via variável de ambiente DISCOLIKE_API_KEY, arquivo de configuração do CLI ou parâmetro explícito). As credenciais OAuth são renovadas proativamente dentro de 60 segundos antes da expiração e mais uma vez após um 401. O cliente também suporta trazer seu próprio httpx2.Client ou httpx2.AsyncClient. Todos os modelos de requisição são gerados a partir da especificação OpenAPI da plataforma e validados localmente com Pydantic antes de qualquer requisição ser enviada, então valores de enum inválidos ou números fora do intervalo nunca custam uma ida e volta. Todas as respostas são modelos Pydantic tipados. Erros herdam de DiscolikeError com subclasses específicas para autenticação, acesso ao plano, não encontrado, servidor, limite de taxa, validação e falhas de conexão com a API. Falhas transitórias são repetidas automaticamente (3 tentativas por padrão). Operações em lote de longa duração (match.bulk, segment, validate_icp, contacts.bulk_match) retornam um identificador de Job em vez de bloquear. Job.wait() bloqueia até a conclusão, Job.status() consulta sem bloquear e Job.cancel() aborta. Em trabalhos da família DiscoGen, o JobStatus retornado carrega avisos, estimated_cost e cost_metadata, incluindo uso por modelo e entradas do provedor de busca. JobTimeoutError é apenas um limite de espera do lado do cliente — a tarefa continua sendo executada no servidor, então wait() pode ser chamado novamente para retomar. O CLI espelha as capacidades do SDK com comandos para discover, count, match, extract, validate-icp, append, segment, signup, além de grupos de comandos para auth, company, contacts, discogen, queries, account, search-providers e llm-providers. Os resultados são impressos como JSON no stdout por padrão, com --format table para saída legível quando stdout é um TTY. Endpoints assíncronos aceitam --wait para bloquear até o trabalho terminar, ou retornam um task_id para consulta. Os códigos de saída são padronizados: 0 sucesso, 1 erro de servidor, 2 erro de validação, 3 erro de autenticação/plano, 4 limite de taxa, 5 erro de rede, 6 não encontrado. O repositório é estruturado como um workspace uv com dois membros: packages/discolike (o SDK) e packages/discolike-cli (o CLI). O desenvolvimento usa pytest para testes, ruff para linting e um script de geração de código (scripts/gen_requests.py) para regenerar modelos de requisição a partir da especificação OpenAPI. A pasta examples/ contém scripts executáveis para fluxos de trabalho comuns, incluindo associar exportações de contatos de CRM a IDs de persona da DiscoLike com checkpointing e retomada, encontrar e-mails de trabalho em lote a partir de um CSV e descobrir empresas por ICP e depois enriquecê-las com DiscoGen. O projeto é licenciado sob MIT.