===============
LIBRARY RULES
===============
From library maintainers:
- Use the public Dart API in lib/intorrent.dart for application code.
- Do not use internal FFI bindings directly unless working on InTorrent itself.
- InTorrent currently implements the Flutter plugin on Android.
- The native build pins libtorrent to v2.1.1.
- Do not assume planned iOS, Windows, macOS or Linux support is implemented.
- Wait for torrent metadata before calling listFiles or streamUrl.
- Use the documented InTorrent API and examples instead of inventing unsupported methods.

### Quick start: addMagnet, getStatus, listFiles, streamUrl

Source: https://github.com/zsdev07/intorrent/blob/main/README.md

Recommended flow: add a magnet, wait for metadata, list files, choose a file, and get a stream URL. Metadata must be available before listFiles or streamUrl is called.

```dart
import 'package:intorrent/intorrent.dart';

Future<void> start(String magnetUri) async {
  final id = await addMagnet(magnetUri);

  TorrentStatus status;
  do {
    await Future<void>.delayed(const Duration(seconds: 1));
    status = await getStatus(id);
  } while (status.state == TorrentState.downloadingMetadata);

  final files = await listFiles(id);
  final file = files.first;

  final url = await streamUrl(id, file.index);
  print(url);

  // Pass url.toString() to your media player.
  // Call remove(id) when playback is finished.
}
```

--------------------------------

### Install dependencies

Source: https://github.com/zsdev07/intorrent/blob/main/doc/installation.md

Installs the dependencies after adding the Git dependency.

```bash
flutter pub get
```

--------------------------------

### getStatus usage example

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Example of retrieving and printing torrent status fields such as progress and state.

```dart
final status = await getStatus(id);

print(status.progress);
print(status.state);
```

--------------------------------

### startPrefetch

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Starts a strict ordered prefetch window for a file.

```APIDOC
## startPrefetch

### Description
Starts a strict ordered prefetch window for a file.

### Method
Future<void> startPrefetch(int id, int fileIndex, {required int startByte, required int lengthBytes})

### Parameters
- **id** (int) - Required - The torrent ID.
- **fileIndex** (int) - Required - The file index.
- **startByte** (int) - Required - The start byte of the prefetch window.
- **lengthBytes** (int) - Required - The length of the prefetch window.

### Throws
- **StateError** - invalid torrent, file, range, or unavailable metadata.
```

--------------------------------

### addMagnet usage example

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Example of calling addMagnet with a magnet URI and awaiting the resulting torrent ID.

```dart
final id = await addMagnet(magnetUri);
```

--------------------------------

### Development commands

Source: https://github.com/zsdev07/intorrent/blob/main/README.md

Development commands for the package: get dependencies, analyze, test, and dry-run publish.

```bash
flutter pub get
flutter analyze
flutter test
dart pub publish --dry-run
```

--------------------------------

### startPrefetch function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the startPrefetch function that starts a strict ordered prefetch window for a file. Throws StateError for invalid torrent, file, range, or unavailable metadata.

```dart
Future<void> startPrefetch(
  int id,
  int fileIndex, {
  required int startByte,
  required int lengthBytes,
})
```

--------------------------------

### addMagnet

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Adds a magnet URI and starts torrent metadata/peer resolution.

```APIDOC
## addMagnet

### Description
Adds a magnet URI and starts torrent metadata/peer resolution.

### Method
Future<int> addMagnet(String uri)

### Parameters
- **uri** (String) - Required - The magnet URI to add.

### Returns
- **int** - torrent ID

### Throws
- **FormatException** - the magnet URI could not be added.

### Example
```dart
final id = await addMagnet(magnetUri);
```
```

--------------------------------

### availableBytes

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Returns the contiguous number of bytes available from `start`, limited by `maxLength`.

