jira-rest-sdk

Another JavaScript/TypeScript wrapper for the JIRA REST API via swagger.

Features

• Lightless wrapper with axios
• TypeScript development friendly
• Generate by jira official swagger.json

API documents

https://x-cold.github.io/jira-rest-sdk/

NOTICE: Node.js is supported by default (jwt authentication depends on Node.js module named crypto). If you want to work in the browser, just customize with exported pure client (which doesn't support authentication and takes up less storage space) and override request method.

Usage

Install the package

npm i -S jira-rest-sdk

Authentication

This module is inspired by jira.js

There are several types of authentication to gain access to the Jira API. Let's take a look at a few of them below

Basic authentication

Basic authentication allows you to log in with credentials. You can use username and password, but this login method is not supported in the online version and most standalone versions, so it's better to release API Token, read how to do it here, and use it together with email.

Username and password example:

import { Version3Client } from 'jira-rest-sdk';

const client = new Version3Client({
  baseURL: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      username: 'YOUR_USERNAME',
      password: 'YOUR_PASSWORD',
    },
  },
});

Email and API Token example:

import { Version3Client } from 'jira-rest-sdk';

const client = new Version3Client({
  baseURL: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: '[email protected]',
      apiToken: 'YOUR_API_TOKEN',
    },
  },
});

OAuth

import { Version3Client } from 'jira-rest-sdk';

const client = new Version3Client({
  baseURL: 'https://your-domain.atlassian.net',
  authentication: {
    oauth: {
      consumerKey: 'your consumer key',
      consumerSecret: '-----BEGIN RSA PRIVATE KEY-----\n" + "some private key\n" + "-----END RSA PRIVATE KEY-----',
      accessToken: 'your access token',
      tokenSecret: 'your token secret',
    },
  },
});

OAuth 2.0

Only the authorization token is currently supported. To release it, you need to read the documentation and write your own code to get the token.

Example of usage

import { Version3Client } from 'jira-rest-sdk';

const client = new Version3Client({
  baseURL: 'https://your-domain.atlassian.net',
  authentication: {
    oauth2: {
      accessToken: 'YOUR_ACCESS_TOKEN',
    },
  },
});

JWT

import { Version3Client } from 'jira-rest-sdk';

const client = new Version3Client({
  baseURL: 'https://your-domain.atlassian.net',
  authentication: {
    jwt: {
      issuer: 'ISSUER',
      secret: 'shhhh',
      expiryTimeSeconds: 180,
    },
  },
});

Your first request and using algorithm

import { Version3Client } from 'jira-rest-sdk';

const client = new Version3Client({
  baseURL: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'YOUR_EMAIL',
      apiToken: 'YOUR_API_TOKEN',
    },
  },
});

async function main() {
  const projects = await client.getAllProjects();

  console.log(projects);
}

main();

// Expected output:
// [
//   {
//     expand: 'description,lead,issueTypes,url,projectKeys,permissions,insight',
//     self: 'https://your-domain.atlassian.net/rest/api/2/project/10000',
//     id: '10000',
//     key: 'TEST',
//     name: 'test',
//     avatarUrls: {
//       '48x48': 'https://your-domain.atlassian.net/secure/projectavatar?pid=10000&avatarId=10425',
//       '24x24': 'https://your-domain.atlassian.net/secure/projectavatar?size=small&s=small&pid=10000&avatarId=10425',
//       '16x16': 'https://your-domain.atlassian.net/secure/projectavatar?size=xsmall&s=xsmall&pid=10000&avatarId=10425',
//       '32x32': 'https://your-domain.atlassian.net/secure/projectavatar?size=medium&s=medium&pid=10000&avatarId=10425'
//     },
//     projectTypeKey: 'software',
//     simplified: true,
//     style: 'next-gen',
//     isPrivate: false,
//     properties: {},
//     entityId: 'e0a412bd-1510-4841-bdbc-84180db3ee3b',
//     uuid: 'e0a412bd-1510-4841-bdbc-84180db3ee3b'
//   }
// ]

Customize pure client to support working in a browser

import { Version3Client, FullRequestParams } from 'jira-rest-sdk/dist/pure';

class MyVersion3Client extends Version3Client {
  public request = async <T>(params: FullRequestParams): Promise<T> => {
    const res = {
      ...params,
    }; // TODO: implement request logic
    return res as any;
  };
}

const client = new MyVersion3Client();

async function main() {
  const projects = await client.getAllProjects();

  console.log(projects);
}

main();

Development

NPM scripts

• npm lint: Eslint code
• npm lint:fix: Eslint code and try to fix problems
• npm start: Realtime complie code
• npm run docs: Generate type documents
• npm run build: Build ths dist products
• npm run release: The same as npm run release:patch
• npm run release:patch: Automatically upgrade patch versioin and update CHANGELOG.md
• npm run release:minor: Automatically upgrade minor versioin and update CHANGELOG.md
• npm run release:major: Automatically upgrade major versioin and update CHANGELOG.md
• npm run test: Run test suite via jest with code coverage
• npm run test:watch: Run test suite in interactive watch mode
• npm run test:prod: Run linting and generate coverage
• npm run generate-jira-api: Generate v3 open api

Cookbook

• Local development

npm install
npm test