aMule EC Client for TypeScript


A TypeScript client library for interacting with aMule's External Connection (EC) protocol.

Ported from jamule (Java/Kotlin) to TypeScript.

Features

- ✅ Full EC protocol implementation (v0x0204)
- ✅ Authentication and connection management
- ✅ Server statistics
- ✅ File searching (local, global, Kad, web)
- ✅ Download management
- ✅ Shared files listing
- ⏳ Category management (partial)
- ⏳ ED2K link parsing

Installation

``bash
npm install amule-ec-client
`

Usage

`typescript
import { AmuleClient, SearchType } from 'amule-ec-client';

// Create client
const client = new AmuleClient({
host: 'localhost',
port: 4712,
password: 'your-password',
timeout: 10000, // optional, in milliseconds
});

// Get server stats
const stats = await client.getStats();
console.log(Download speed: ${stats.downloadSpeed} bytes/s);
console.log(Upload speed: ${stats.uploadSpeed} bytes/s);

// Perform a search
const results = await client.searchSync('ubuntu', SearchType.GLOBAL);
console.log(Found ${results.files.length} files);

for (const file of results.files) {
console.log(${file.fileName} (${file.sizeFull} bytes));

// Download a file
if (file.sourceCount > 5) {
await client.downloadSearchResult(file.hash);
}
}

// Get download queue
const queue = await client.getDownloadQueue();
console.log(${queue.length} files downloading);
`

API

$3

#### Constructor

`typescript
new AmuleClient(options: AmuleClientOptions)
`

Options:

- host: aMule server hostname
- port: EC port (default: 4712)
- password: EC password
- timeout: Connection timeout in ms (optional)

#### Methods

Connection

- reconnect(): Promise - Reconnect to server

Statistics

- getStats(): Promise - Get server statistics

Search

- searchAsync(query, searchType?, filters?): Promise - Start async search
- searchStatus(): Promise - Get search progress (0-1)
- searchResults(): Promise - Get search results
- searchSync(query, searchType?, filters?, timeout?): Promise - Synchronous search
- searchStop(): Promise - Stop current search

Downloads

- downloadSearchResult(hash, category?): Promise - Download from search results
- getDownloadQueue(): Promise - Get download queue

Shared Files

- getSharedFiles(): Promise - Get shared files

Protocol Details

This library implements the aMule External Connection protocol version 0x0204, compatible with:

- aMule 2.3.1
- aMule 2.3.2
- aMule 2.3.3

$3

- UTF-8 number encoding for reduced packet size
- ZLIB compression support
- MD5-based authentication with salt
- Binary packet format with tagged data structures

Development

`bash


Install dependencies

npm install

Build

npm run build

Test

npm test
``

Credits

- Original Java/Kotlin implementation: jamule by vexdev

License

MIT License