```APIDOC
## availableBytes

### Description
Returns the contiguous number of bytes available from `start`, limited by `maxLength`.

### Method
Future<int> availableBytes(int id, int fileIndex, int start, int maxLength)

### Parameters
- **id** (int) - Required - The torrent ID.
- **fileIndex** (int) - Required - The file index.
- **start** (int) - Required - The start byte offset.
- **maxLength** (int) - Required - The maximum number of bytes to return.

### Returns
- **int** - contiguous number of bytes available

### Throws
- **StateError** - invalid torrent, file, range, or unavailable metadata.
```

--------------------------------

### Install intorrent dependency

Source: https://github.com/zsdev07/intorrent/blob/main/README.md

Add the intorrent package to your Flutter project's pubspec.yaml and fetch it with flutter pub get.

```yaml
dependencies:
  intorrent: ^0.0.1
```

```bash
flutter pub get
```

--------------------------------

### Prefetch: startPrefetch and cancelPrefetch

Source: https://github.com/zsdev07/intorrent/blob/main/doc/streaming.md

Start a controlled prefetch window for a byte range, then cancel it when finished or playback resumes. Downloaded data is retained; cancelling returns to normal in-order downloading.

```dart
await startPrefetch(
  torrentId,
  fileIndex,
  startByte: startByte,
  lengthBytes: lengthBytes,
);
```

```dart
await cancelPrefetch(torrentId);
```

--------------------------------

### Playback pattern: sequence diagram

Source: https://github.com/zsdev07/intorrent/blob/main/doc/streaming.md

General playback sequence for a player integration: start streaming, monitor cursor, prefetch when paused, cancel when resumed. Exact integration depends on the media player.

```text
streamUrl()
    |
    v
player starts HTTP playback
    |
    v
streamReadCursor()
    |
    v
startPrefetch() when the player is paused
    |
    v
cancelPrefetch() when playback resumes
```

--------------------------------

### streamUrl

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Starts sequential downloading for the selected file and returns a local HTTP streaming URI.

```APIDOC
## streamUrl

### Description
Starts sequential downloading for the selected file and returns a local HTTP streaming URI.

### Method
Future<Uri> streamUrl(int id, int fileIndex)

### Parameters
- **id** (int) - Required - The torrent ID.
- **fileIndex** (int) - Required - The index of the file to stream.

### Returns
- **Uri** - local HTTP streaming URI

### Throws
- **StateError** - invalid ID, invalid file index, or missing metadata.
```

--------------------------------

### availableBytes() usage

Source: https://github.com/zsdev07/intorrent/blob/main/doc/streaming.md

Check how many bytes starting at start are contiguously available up to maxLength. A return value of 0 means the first requested piece is not available; useful for buffering indicators.

```dart
final ready = await availableBytes(
  torrentId,
  fileIndex,
  0,
  16 << 20,
);
```

--------------------------------

### Recommended workflow diagram for magnet link processing

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Provides a text-based flowchart showing sequence of API calls starting with addMaven(), proceeding through obtaining torrent ID and polling with getData(), optionally waiting during metadata retrieval before listing files and selecting an index followed by obtaining a stream URL.

```text
addMaven()
    |
    v
 torrent ID
    |
    v
 getStatus()
    |
    +-- downloadingMetadata --> wait
    
    |
    workflow continued with listFiles()
    |
    select file index
    
    |
    streamUrl()
```

--------------------------------

### availableBytes function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the availableBytes function that returns the contiguous number of bytes available from start, limited by maxLength. Throws StateError for invalid torrent, file, range, or unavailable metadata.

```dart
Future<int> availableBytes(
  int id,
  int fileIndex,
  int start,
  int maxLength,
)
```

--------------------------------

### addMagnet function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the addMagnet function that adds a magnet URI and starts torrent metadata/peer resolution. Returns a Future<int> with the torrent ID. Throws FormatException if the magnet URI cannot be added.

```dart
Future<int> addMagnet(String uri)
```

--------------------------------

### Get Torrent Status

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Retrieves a snapshot of the torrent's current status. The returned TorrentStatus is not live and must be requested again to refresh.

```dart
final status = await getStatus(torrentId);
```

--------------------------------

