Redmine-ts

redmine-ts is Redmine REST API client written using TypeScript and using Axios for making requests.. It supports 100% of Redmine's API features.

Installation

npm install --save redmine-ts

Usage

const fs = require('fs');
import {Redmine, RedmineTS} from 'redmine-ts';

// RedmineTS namespace can be used! (version 0.3.0+)
const redmineConfig: RedmineTS.Config = {
    /**
     * apiKey (optional) Redmine API key
     */
    apiKey: 'abcdef0123456789abcdef0123456789',

    /**
     * username (optional) Redmine username (login)
     */
    username: 'api-user',

    /**
     * password (optional) Redmine password
     */
    password: 'mySuperSecretPassword&TwoZero21',

    /**
     * impersonateUser (optional) Impersonate user login
     * See more: https://www.redmine.org/projects/redmine/wiki/rest_api#User-Impersonation
     */
    impersonateUser: 'secondUser',
    
    /**
     * maxUploadSize (optional) Maximum size of sent files in bytes. Default value: 5242880 (5MB)
     * Note that it's only changes the maxBodyLength parameter of axios.
     * Max upload size accepted by Redmine needs to be setted by administrator in settings!
     */
    maxUploadSize: 5242880
};

// Initialization
const redmine = new Redmine('https://redmine-hostname.com:3000', redmineConfig);

// Example 1: List 5 issues
redmine.listIssues({
    limit: 5
})
.then(iObj => {
    console.log(`Showing ${iObj.issues.length} of ${iObj.total_count} total results:`, iObj.issues)
})
.catch(err) {
    console.log('List issues error:', err)
}

// Example 2: Add attachment to issue
const fileContent = fs.readFileSync('example-image.png');
redmine.uploadFile(fileContent).then(res => {
    const { token } = res.upload;

    redmine.updateIssue(1, {
        uploads: [
            token,
            filename: 'sweet-duckling.png',
            content_type: 'image/png',
            description: 'A photo of a yellow lovely duckling!'
        ]
    })
})

Authentication

redmine-ts supports authentication using an API key as well as login/password. However, providing an authentication is not required - this allows for sending inquiries about publicly available resources.

If three parameters are given: API key, login and password, the API key always takes precedence. Additionally, the library does not attempt to automatically log in with the login/password in case of an incorrect API key

Additional

Limitations:

• The current version only supports JSON format (implementation of XML versions is not planned)

• ~~apiKey is the only authentication method right now~~ Since version 0.3.0 both authentication methods are available 😊

Known problems:

• ❗ Please use version 0.2.3 or above. Previous versions are broken by wrong pipeline configuration

• The parameter cf_x in the listIssues method (API ref) was not included, so TypeScript reports an error. Currently, to work around this problem, please use @ts-ignore (Issue #20)

• Search method - Since official documentation are not completed yet, only limit and offset parameters are available (Issue #19)

Planned improvements

• ✔️ ~~Add support for username/password authentication~~ available from verion 0.3.0

• ✔️ ~~Add support for User-Impersonation~~ available from verion 0.3.0

License

This software is distributed under the MIT License.