Jira-rest-sdk NPM

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: 'YOUR@EMAIL.ORG',
      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