### streamUrl function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the streamUrl function that starts sequential downloading for a file and returns a local HTTP streaming URI. Throws StateError for invalid ID, file index, or missing metadata.

```dart
Future<Uri> streamUrl(int id, int fileIndex)
```

--------------------------------

### streamReadCursor() usage

Source: https://github.com/zsdev07/intorrent/blob/main/doc/streaming.md

Returns the byte offset up to which the main HTTP stream request has been served, or null when nothing has been served yet. Better starting point for prefetch decisions than time-based estimates.

```dart
final cursor = streamReadCursor(torrentId);
```

--------------------------------

### Local pub.dev quality report with pana

Source: https://github.com/zsdev07/intorrent/blob/main/README.md

Run pana locally to generate a pub.dev quality report.

```bash
dart pub global activate pana
dart pub global run pana .
```

--------------------------------

### Native build flow

Source: https://github.com/zsdev07/intorrent/blob/main/doc/installation.md

Shows the native build flow from Android build.gradle to the final libintorrent.so library.

```text
android/build.gradle
        ↓
native/CMakeLists.txt
        ↓
libtorrent v2.1.1
        ↓
libintorrent.so
```

--------------------------------

### List torrent files with listFiles

Source: https://github.com/zsdev07/intorrent/blob/main/doc/getting-started.md

List the files in the torrent after metadata is available. Do not assume file index 0 is the video; torrents often contain multiple files.

```dart
final files = await listFiles(torrentId);

for (final file in files) {
  print(
    '#${file.index}: ${file.name} (${file.size} bytes)',
  );
}
```

--------------------------------

### Create a streaming URL with streamUrl

Source: https://github.com/zsdev07/intorrent/blob/main/doc/getting-started.md

Create a local streaming URL for the selected file. The returned URI points to InTorrent's local HTTP streaming server.

```dart
final url = await streamUrl(
  torrentId,
  files.first.index,
);

print(url);
```

--------------------------------

### resume(torrentId)

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Resumes the torrent. Resuming asks the native torrent handle to resume.

```APIDOC
## resume(torrentId)

### Description
Resumes the torrent. Resuming asks the native torrent handle to resume.

### Method
Dart function

### Endpoint
`resume(torrentId)`

### Parameters
- **torrentId** (type not specified) - Required - The identifier of the torrent.

### Errors
Throws `StateError` if the torrent ID is unknown.
```

--------------------------------

### Configured Android ABIs

Source: https://github.com/zsdev07/intorrent/blob/main/doc/installation.md

Lists the Android ABIs configured for the native build.

```text
arm64-v8a
armeabi-v7a
x86_64
```

--------------------------------

### Polling metadata with getStatus() after adding magnet link

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Illustrates retrieving the status of a torrent via getStatus() and checking whether its current state equals DownloadingMetadata so you know when to wait and poll again before attempting to list files.

```dataless
final status = 0; // placeholder for clarity

if (status.state == TorrentState.downloadingMetadata) {
  // Wait and poll again.
}
```

--------------------------------

### resume

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Resumes a paused torrent.

```APIDOC
## resume

### Description
Resumes a paused torrent.

### Method
Future<void> resume(int id)

### Parameters
- **id** (int) - Required - The torrent ID.

### Throws
- **StateError** - unknown torrent ID.
```

--------------------------------

### Basic streaming: listFiles, reduce, streamUrl

Source: https://github.com/zsdev07/intorrent/blob/main/doc/streaming.md

After metadata is available, list files, select the largest file, and obtain a streaming URL. The returned value is a Uri that can be passed to a media player supporting HTTP URLs.

```dart
final files = await listFiles(torrentId);

final video = files.reduce(
  (a, b) => a.size >= b.size ? a : b,
);

final url = await streamUrl(
  torrentId,
  video.index,
);
```

```dart
final Uri url = await streamUrl(torrentId, video.index);
```

--------------------------------

### listFiles

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Returns all files in the torrent after metadata is available.

