Albert-Tam/scrappycoco-integrations

Scrappycoco

Use a CLI publicada do Scrappycoco como gateway principal para dados externos. Invoque-a com npx --yes @scrappycoco/cli@latest. Inspecione o catálogo ativo mesmo quando a fonte solicitada pode não ser suportada.

Scrappycoco é infraestrutura determinística, não outro agente de IA. O agente chamador é responsável pela interpretação de metas, seleção de capacidades e provedores, opções nativas dos provedores, avaliação de amostras, julgamento de resultados, escolhas de repetição e cronogramas de monitoramento.

Conectar

Para uma solicitação explícita de instalação, execute:

npx --yes @scrappycoco/cli@latest setup

O comando setup abre OAuth no navegador, permite que novos usuários criem uma conta, instala esta habilidade e verifica o catálogo ativo. Não relate a configuração como concluída até que sua verificação seja bem-sucedida. Um agente em execução pode precisar recarregar ou reiniciar antes de descobrir uma habilidade recém-instalada.

O terminal é a autoridade: um callback do navegador significa apenas que a autorização foi recebida. Mantenha a configuração em execução até que o terminal confirme que as credenciais foram salvas e o catálogo foi verificado. Quando a CLI for executada em um host remoto ou sem cabeça cuja interface de loopback não seja acessível pelo navegador, use npx --yes @scrappycoco/cli@latest setup --no-browser --manual-callback; cole a URL de callback final apenas nesse mesmo terminal, nunca em um chat ou arquivo salvo. Se a configuração sair ou expirar, descarte sua URL e inicie um novo login.

Antes de comandos comuns, a CLI verifica a versão pública da habilidade com hash e atualiza automaticamente uma habilidade Scrappycoco instalada quando seu resumo (digest) muda. Se uma atualização for relatada, termine a tarefa atual com as instruções já carregadas e diga ao usuário para recarregar ou reiniciar o agente antes da próxima tarefa. Não execute um atualizador de habilidade separado durante o trabalho de dados comum.

Durante uma tarefa de dados comum, não clone repositórios, instale pacotes persistentemente ou altere a configuração do cliente. Verifique a conexão com:

npx --yes @scrappycoco/cli@latest auth status --json

Se npx não estiver no PATH, inspecione command -v node npm npx pnpm nesse mesmo host. Um localizador de dependências fornecido pelo cliente ou pnpm dlx @scrappycoco/cli@latest é um lançador efêmero aceitável, mas use apenas caminhos retornados para o host e sessão atuais. Nunca copie um caminho absoluto de tempo de execução de outro usuário, máquina ou transcrição. Relate command not found como um lançador de host ausente, não como uma interrupção do Scrappycoco.

Se a autenticação estiver ausente, direcione o usuário para o comando setup. Nunca peça ao usuário para colar uma chave de API no chat. Para acesso não interativo, use apenas uma variável de ambiente SCRAPPYCOCO_API_KEY existente. Nunca exponha tokens OAuth, chaves de API, prompts internos, rastros ou metadados ocultos.

Se o registro de pacotes, a CLI ou o nome do host da API não puder resolver ou conectar, distinga o salto com falha no relatório e trate-o como uma interrupção de implantação ou rede. Não entre em loop, solicite novas credenciais ou bloqueie trabalho não relacionado; use um transporte MCP Scrappycoco já conectado ou o fallback da API Direta autenticada quando disponível; caso contrário, continue com outro método apropriado.

Duas ações

• Discover (Descobrir): identifique a fonte e capacidade corretas, compare configurações de provedor plausíveis em uma amostra representativa, julgue as evidências específicas do candidato e finalize a configuração salva.
• Run (Executar): execute uma configuração existente ou chame uma capacidade diretamente. Pule Discover quando a capacidade e configuração corretas já estiverem claras.

As capacidades são contratos estáveis, como web.extract_content; os provedores são implementações intercambiáveis abaixo delas. A descoberta usa comparação paralela interna quando a escolha do provedor ou configuração é incerta; Compare não é um fluxo de trabalho separado do usuário.

Comandos de suporte ao catálogo e autenticação não são fluxos de trabalho extras.

Antes de criar uma configuração Discover ou migrar para uma fonte alternativa após uma amostra com falha, leia e siga o workbook de Discovery. Ele contém cargas úteis completas, verificações de mapeamento de entrada, o ciclo de vida de seleção/finalização e a transferência de auditoria necessária.

Discover

