Nyaa.si Scraper/API Wrapper

Um wrapper/scraper robusto e não-oficial para o site nyaa.si, desenvolvido em TypeScript.

� Documentação

• 🚀 Getting Started - Comece aqui!
• 📚 API Reference - Documentação completa da API
• ⚡ Quick Start - Guia rápido de uso
• 🧪 Testing Guide - Como testar
• 🤝 Contributing - Como contribuir
• 📝 Changelog - Histórico de mudanças
• 🔒 Security - Política de segurança
• 📊 Summary - Resumo do projeto

�🚀 Funcionalidades

Core Features

• ✅ Busca de torrents com filtros avançados
• ✅ Obtenção de detalhes completos de torrents
• ✅ Busca por usuário
• ✅ Listagem de torrents mais recentes
• ✅ Suporte a paginação
• ✅ Parsing robusto de HTML com Cheerio
• ✅ Tratamento de erros completo
• ✅ TypeScript com tipagem completa
• ✅ Suporte a categorias do Nyaa
• ✅ Identificação de uploads confiáveis (trusted)
• ✅ Links de torrent e magnet

🆕 Advanced Features

• ✨ Retry automático com exponential backoff
• ✨ Cache em memória para reduzir requisições
• ✨ Download de arquivos .torrent
• ✨ Paginação automática (buscar todas as páginas)
• ✨ Validação de parâmetros de entrada
• ✨ Estatísticas de requisições (total, cache hit rate, retries, etc.)
• ✨ Configuração flexível (timeout, retry, cache TTL)

� Getting Started

Para começar rapidamente, consulte o Guia de Início.

�📦 Instalação

npm install

🔧 Uso

Inicialização Básica

import { NyaaScraper, NyaaCategory } from '@kitsuneislife/nyaa';

// Uso básico
const scraper = new NyaaScraper();

// Com configuração avançada
const scraper = new NyaaScraper({
  timeout: 30000,
  retry: {
    maxRetries: 5,
    initialDelay: 1000,
    maxDelay: 10000,
    backoffMultiplier: 2
  },
  enableCache: true,
  cacheTTL: 300000  // 5 minutos
});

Busca Básica

// Buscar torrents
const results = await scraper.search({
  query: 'one piece',
  category: NyaaCategory.ANIME_ENGLISH,
  filter: 'trusted-only',
  page: 1,
});

console.log(results.torrents);
console.log(results.hasNextPage);

Busca Avançada

// Busca com todos os filtros
const results = await scraper.search({
  query: 'anime',
  category: NyaaCategory.ANIME_ENGLISH,
  filter: 'trusted-only', // 'no-filter' | 'no-remakes' | 'trusted-only'
  page: 1,
  sortBy: 'seeders', // 'id' | 'size' | 'seeders' | 'leechers' | 'downloads'
  order: 'desc', // 'asc' | 'desc'
});

🆕 Buscar Todas as Páginas

// Buscar automaticamente múltiplas páginas
const allTorrents = await scraper.searchAllPages({
  query: 'one piece',
  filter: 'trusted-only'
}, 5); // Máximo de 5 páginas

console.log(`Encontrados ${allTorrents.length} torrents`);

🆕 Download de Arquivo .torrent

import fs from 'fs/promises';

// Baixar arquivo .torrent
const torrentData = await scraper.downloadTorrent('1234567');
await fs.writeFile('myfile.torrent', torrentData);
console.log('Arquivo .torrent salvo!');

🆕 Estatísticas de Uso

// Fazer algumas requisições
await scraper.search({ query: 'test' });
await scraper.search({ query: 'test' }); // Virá do cache

// Obter estatísticas
const stats = scraper.getStats();
console.log(`Total de requisições: ${stats.totalRequests}`);
console.log(`Respostas cacheadas: ${stats.cachedResponses}`);
console.log(`Taxa de cache: ${(stats.cachedResponses / (stats.totalRequests + stats.cachedResponses) * 100).toFixed(2)}%`);

// Limpar cache e estatísticas
scraper.clearCache();
scraper.resetStats();

Obter Detalhes de um Torrent

const details = await scraper.getTorrent('1234567');

console.log(details.title);
console.log(details.description);
console.log(details.files); // Lista de arquivos
console.log(details.infoHash);
console.log(details.magnetLink);

Buscar por Usuário

const userTorrents = await scraper.searchByUser('subsplease', {
  page: 1,
  sortBy: 'id',
  order: 'desc',
});

Obter Torrents Mais Recentes

const latest = await scraper.getLatest(1);

📋 API

NyaaScraper

Métodos

• search(options: SearchOptions): Promise<SearchResult>

  • Busca torrents com filtros opcionais

• getTorrent(id: string): Promise<NyaaTorrentDetails>

  • Obtém informações detalhadas de um torrent específico

• getLatest(page?: number): Promise<SearchResult>

  • Obtém os torrents mais recentes

• searchByUser(username: string, options?: SearchOptions): Promise<SearchResult>

  • Busca torrents de um usuário específico

Tipos

SearchOptions

interface SearchOptions {
  query?: string;
  category?: string;
  filter?: 'no-filter' | 'no-remakes' | 'trusted-only';
  page?: number;
  sortBy?: 'id' | 'size' | 'comments' | 'seeders' | 'leechers' | 'downloads';
  order?: 'asc' | 'desc';
  user?: string;
}

NyaaTorrent

interface NyaaTorrent {
  id: string;
  title: string;
  category: string;
  torrentLink: string;
  magnetLink: string;
  size: string;
  date: string;
  seeders: number;
  leechers: number;
  downloads: number;
  link: string;
  uploader?: string;
  isTrusted?: boolean;
  isRemake?: boolean;
}

NyaaCategory

enum NyaaCategory {
  ALL = '0_0',
  ANIME = '1_0',
  ANIME_AMV = '1_1',
  ANIME_ENGLISH = '1_2',
  ANIME_NON_ENGLISH = '1_3',
  ANIME_RAW = '1_4',
  AUDIO = '2_0',
  AUDIO_LOSSLESS = '2_1',
  AUDIO_LOSSY = '2_2',
  LITERATURE = '3_0',
  // ... e mais
}

🧪 Testes

Executar Testes

# Executar todos os testes
npm test

# Executar testes com coverage
npm run test:coverage

# Executar testes em watch mode
npm run test:watch

# Executar testes de integração (cuidado com rate limiting!)
INTEGRATION_TESTS=true npm test

Cobertura de Testes

Este projeto mantém alta cobertura de testes:

• ✅ Testes unitários para todas as funções principais
• ✅ Testes de integração (opcionais)
• ✅ Testes de parsing HTML
• ✅ Testes de tratamento de erros

🧪 Executar Exemplos

npm run example

🏗️ Build

npm run build

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, leia CONTRIBUTING.md para detalhes sobre nosso código de conduta e processo de submissão de pull requests.

Desenvolvimento

# Instalar dependências
npm install

# Rodar em modo dev
npm run dev

# Lint
npm run lint

# Format
npm run format

⚠️ Aviso Legal

Este é um projeto não-oficial e não tem afiliação com nyaa.si. Use de forma responsável e respeite os termos de serviço do site.

📄 Licença

MIT

🛠️ Tecnologias

• TypeScript
• Axios (HTTP client)
• Cheerio (HTML parsing)
• Node.js