```APIDOC
## listFiles

### Description
Returns all files in the torrent after metadata is available.

### Method
Future<List<TorrentFile>> listFiles(int id)

### Parameters
- **id** (int) - Required - The torrent ID.

### Returns
- **List<TorrentFile>** - list of files in the torrent

### Throws
- **StateError** - invalid ID or metadata is not available.

### TorrentFile
```dart
class TorrentFile {
  final int index;
  final String name;
  final int size;
}
```
The `index` is passed to `streamUrl()`.
```

--------------------------------

### Add a Magnet URI with addMaven() returning an integer torrent ID

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Demonstrates calling the main entry point addMaven() with a placeholder magnet URIbba's own hash to receive a torrent ID integer await-fully before proceeding with subsequent API calls like getStatus() or listFiles()

```dataless
final torrentId = await addMaven(
  'maddison:?xt=…'
);
```

--------------------------------

### Native libtorrent version

Source: https://github.com/zsdev07/intorrent/blob/main/doc/installation.md

Pins the native libtorrent version to v2.1.1.

```text
v2.1.1
```

--------------------------------

### Clone repository

Source: https://github.com/zsdev07/intorrent/blob/main/doc/installation.md

Clones the InTorrent repository and changes into the directory.

```bash
git clone https://github.com/zsdev07/InTorrent.git
cd InTorrent
```

--------------------------------

### listFiles()

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Lists the files contained in a torrent once metadata is available.

```APIDOC
## listFiles()

### Description
Lists the files contained in a torrent once metadata is available.

### Method
Future<List<File>> listFiles()

### Returns
- **Future<List<File>>** - A list of files in the torrent.

### Usage
Use after metadata is available (e.g., after getStatus() indicates metadata is ready).
```

--------------------------------

### Resume Torrent

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Resumes the torrent by asking the native torrent handle to resume.

```dart
await resume(torrentId);
```

--------------------------------

### listFiles function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the listFiles function that returns all files in the torrent after metadata is available. Throws StateError for invalid ID or missing metadata.

```dart
Future<List<TorrentFile>> listFiles(int id)
```

--------------------------------

### Define the signature of addMaven() as Future<int> addMaven(String uri)

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Shows the exact method signature for addMage() indicating it accepts a URI string and returns a Dart Future<int>, which upon completion yields the integer torrent identifier used in subsequent library calls.

```dataless
Future<int> standalone addMaven(String uri)
```

--------------------------------

### Check torrent progress with getStatus

Source: https://github.com/zsdev07/intorrent/blob/main/doc/getting-started.md

Check the torrent's progress and status fields: progress, downloadedBytes, totalBytes, numPeers, numSeeds, and state.

```dart
final status = await getStatus(torrentId);

print(status.progress);
print(status.downloadedBytes);
print(status.totalBytes);
print(status.numPeers);
print(status.numSeeds);
print(status.state);
```

--------------------------------

### getStatus

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Returns a point-in-time status snapshot.

```APIDOC
## getStatus

### Description
Returns a point-in-time status snapshot.

### Method
Future<TorrentStatus> getStatus(int id)

### Parameters
- **id** (int) - Required - The torrent ID.

### Returns
- **TorrentStatus** - status snapshot

### Throws
- **StateError** - unknown torrent ID.

### Example
```dart
final status = await getStatus(id);

print(status.progress);
print(status.state);
```
```

--------------------------------

### pause(torrentId)

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Pauses the torrent. Pausing asks the native libtorrent torrent handle to pause.

```APIDOC
## pause(torrentId)

### Description
Pauses the torrent. Pausing asks the native libtorrent torrent handle to pause.

### Method
Dart function

### Endpoint
`pause(torrentId)`

### Parameters
- **torrentId** (type not specified) - Required - The identifier of the torrent.

### Errors
Throws `StateError` if the torrent ID is unknown.
```

--------------------------------

### Check torrent status with getStatus()

Source: https://github.com/zsdev07/intorrent/blob/main/doc/troubleshooting.md