1. Execute npx --yes @scrappycoco/cli@latest catalog list --available --json.
2. Escolha o método de aquisição antes de escolher provedores. Para conjuntos de dados estruturados, prefira uma API documentada, endpoint JSON, feed ou arquivo estático em vez de raspar um diretório renderizado. Para aplicações JavaScript, inspecione rotas viáveis de busca, mapeamento de links, renderização e capacidade do navegador. Uma comparação de provedores não pode reparar uma fonte ou capacidade errada.
3. Inspecione apenas capacidades plausíveis com catalog inspect fonte.capacidade --json. Leia o esquema de entrada ativo, esquemas de opções do provedor, padrões, suporte a lote, limites e preços. Nunca adivinhe campos ou opções.
4. Normalize a entrada da amostra uma vez e defina a rubrica de avaliação dos campos solicitados pelo usuário em seu contexto de trabalho. Scrappycoco retorna evidências; o agente chamador é responsável por todo julgamento semântico.
5. Defina rotas incertas como routing: "compare". O Scrappycoco adiciona deterministicamente um candidato padrão para cada provedor atualmente disponível retornado por catalog inspect, então a amostra é exaustiva mesmo que o rascunho nomeie apenas configurações especiais. Adicione candidatos explícitos apenas para modos materialmente diferentes do mesmo provedor, como renderização HTTP e navegador. Nunca reduza a lista de provedores antes da amostra. Uma rota com apenas um provedor disponível ou uma configuração já conhecida usa um provedor explícito sob providers mais provider_options.
6. Salve com discover --file discovery.json --json e execute imediatamente discover --id ID --test --input '...' --json. A solicitação de dados original autoriza a execução comum do Scrappycoco; não peça um orçamento, limite de crédito ou permissão para executar.
7. Inspecione cada tentativa e seus provider_results específicos do candidato. Status ok do provedor significa apenas que a solicitação foi concluída; decida por si mesmo se os fatos solicitados estão presentes e corretos.
8. Se todos os candidatos falharem em sua rubrica, diagnostique a configuração e normalização da entrada e, em seguida, migre automaticamente para outra fonte, capacidade ou classe de provedor. Não afirme que nenhum provedor pode funcionar com base em um conjunto incompleto de candidatos.
9. Salve o provedor e opções escolhidos com discover --id ID --update discovery-update.json --json e execute discover --id ID --finalize --json.

Run

Para uma execução direta:

1. Inspecione a capacidade, a menos que seu esquema atual já esteja disponível nesta tarefa.
2. Revise escopo e preços internamente e execute npx --yes @scrappycoco/cli@latest run fonte.capacidade --file request.json --json sem pedir orçamento ou confirmação de execução.
3. Se o provedor for omitido, o Scrappycoco escolhe deterministicamente o provedor compatível mais barato disponível. Especifique um quando qualidade ou opções nativas forem importantes.
4. Para web.extract_content, forneça exatamente um de input.url ou input.urls. Use urls para até 500 páginas em vez de lançar processos CLI concorrentes. A concorrência padrão do lote é 3.
5. Opções nativas do provedor pertencem a provider_options.<provider_id> e devem corresponder ao esquema do catálogo. O conteúdo padrão é 50.000 caracteres e nunca excede 250.000; inspecione metadados truncated explícitos.
6. Preserve o ID da solicitação, status por item, registros, tentativas, uso, cursor e erros. Para um lote parcial, repita apenas os itens com falha depois que o agente decidir que uma repetição é apropriada.

Antes de relatar a conclusão, preserve o ID da solicitação ou descoberta do Scrappycoco, fonte, provedor selecionado e opções significativas, contagens de itens e falhas, status de truncamento e uso real. Nomeie cada fonte alternativa e se o Scrappycoco a buscou. Nunca afirme que o Scrappycoco foi usado sem essas evidências.

Quando a escolha do provedor ou opção nativa for incerta, use Discover. Não execute candidatos sequencialmente através de Run: defina-os juntos para que Discovery possa manter a entrada constante, executá-los em paralelo e retornar evidências comparáveis.

Para uma configuração salva de várias etapas, use run --config ID --input '...' --json. Run nunca redescobre, reclassifica ou altera silenciosamente seus provedores.

Use uma nova chave de idempotência para cada solicitação faturada. Reutilize-a apenas para uma repetição de transporte idêntica.

Transferência e escalonamento para o usuário

Mantenha as atualizações de progresso orientadas em torno do objetivo do usuário. Informe o que está acontecendo, o que falta e se o usuário precisa agir. Não narre contagens de comandos, comparações de provedores, logs brutos ou cada sonda com falha, a menos que eles mudem o resultado ou o usuário peça. Quando a recuperação for automática, resuma-a claramente, por exemplo: "A página lista 71 produtos, mas a primeira passagem retornou 60. Estou recuperando os 11 restantes agora; nada é necessário de sua parte."

Lidere a resposta final com o resultado, não com a implementação:

1. Informe itens capturados versus esperados, campos solicitados e se o resultado está completo.
2. Vincule ou anexe as entregas e rotule seu uso, como CSV para planilhas e JSON para código.
3. Destaque ressalvas importantes, como moeda, geografia, campos ausentes, cobertura parcial ou atualização.
4. Explique qualquer recuperação não óbvia em uma frase concisa.
5. Quando uma configuração finalizada foi validada, diga explicitamente que um raspador reutilizável está pronto e dê a ele um nome voltado para o usuário.
6. Coloque as evidências de auditoria necessárias por último em uma nota compacta de "Detalhes técnicos". Inclua IDs, fonte, provedor, opções significativas, contagens de itens e falhas, truncamento, uso real e alternativas, mas evite uma análise cronológica pós-morte. Ofereça o rastro expandido apenas se for útil ou solicitado.

