flibusta-api/README.md

> **Disclaimer**: This package is only created as an example of a search tool for Flibusta. If you like to read books - buy them legally.

# Unofficial Flibusta API

> **Disclaimer**: This package is only created as an example of a search tool for Flibusta. If you like to read books - buy them legally.

A TypeScript/JavaScript library for searching and downloading books from Flibusta. This unofficial API provides programmatic access to search functionality and book metadata.

## Features

- 📚 Search books by title and content
- 👤 Search books by author
- 📖 Get detailed book information including genres and descriptions
- ⬇️ Download books in various formats (MOBI, EPUB, FB2, PDF)
- 🔗 Generate download and send links
- 📝 TypeScript support with full type definitions
- 🧪 Comprehensive test coverage

## Installation

```bash
npm install flibusta-api
```

## Usage

### Basic Book Search

```typescript
import { searchBooks } from 'flibusta-api';

// Search for books by title or content
const books = await searchBooks('Harry Potter', 10);
console.log(books);
// Returns: Book[]
```

### Search by Author

```typescript
import { searchByAuthor } from 'flibusta-api';

// Search for books by a specific author
const books = await searchByAuthor('Tolkien', 5);
console.log(books);
// Returns: Book[]
```

### Get Book Information

```typescript
import { getBookInfo } from 'flibusta-api';

// Get detailed information about a specific book
const bookInfo = await getBookInfo(123456);
console.log(bookInfo);
// Returns: BookInfo | undefined
```

### Download Books

```typescript
import { downBook, getUrl } from 'flibusta-api';

// Download a book file
const bookFile = await downBook('123456', 'epub');
console.log(bookFile.fileName);

// Or just get the download URL
const downloadUrl = getUrl('123456', 'mobi');
console.log(downloadUrl);
```

## API Reference

### Types

#### `Book`
```typescript
type Book = {
  id: number;
  title: string;
  author: string;
  link: string;
  sendLink: string;
};
```

#### `BookInfo`
```typescript
type BookInfo = {
  id: number;
  title: string;
  author: string;
  genres: BookGenres[];
  description?: string;
};
```

#### `BookFile`
```typescript
interface BookFile {
  id: string;
  file: Buffer;
  fileName: string;
  filePath?: string;
}
```

#### `BookFormat`
```typescript
type BookFormat = 'mobi' | 'fb2' | 'pdf' | 'epub';
```

### Methods

#### `searchBooks(text: string, limit?: number): Promise<Book[]>`
Search for books by title or content.

- `text` - Search query
- `limit` - Maximum number of results (default: 20)

#### `searchByAuthor(text: string, limit?: number): Promise<Book[]>`
Search for books by author name.

- `text` - Author name to search for
- `limit` - Maximum number of results (default: 10)

#### `getBookInfo(id: number): Promise<BookInfo | undefined>`
Get detailed information about a specific book.

- `id` - Book ID

#### `downBook(id: string, format?: BookFormat): Promise<BookFile>`
Download a book file.

- `id` - Book ID
- `format` - File format (default: 'mobi')

#### `getUrl(id: string, format?: BookFormat): string`
Generate download URL for a book.

- `id` - Book ID
- `format` - File format (default: 'mobi')

## Examples

### Complete Example

```typescript
import { 
  searchBooks, 
  searchByAuthor, 
  getBookInfo, 
  downBook 
} from 'flibusta-api';

async function example() {
  try {
    // Search for books
    const books = await searchBooks('fantasy', 5);
    
    if (books.length > 0) {
      const book = books[0];
      console.log(`Found: ${book.title} by ${book.author}`);
      
      // Get detailed info
      const info = await getBookInfo(book.id);
      if (info) {
        console.log(`Description: ${info.description}`);
        console.log(`Genres: ${info.genres.map(g => g.title).join(', ')}`);
      }
      
      // Download the book
      const file = await downBook(book.id.toString(), 'epub');
      console.log(`Downloaded: ${file.fileName}`);
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

example();
```

### Error Handling

```typescript
import { downBook } from 'flibusta-api';

try {
  const file = await downBook('invalid-id', 'epub');
} catch (error) {
  if (error.message.includes('unavailable')) {
    console.log('Book is not available for download');
  } else {
    console.error('Unexpected error:', error);
  }
}
```

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

### Linting

```bash
npm run lint
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Legal Notice

This library is for educational and research purposes only. Please respect copyright laws and support authors by purchasing books legally. The authors of this library are not responsible for any misuse.

## License

[MIT](https://github.com/NicomUA/flibusta-api/blob/master/LICENSE.md) © [Mykyta Matsapura](https://github.com/NicomUA)