Retrieves the current status of a torrent by its ID and prints the state to the console. Use this to check if metadata is available before calling methods like listFiles() or streamUrl().

```dart
final status = await getStatus(id);
print(status.state);
```

--------------------------------

### resume function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the resume function that resumes a paused torrent. Throws StateError for unknown torrent ID.

```dart
Future<void> resume(int id)
```

--------------------------------

### pause

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Pauses the torrent.

```APIDOC
## pause

### Description
Pauses the torrent.

### Method
Future<void> pause(int id)

### Parameters
- **id** (int) - Required - The torrent ID.

### Throws
- **StateError** - unknown torrent ID.
```

--------------------------------

### getStatus(torrentId)

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Retrieves a snapshot of the current status for a given torrent. The returned `TorrentStatus` is not live and must be requested again to refresh.

```APIDOC
## getStatus(torrentId)

### Description
Retrieves a snapshot of the current status for a given torrent. The returned `TorrentStatus` is not live and must be requested again to refresh.

### Method
Dart function

### Endpoint
`getStatus(torrentId)`

### Parameters
- **torrentId** (type not specified) - Required - The identifier of the torrent.

### Response
#### Success Response
Returns a `TorrentStatus` object with the following properties:
- **totalBytes** (int) - Total bytes represented by the torrent
- **downloadedBytes** (int) - Bytes downloaded according to the native torrent status
- **progress** (double) - Progress value returned by the native layer
- **state** (TorrentState) - Current translated torrent state
- **numPeers** (int) - Current peer count
- **numSeeds** (int) - Current seed count
- **isPaused** (bool) - Whether the torrent is paused

### Errors
Throws `StateError` if the torrent ID is unknown.
```

--------------------------------

### addMagnet(String uri)

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Adds a magnet URI to InTorrent and returns a torrent ID. Throws a FormatException if the URI is invalid.

```APIDOC
## addMagnet(String uri)

### Description
Adds a magnet URI to InTorrent and returns a torrent ID.

### Method
Future<int> addMagnet(String uri)

### Parameters
- **uri** (String) - Required - The magnet URI to add.

### Returns
- **Future<int>** - A torrent ID.

### Exceptions
- **FormatException** - Thrown if the native layer cannot add the supplied URI.

### Example
```dart
final torrentId = await addMagnet(
  'magnet:?xt=urn:btih:YOUR_INFO_HASH',
);
```
```

--------------------------------

### Inspect torrent status for progress issues

Source: https://github.com/zsdev07/intorrent/blob/main/doc/troubleshooting.md

Inspects torrent status details including state, peer and seed counts, and downloaded bytes. Use this to diagnose why progress is not moving, such as when there are no usable peers or seeds.

```dart
final status = await getStatus(id);

print(status.state);
print(status.numPeers);
print(status.numSeeds);
print(status.downloadedBytes);
```

--------------------------------

### Import InTorrent public API

Source: https://github.com/zsdev07/intorrent/blob/main/doc/getting-started.md

Import the public API of the InTorrent plugin. Do not import 'lib/src/intorrent_bindings.dart' from application code; that file is the low-level FFI layer.

```dart
import 'package:intorrent/intorrent.dart';
```

--------------------------------

### How streaming works: flow diagram

Source: https://github.com/zsdev07/intorrent/blob/main/doc/streaming.md

High-level flow of streaming: the native layer prepares the file for sequential downloading, the Dart layer registers it with a local HTTP server, and the media player consumes it. The server checks byte-range availability before reading from disk.

```text
streamUrl()
    |
    v
Native libtorrent
    |
    +-- select requested file
    +-- enable sequential download
    +-- prioritize initial window
    |
    v
Local HTTP server
    |
    v
Media player
```

--------------------------------

### Wait for metadata with TorrentState.downloadingMetadata

Source: https://github.com/zsdev07/intorrent/blob/main/doc/troubleshooting.md

Condition to wait for while metadata is being downloaded. Use this in a loop or with a delay before retrying operations that require metadata.