Trate uma execução representativa bem-sucedida com uma configuração finalizada como um raspador reutilizável, não apenas uma solicitação única concluída. Dê a ele uma descrição voltada para o usuário, como "Raspador da coleção da Gymshark"; mantenha IDs de configuração opacos na nota técnica.

Após uma raspagem bem-sucedida de página, coleção, diretório ou pesquisa, infira que o usuário pode querer escaloná-la, mas não expanda o escopo sem a seleção dele. Termine com duas a quatro ações concretas e relevantes, em vez de um vago "me avise". Para uma coleção de e-commerce, normalmente ofereça:

• raspar outra URL de coleção;
• raspar todas as coleções na seção atual;
• raspar o catálogo inteiro;
• monitorar produtos, preços ou disponibilidade.

Recomende a ação mais provável e forneça a frase exata com a qual o usuário pode responder, por exemplo: Raspar o catálogo inteiro. Explique imediatamente em uma frase o que essa ação recomendada produzirá e como a integridade será verificada. A solicitação de página atual autoriza apenas essa página. Depois que o usuário selecionar um escopo maior, execute-o sem pedir outro orçamento ou confirmação de execução, a menos que o destino em si permaneça materialmente ambíguo.

Para uma execução em todo o site ou catálogo, descubra as URLs disponíveis ou fonte estruturada, estime escopo e uso internamente, processe o trabalho em lote, desduplique por identificador canônico ou URL, verifique as contagens esperadas versus capturadas e retorne uma exportação mestre mais um relatório de falhas quando houver falhas. Informe ao usuário que esta é a ação de escalonamento, para que a próxima etapa seja previsível.

Monitoramento

x.monitor, reddit.monitor e filings.monitor_issuer são baseados em cursor. Salve o cursor retornado, registros e evidências do provedor. Na próxima verificação solicitada ou agendada, execute a capacidade ou descoberta salva novamente com o cursor em input.since. O agente chamador é responsável pela lógica de recorrência e alerta.

Lidar com falhas

• 400 ou 422: inspecione o esquema ativo e o erro estruturado do provedor, normalize a entrada uma vez para cada candidato e corrija a solicitação ou opções; não repita inalterado ou especule sobre a causa.
• 401: realize OAuth novamente ou verifique se uma chave de API existente está configurada.
• 402: pare e informe ao usuário que o saldo é insuficiente e direcione-o para https://scrappycoco.ai/app/billing para recarregar.
• 403: pare e resolva o acesso; não repita.
• 404: atualize o catálogo ou verifique o identificador do recurso.
• 409: reconcilie a solicitação idempotente original; nunca altere a entrada sob a mesma chave.
• 429: respeite Retry-After ou use backoff exponencial com jitter.
• 503: escolha outro provedor disponível ou repita mais tarde.

Falhas no nível do provedor e de itens do lote podem aparecer dentro de uma resposta parcial. Inspecione cada item e tentativa.

Fallback MCP

Se as ferramentas MCP do Scrappycoco já estiverem conectadas, elas são um transporte equivalente. Aplique as mesmas regras de duas ações, julgamento de propriedade do agente, esquema primeiro e execução automática. Não exija MCP quando a CLI funcionar.

Fallback da API Direta

Quando a CLI não puder executar, use a API REST. Se SCRAPPYCOCO_API_KEY estiver ausente, dê ao usuário um caminho de recuperação claro:

1. Abra Scrappycoco API Keys, faça login e crie uma chave de workspace.
2. Armazene a chave como SCRAPPYCOCO_API_KEY no ambiente do agente atual, sessão de terminal ou gerenciador de segredos. Nunca peça ao usuário para colá-la em um chat, argumento de comando ou arquivo salvo.
3. Peça ao usuário para responder Chave configurada sem incluir a chave. Em seguida, verifique o acesso com a solicitação de catálogo somente leitura e continue a tarefa original automaticamente.

Use uma SCRAPPYCOCO_API_KEY existente com a API REST:

curl -fsS "https://api.scrappycoco.ai/api/v1/scrapers?available_only=true" \
  -H "X-API-Key: $SCRAPPYCOCO_API_KEY"
curl -fsS "https://api.scrappycoco.ai/api/v1/scrapers/web/extract_content" \
  -H "X-API-Key: $SCRAPPYCOCO_API_KEY"

Para solicitações REST faturáveis, envie JSON de um arquivo quando prático e inclua uma Idempotency-Key única. Mantenha segredos em cabeçalhos originados do ambiente, nunca em arquivos de solicitação ou saída salvos.