Features :

xdccJS is a complete implementation of the <a href="https://en.wikipedia.org/wiki/XDCC">XDCC protocol</a> for nodejs.
It can also be used as a <a href="#command-line-interface">command-line</a> downloader !

Batch downloads : 1-3, 5, 32-35, 101
Resume file and auto-retry
Pipes!
Passive DCC
Check advanced examples and see what else you can do

API
Getting Started
List of options
Download
(Auto) disconnect from IRC
Advanced IRC commands and middlewares
CLI

Installation

API

Getting started

There's three different way to import/require xdccJS depending on which environment it is running:

CommonJS

const XDCC = require('xdccjs')
const xdccJS = new XDCC.default({/*..options..*/})

Modules

import XDCC from 'xdccjs'
const xdccJS = new XDCC.default({/*..options..*/})

TypeScript

import XDCC from 'xdccjs'
const xdccJS = new XDCC({/*..options..*/})

Example

const XDCC = require('xdccjs')

const xdccJS = new XDCC.default({
  host: 'irc.server.net',
  port: 6667,
  chan: ['#welcome', '#fansub'],
  nickname: 'Leon',
  path: '/home/leon/downloads'
})

xdccJS.on('ready', () => {
  xdccJS.download('XDCC|BOT_RED', 5)
  xdccJS.download('XDCC|BOT_GREEN', '1-3, 55, 100-200')
  xdccJS.download('XDCC|BOT_BLUE', [12, 7, 10, 20])
  xdccJS.download('XDCC|BOT_ALPHA', ['5', '6'])
})

Options

Every parameter is optional, except for host.

const opts = {
  host: 'irc.server.net', // IRC hostname                                                   - required
  port: 6660, // IRC port                                                                   - default: 6667
  tls: {
    enable: true, // Enable TLS Support                                                     - default: false
    rejectUnauthorized: true, // Reject self-signed certificates                            - default: false
  },
  nickname: 'ItsMeJiPaix', // Nickname                                                      - default: xdccJS + random
  nickServ: 'complex_password', // Your NickServ password (no spaces)                       - default: undefined (disabled)
  chan: ['#candy', '#fruits'], // Array of channels                                         - default : [ ] (no chan)
  path: 'downloads', // Download path or 'false'                                            - default: false (which enables piping)
  retry: 2, // Nb of retries before skip                                                    - default: 1
  timeout: 50, // Nb of seconds before a download is considered timed out                   - default: 30
  verbose: true, // Display download progress and jobs status                               - default: false
  randomizeNick: false, // Add random numbers at end of nickname                            - default: true
  passivePort: [5000, 5001, 5002], // Array of port(s) to use with Passive DCC              - default: [5001]
  botNameMatch: false, // Block downloads if the bot's name does not match the request      - default: true
  throttle: 500, // Throttle download speed to n KiB/s                                       - default: undefined (disabled)
  queue: /soMething(.*)maTching/g //                                                        - default: undefined (disabled)
  // ^ Regex matching the bot's message when you're request is moved to a queue    
}

Config

xdccJS.config( parameters? : object ) change parameters during runtime
If there's a file downloading throttle and passivePort won't be applied until the next download

xdccJS.config({
  passivePort: [5000, 5001, 5002],
  throttle: 800,
  nickname: 'TrustMe',
  chan: ['#candy', '#fruits'], 
  path: 'download/subfolder',
  botNameMatch: false,
  retry: 5,
  timeout: 50,
  verbose: false,
  randomizeNick: true,
  queue: /soMething(.*)maTching/g
})

Download

xdccJS.download( bot : string, packets : string | number | number[] | string[], options?: { ipv6?: boolean ** throttle?: number } )
download() is asynchronous and returns a Job
options are optional, per job options.ipv6 parameter is only required when if a bot's is ipv6 AND uses passive DCC