```dart
status.state == TorrentState.downloadingMetadata
```

--------------------------------

### Package name

Source: https://github.com/zsdev07/intorrent/blob/main/doc/installation.md

The package name for the InTorrent Dart package.

```yaml
intorrent
```

--------------------------------

### remove

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Stops and removes the torrent and deletes its temporary files.

```APIDOC
## remove

### Description
Stops and removes the torrent and deletes its temporary files.

### Method
Future<void> remove(int id)

### Parameters
- **id** (int) - Required - The torrent ID.

### Throws
- **StateError** - unknown torrent ID.
```

--------------------------------

### Pause Torrent

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Pauses the torrent by asking the native libtorrent torrent handle to pause.

```dart
await pause(torrentId);
```

--------------------------------

### Add a magnet URI with addMagnet

Source: https://github.com/zsdev07/intorrent/blob/main/doc/getting-started.md

Add a magnet URI and obtain the torrent ID used by the rest of the API.

```dart
final torrentId = await addMagnet(
  'magnet:?xt=urn:btih:YOUR_INFO_HASH',
);
```

--------------------------------

### streamUrl()

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Provides a streaming URL for a selected file index.

```APIDOC
## streamUrl()

### Description
Provides a streaming URL for a selected file index.

### Method
Future<String> streamUrl()

### Returns
- **Future<String>** - A streaming URL for the selected file.
```

--------------------------------

### getStatus(int torrentId)

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Retrieves the status of a torrent, including its state (e.g., downloadingMetadata).

```APIDOC
## getStatus(int torrentId)

### Description
Retrieves the status of a torrent, including its state (e.g., downloadingMetadata).

### Method
Future<Status> getStatus(int torrentId)

### Parameters
- **torrentId** (int) - Required - The torrent ID returned by addMagnet().

### Returns
- **Future<Status>** - The torrent status, containing a state field.

### Example
```dart
final status = await getStatus(torrentId);

if (status.state == TorrentState.downloadingMetadata) {
  // Wait and poll again.
}
```
```

--------------------------------

### TorrentFile class definition

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Defines the TorrentFile class with index, name, and size fields. The index is passed to streamUrl().

```dart
class TorrentFile {
  final int index;
  final String name;
  final int size;
}
```

--------------------------------

### Remove torrent with remove

Source: https://github.com/zsdev07/intorrent/blob/main/doc/getting-started.md

Remove the torrent when playback is finished. Stops the torrent and asks the native layer to delete its temporary torrent files.

```dart
await remove(torrentId);
```

--------------------------------

### Add Git dependency

Source: https://github.com/zsdev07/intorrent/blob/main/doc/installation.md

Adds the InTorrent package as a Git dependency during active development.

```yaml
dependencies:
  intorrent:
    git:
      url: https://github.com/zsdev07/InTorrent.git
```

--------------------------------

### Catch FormatException thrown by addMaven() for invalid URIs

Source: https://github.com/zsdev07/intorrent/blob/main/doc/magnet-links.md

Provides a try-catch wrapper around addMaven() printing either the resulting torrent ID or details of the FormatException that occurs when the native layer rejects the supplied magnet URI, enabling graceful error handling in Dart code

```dameon
try {
  final id = await addMaven(magnetUri);
  wait('Torrents ID: $id');
} on FormatException catch ( downloadingError) {
 wait('Invalid magnet: $error');
}
```

--------------------------------

### Android FFI plugin configuration

Source: https://github.com/zsdev07/intorrent/blob/main/doc/installation.md

Configures the Android plugin to use Flutter's FFI plugin integration.

```yaml
flutter:
  plugin:
    platforms:
      android:
        ffiPlugin: true
```

--------------------------------

### getStatus function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the getStatus function that returns a point-in-time status snapshot for a torrent ID. Throws StateError for unknown torrent ID.

```dart
Future<TorrentStatus> getStatus(int id)
```

--------------------------------

### Wait for torrent metadata

