Tokybook API

A Dart package for accessing Tokybook audiobooks. Search and retrieve audiobooks with ease.

Features

✨ Simple API - Clean, intuitive interface for searching audiobooks
🔍 Powerful Search - Search by title with pagination support
📂 Category Browse - Browse audiobooks by category
📖 Detailed Metadata - Get comprehensive book information including descriptions and download links
🎧 Download Support - Direct access to audiobook files
🛡️ Error Handling - Comprehensive exception handling with specific error types
🚀 Lightweight - Minimal dependencies, maximum performance

Getting Started

Add this package to your pubspec.yaml:

dependencies:
  tokybook: ^0.0.1

Then run:

dart pub get

Usage

Basic Search

import 'package:tokybook/tokybook.dart';

void main() async {
  final api = TokybookApi();

  try {
    // Search for audiobooks
    final results = await api.searchTitles(
      query: 'sherlock holmes',
      limit: 12,
    );

    for (final book in results) {
      print('📚 ${book.title}');
      print('   Cover: ${book.coverUrl}');
      print('   Slug: ${book.dynamicSlugId}');
    }
  } catch (e) {
    print('Error: $e');
  }
}

Browse by Category

import 'package:tokybook/tokybook.dart';

void main() async {
  final api = TokybookApi();

  try {
    // Browse audiobooks by category/type filter
    final results = await api.getByCategory(
      category: 'fiction',
      limit: 12,
    );

    for (final book in results) {
      print('📚 ${book.title}');
    }
  } catch (e) {
    print('Error: $e');
  }
}

Get Audiobook Details

import 'package:tokybook/tokybook.dart';

void main() async {
  final api = TokybookApi();

  try {
    // Get detailed information about an audiobook using dynamicSlugId
    final book = await api.getInfo('a-very-stalker-christmas-43fa42');

    print('📚 ${book.title}');
    print('🆔 Audio Book ID: ${book.audioBookId}');
    print('👤 Author: ${book.author}');
    print('🎙️ Narrator: ${book.narrator}');
    print('📝 Description: ${book.description}');
    print('⏱️ Duration: ${book.duration}');
    
    if (book.downloadLinks != null) {
      print('🎧 Download Links:');
      for (final link in book.downloadLinks!) {
        print('   $link');
      }
    }
  } catch (e) {
    print('Error: $e');
  }
}

With Pagination

import 'package:tokybook/tokybook.dart';

void main() async {
  final api = TokybookApi();

  // Fetch first page (offset 0)
  final page1 = await api.searchTitles(
    query: 'adventure',
    offset: 0,
    limit: 12,
  );

  // Fetch second page (offset 12)
  final page2 = await api.searchTitles(
    query: 'adventure',
    offset: 12,
    limit: 12,
  );
}

Error Handling

The package provides specific exception types for different error scenarios:

import 'package:tokybook/tokybook.dart';

void main() async {
  final api = TokybookApi();

  try {
    final results = await api.searchTitles(query: 'test');
  } on TokybookNotFoundException catch (e) {
    print('Not found: ${e.message}');
  } on TokybookApiException catch (e) {
    print('API error: ${e.message}');
  } on TokybookParseException catch (e) {
    print('Parse error: ${e.message}');
  } on TokybookException catch (e) {
    print('General error: ${e.message}');
  }
}

Available Exception Types

Exception	Description
TokybookException	Base exception class
TokybookApiException	HTTP/API errors
TokybookNotFoundException	Resource not found (404)
TokybookParseException	Response parsing errors
TokybookRateLimitException	Rate limiting errors
TokybookServerException	Server errors

TokybookItem Properties

Property	Type	Description
id	String	Unique UUID identifier
title	String	Audiobook title
audioBookId	String?	External ID (Amazon ASIN, LibriVox ID)
dynamicSlugId	String?	URL slug for fetching details
author	String?	Author name
narrator	String?	Narrator name
description	String?	Book description
coverUrl	String?	Cover image URL
duration	String?	Total duration
category	String?	Book category
language	String?	Language
releaseDate	String?	Release date
timestamp	int?	Unix timestamp in milliseconds
downloadLinks	List<String>?	Audio file URLs

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.