As a Module

Note: API v4 is currently in development, and is on branch feature/report-groups

Running as an external module

To read more about the design decisions that went into v4, read here

Currently, the only exported function is the run() function, documented below. It returns a promise, which then resolves to the raw data.

Library

The library exposes the run function, which allows you to execute a report. It returns a promise which allows you to access the data from the report.

/**
 * Public interface for the run function.
 *
 * @param {string} report - the report id.
 * @param {Object=} options - report options
 * @return {Promise.<Object>}
 */
function run(report, options)

/**
 * Add an array of plugins to the plugins list.
 * @param {Array<Object>} array contains array of plugin objects.
 */
function registerModule (array)

/**
 * Remove all non-default plugins.
 */
function clearModules()

/**
 * Get an object containing keys for all reports and groups.
 */
get modules()

There are a few pre-defined options keys which may be accepted as the second parameter for the run(report, options) function. These key are documented in the individual report docs.

{
  raw: Boolean, // Optional, allows you to get raw iOS data
  backup: String | Backup, // Backup ID or Backup instance for running, if required
  filter: String, // Filter string
  id: String, // Filter ID
  extract: String // Filesystem extract dest. path. Allows extraction of files from the backup, if allowed.
}

Usage examples:

const bt = require('ibackuptool')

// Register custom reporting modules.
// See below for implementation
bt.registerModule([
  require('./reports')
])

// Call the backups.list report.
bt.run('backups.list')
  .then(backups => {
    // Gives you a list of backups.
    console.log(backups)
  }
  
// Call the backup.info report.
// You must provide a backup parameter to this module.
// Most modules will require this.
bt.run('backup.info', { backup: '<backup id here>' })
  .then(info => {
    // Gives you the formatted info about the backup
    console.log(info)
  })

// Call the backup.info report.
// You must provide a backup parameter to this module.
// Most modules will require this.
bt.run('backup.info', { backup: '<backup id here>', raw: true })
  .then(content => {
    // Gives you the raw contents of the backup Info.plist file.
    console.log(content)
  })

// Call the backup.info report.
// You must provide a backup parameter to this module.
// Most modules will require this.
bt.run('example.test')
  .then(content => {
    // The content of the third party report we added above.
    console.log(content)
  })

Report Module

// reports.js

// We must use the Group() object to declare groups.
const { Group } = require('ibackuptool')

module.exports = {
    // "example" is a group containing the "test" report.
    example: new Group({
        test: {
            version: 3,
            name: 'example.test',
            description: 'A test plugin',
            requiresBackup: false,
            
            run: function(lib, opts) {
                return new Promise((resolve, reject) => {
                    resolve([{
                        name: '1337',
                    }, {
                        name: 'test'
                    }, {
                        name: '12345'
                    }])
                })
            },
        
            output: {
                name: el => el.name
            }
        }
    })
}