Source: https://github.com/zsdev07/intorrent/blob/main/doc/getting-started.md

Poll the torrent status until metadata is available, i.e., the state is no longer TorrentState.downloadingMetadata. Uses a 500 ms delay between checks.

```dart
while (true) {
  final status = await getStatus(torrentId);

  if (status.state != TorrentState.downloadingMetadata) {
    break;
  }

  await Future<void>.delayed(
    const Duration(milliseconds: 500),
  );
}
```

--------------------------------

### cancelPrefetch

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Stops an active prefetch window and returns the selected file to normal streaming behavior.

```APIDOC
## cancelPrefetch

### Description
Stops an active prefetch window and returns the selected file to normal streaming behavior. Calling it when no prefetch is active is safe.

### Method
Future<void> cancelPrefetch(int id)

### Parameters
- **id** (int) - Required - The torrent ID.

### Throws
- **StateError** - unknown torrent ID.
```

--------------------------------

### TorrentStatus class definition

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Defines the TorrentStatus class with fields for totalBytes, downloadedBytes, progress, state, numPeers, numSeeds, and isPaused.

```dart
class TorrentStatus {
  final int totalBytes;
  final int downloadedBytes;
  final double progress;
  final TorrentState state;
  final int numPeers;
  final int numSeeds;
  final bool isPaused;
}
```

--------------------------------

### streamReadCursor

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Returns the main stream's served byte cursor, or `null` if nothing has been served.

```APIDOC
## streamReadCursor

### Description
Returns the main stream's served byte cursor, or `null` if nothing has been served.

### Method
int? streamReadCursor(int id)

### Parameters
- **id** (int) - Required - The torrent ID.

### Returns
- **int?** - served byte cursor, or null if nothing has been served.
```

--------------------------------

### pause function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the pause function that pauses the torrent. Throws StateError for unknown torrent ID.

```dart
Future<void> pause(int id)
```

--------------------------------

### cancelPrefetch function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the cancelPrefetch function that stops an active prefetch window and returns the file to normal streaming. Safe to call when no prefetch is active. Throws StateError for unknown torrent ID.

```dart
Future<void> cancelPrefetch(int id)
```

--------------------------------

### remove(torrentId)

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Removes the torrent. Removal invalidates the torrent ID, removes the torrent from the native session, deletes the torrent's temporary files, and unregisters the torrent from the local HTTP streaming server. After `remove()`, the old ID must not be used with other InTorrent methods.

```APIDOC
## remove(torrentId)

### Description
Removes the torrent. Removal invalidates the torrent ID, removes the torrent from the native session, deletes the torrent's temporary files, and unregisters the torrent from the local HTTP streaming server. After `remove()`, the old ID must not be used with other InTorrent methods.

### Method
Dart function

### Endpoint
`remove(torrentId)`

### Parameters
- **torrentId** (type not specified) - Required - The identifier of the torrent.

### Errors
Throws `StateError` if the torrent ID is unknown.
```

--------------------------------

### Handle StateError on Pause

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Handles StateError thrown by lifecycle methods when the torrent ID is unknown.

```dart
try {
  await pause(torrentId);
} on StateError catch (error) {
  print(error);
}
```

--------------------------------

### remove function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the remove function that stops and removes the torrent and deletes its temporary files. Throws StateError for unknown torrent ID.

```dart
Future<void> remove(int id)
```

--------------------------------

### streamReadCursor function signature

Source: https://github.com/zsdev07/intorrent/blob/main/doc/api-reference.md

Declares the streamReadCursor function that returns the main stream's served byte cursor, or null if nothing has been served.

```dart
int? streamReadCursor(int id)
```

--------------------------------

### TorrentState Enum

Source: https://github.com/zsdev07/intorrent/blob/main/doc/torrent-management.md

Defines the public TorrentState enum. The unknown state indicates the native layer returned a state not mapped to a known value.

```dart
enum TorrentState {
  queued,
  checking,
  downloadingMetadata,
  downloading,
  finished,
  seeding,
  unknown,
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.