wayback_client 0.1.0

A Dart client for the Internet Archive's Wayback Machine Save Page Now API. Easily archive web pages and check if snapshots are cached.

wayback_client

A Dart client for the Internet Archive's Wayback Machine Save Page Now API. Easily archive web pages and check if snapshots are cached.

Features

• Dart 3.9+ compatible: Uses records, sealed classes, and modern null safety.
• Automatic retry logic: Handles transient failures with configurable retry attempts.
• Cached detection: Automatically detects if a snapshot is already cached.
• Customizable: Configure max retries, timeouts, and user agent.
• Built on Dio: Leverages the powerful Dio HTTP client for reliability.

Installation

Add the dependency to your pubspec.yaml:

dependencies:
  wayback_client: ^0.1.0

Then import the package:

import 'package:wayback_client/wayback_client.dart';

Quick Start

The simplest way to archive a URL:

import 'package:wayback_client/wayback_client.dart';

Future<void> main() async {
  final client = WaybackClient();

  try {
    final (archiveUrl, isCached) = await client.saveUrl('https://example.com');

    print('Archived at: $archiveUrl');
    print('Was cached: $isCached');
  } catch (e) {
    print('Error: $e');
  }
}

Usage Examples

Basic Usage

Create a client with default settings:

final client = WaybackClient();
final (archiveUrl, isCached) = await client.saveUrl('https://example.com');

Custom Configuration

Configure timeouts, retries, and user agent:

import 'package:dio/dio.dart';
import 'package:wayback_client/wayback_client.dart';

final dio = Dio(
  BaseOptions(
    connectTimeout: const Duration(seconds: 30),
    receiveTimeout: const Duration(seconds: 30),
  ),
);

final client = WaybackClient(
  dio: dio,
  maxRetries: 5,
  userAgent: 'My App/1.0',
);

final (archiveUrl, isCached) = await client.saveUrl('https://example.com');

Handling Errors

The package provides specific exceptions for error handling:

import 'package:wayback_client/wayback_client.dart';

try {
  final (archiveUrl, isCached) = await client.saveUrl(url);
} on MaxRetriesExceededException catch (e) {
  // Tried max times but still failed
  print('Max retries exceeded: $e');
} on WaybackApiException catch (e) {
  // API-specific error (e.g., empty URL)
  print('API error: $e');
} on WaybackException catch (e) {
  // Generic Wayback error
  print('Wayback error: $e');
}

API Reference

WaybackClient

The main class to interact with the Wayback Machine API.

Constructor

WaybackClient({
  Dio? dio,
  int maxRetries = 8,
  String userAgent = defaultUserAgent,
})

Parameters:

• dio - Optional custom Dio client. If not provided, a default one is created.
• maxRetries - Maximum number of retry attempts (default: 8).
• userAgent - Custom user agent string.

Methods

Future<(String, bool)> saveUrl(String url)

Archives a URL on the Wayback Machine and returns a record containing:

• archiveUrl (String) - The URL of the archived snapshot.
• isCached (bool) - Whether the snapshot was already cached.

Throws:

• WaybackApiException - If the URL is empty.
• MaxRetriesExceededException - If the request fails after all retries.

Exceptions

WaybackException

Base exception for all Wayback Machine related errors.

MaxRetriesExceededException

Thrown when the maximum number of retries is exceeded without a successful response.

WaybackApiException

Thrown for API-specific errors, such as when an empty URL is provided.

How It Works

1. Request: Sends a request to https://web.archive.org/save/{url} with your user agent.
2. Response Parsing: Extracts the archive URL from response headers or HTML body.
3. Retry Logic: If the initial request fails, automatically retries with exponential backoff (5-10 seconds).
4. Cache Detection: Analyzes the snapshot timestamp to determine if it was already cached.

Retry Strategy

The client uses an intelligent retry mechanism:

• Retries on transient failures (network issues, temporary API unavailability).
• Uses exponential backoff with 5-second intervals (increased to 10 seconds every 3 retries).
• Configurable via the maxRetries parameter.

Requirements

• Dart 3.9 or higher
• Flutter 3.13 or higher (if used in a Flutter app)

License

MIT