xdccJS.on('ready', async () => {
  const blue = await xdccJS.download('XDCC|BLUE', '1-3, 8, 55')
  const yellow = await xdccJS.download('XDCC|YELLOW', 4)
  const red = await xdccJS.download('XDCC|RED', [12, 7, 10, 20])
  const purple = await xdccJS.download('XDCC|PURPLE', ['1', '3', '10', '20'])
})

Download queue detection

xdccJS will timeout any request after a certain amount of time when no file is sent (see Options.timeout), Which is exactly what happens when a bot puts you into queue.

To avoid this behavior you need to provide a regex matching the bot "queue message".

If you are clueless about regexes try regexlearn.com interactive tutorial.

const opts = {
  host: 'irc.server.com',
  timeout: 20 // defaut is 30
  queue: /request(.*)queued(.*)\d+\/\d+$/gi
  //=> excepted bot queue message: "Your request has been queued: position x/x"
}
const xdccJS = new XDCC(opts)

xdccJS.on('ready', async () =>{
  const queued = await xdccJS.download('BOT_WITH_LARGE_QUEUE', '1-5')
  //=> if the bot sends a message matching the regex, download won't fail
})

Jobs

Jobs are download() instances which are tied to the target nickname.
calling download() multiple times for the same target will update current job.

xdccJS.on('ready', async () => {
  // jobs are automatically updated
  const botA_1 = await xdccJS.download('BOT-A', 1)
  const botA_2 = await xdccJS.download('BOT-A', 2)
  const botA_3 = await xdccJS.download('BOT-A', 3)
  // botA_1 === botA_2 === botA_3


  // but each "target" has its own job
  const botB_1 = await xdccJS.download('DIFFERENT_TARGET', 4)
  // botA_1 !== botB_1

  // once a job's done, its lifetime ends
  botA_1.on('done', async () => {
    const botA_5 = await xdccJS.download('BOT-A', 5)
    // botA_1 !== botA_5
  })

  // Job options are overwritable
  await xdccJS.download('BOT-B', 1, { throttle: 500 })
  await xdccJS.download('BOT-B', 2, { throttle: 1000 })
  // => Both packets, 1 and 2, will be throttled at 1000 (latest)
})

You can also retrieve on going jobs

xdccJS.jobs( bot : string | undefined )

// find job by botname
const job = await xdccJS.jobs('bot-name')

// retrieve all jobs at once
const arrayOfJobs = await xdccJS.jobs()

Jobs offer three options :

Get job progress status :

let status = job1.show()
let isdone = job1.isDone()
console.log(status)
//=> { name: 'a-bot', queue: [98], now: 62, success: ['file.txt'], failed: [50] }
console.log(isdone)
//=> false

Cancel a Job
```
job2.cancel()
```

Events to track progress (see events documentation)

job.on('downloaded', (fileInfo) => {
  //=> a file has been downloaded
})

job.on('done', () => {
  //=> job has finished downloading all requested packages
})

// more below..

Events

Most events are accessible both from xdccJS or a Job scope

FYI: those examples are for the sake of showing xdccJS capabilities, if you need download status to be displayed in a nice way just start xdccJS with parameter verbose = true

[xdccJS].on( 'ready' ) : xdccJS is ready to download

  xdccJS.on('ready', async () => {
    // download() here
  })

[xdccJS | Job].on( 'downloading' ) : Data is being received (a file is downloading)

  xdccJS.on('downloading', (fileInfo, received, percentage, eta) => {
    console.log(fileInfo) //=> { file: 'filename.pdf', filePath: '/path/to/filename.pdf', length: 5844849 }
    console.log(`downloading: '${fileInfo.file}'`) //=> downloading: 'your file.pdf'
  })

  job.on('downloading', (fileInfo, received, percentage, eta) => {
    console.log(`${percentage}% - ${eta} ms remaining`) //=> 10.55% - 153500 ms remaining
  })

[xdccJS | Job].on( 'downloaded' ) : *A file successfull

XdccJS

Install / Use

README