JavaScript / TypeScript library for Node.JS and browsers to easily interact with Atlassian Jira API

About

Jira.js is a powerful Node.JS / Browser module that allows you to interact with the Jira Cloud API, Jira Agile Cloud API, Jira ServiceDesk Cloud API very easily.

Usability, consistency, and performance are key focuses of jira.js, and it also has nearly 100% coverage of the Jira API. It receives new Jira features shortly after they arrive in the API.

Table of Contents

• Installation
• Documentation
• Usage
  • Authentication
    • Basic
    • OAuth 2.0
    • Personal access token
  • Error handling
  • Example and using algorithm
• Decreasing Webpack bundle size
• Take a look at our other products
• License

Installation

Node.js 18.0.0 or newer is required.

Install with the npm:

npm install jira.js

Install with the yarn:

yarn add jira.js

Documentation

You can find the documentation here.

Usage

Authentication

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.js';

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

Email and API Token example:

import { Version3Client } from 'jira.js';

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

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.js';

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

Personal access token

To create a personal access token, use this link: https://id.atlassian.com/manage-profile/security/api-tokens

import { Version3Client } from 'jira.js';

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    personalAccessToken: 'secrectPAT',
  },
});

Error handling

Starting from version 4.0.0, the library has a new error handling system. Now, all errors are instances of

• the HttpException class in case the Axios has response from the server;
• the AxiosError class in case something went wrong before sending the request.

The HttpException class tries to parse different sorts of responses from the server to provide a unified error class.

If the original error is required, you can get it from the cause property of the HttpException class.

try {
  const users = await this.client.userSearch.findUsers({ query: email });
  // ...
} catch (error: uknown) {
  if (error instanceof HttpException) {
    console.log(error.message);
    console.log(error.cause); // original error (AxiosError | Error)
    console.log(error.cause.response?.headers); // headers from the server
  } else if (error instanceof AxiosError) {
    console.log(error.message);
    console.log(error.code); // error code, for instance AxiosError.ETIMEDOUT
  } else {
    console.log(error);
  }
}

Example and using algorithm

1. Example

You can find out examples project here or perform the following actions:

• Change the host, email and apiToken to your data
• Run script

import { Version3Client } from 'jira.js';

const client = new Version3Client({
  host,
  authentication: {
    basic: {
      email,
      apiToken,
    },
  },
});

async function main() {
  const { values: projects } = await client.projects.searchProjects();

  if (projects.length) {
    const project = projects[0];

    const { id } = await client.issues.createIssue({
      fields: {
        summary: 'My first issue',
        issuetype: {
          name: 'Task'
        },
        project: {
          key: project.key,
        },
      }
    });

    const issue = await client.issues.getIssue({ issueIdOrKey: id });

    console.log(`Issue '${issue.fields.summary}' was successfully added to '${project.name}' project.`);
  } else {
    const myself = await client.myself.getCurrentUser();

    const { id } = await client.projects.createProject({
      key: 'PROJECT',
      name: "My Project",
      leadAccountId: myself.accountId,
      projectTypeKey: 'software',
    });

    const project = await client.projects.getProject({ projectIdOrKey: id.toString() });

    console.log(`Project '${project.name}' was successfully created.`);
  }
}

main();

2. The algorithm for using the library:

client.<group>.<methodName>(parametersObject);

Available groups:

Agile Cloud API group

• backlog
• board
• builds
• deployments
• developmentInformation
• devopsComponents
• epic
• featureFlags
• issue
• operations
• remoteLinks
• securityInformation
• sprint

Version 2 Cloud REST API group

• announcementBanner
• applicationRoles
• appMigration
• auditRecords
• avatars
• dashboards
• filters
• filterSharing
• groupAndUserPicker
• groups
• issues
• issueAttachments
• issueComments
• issueCustomFieldConfigurationApps
• issueCommentProperties
• issueFields
• issueFieldConfigurations
• issueCustomFieldContexts
• issueCustomFieldOptions
• issueCustomFieldOptionsApps
• issueCustomFieldValuesApps
• issueLinks
• issueLinkTypes
• issueNavigatorSettings
• issueNotificationSchemes
• issuePriorities
• issueProperties
• issueRemoteLinks
• issueResolutions
• issueSearch
• issueSecurityLevel
• issueSecuritySchemes
• issueTypes
• issueTypeSchemes
• issueTypeScreenSchemes
• issueTypeProperties
• issueVotes
• issueWatchers
• issueWorklogs
• issueWorklogProperties
• jiraExpressions
• jiraSettings
• jql
• jqlFunctionsApps
• labels
• licenseMetrics
• myself
• permissions
• permissionSchemes
• projects
• projectAvatars
• projectCategories
• projectComponents
• projectEmail
• projectFeatures
• projectKeyAndNameValidation
• projectPermissionSchemes
• projectProperties
• projectRoles
• projectRoleActors
• projectTypes
• projectVersions
• screens
• screenTabs
• screenTabFields
• screenSchemes
• serverInfo
• status
• tasks
• timeTracking
• uiModificationsApps
• users
• userProperties
• userSearch
• webhooks
• workflows
• workflowTransitionRules
• workflowSchemes
• workflowSchemeProjectAssociations
• workflowSchemeDrafts
• workflowStatuses
• workflowStatusCategories
• workflowTransitionProperties
• appProperties
• dynamicModules

Version 3 Cloud REST API group

• announcementBanner
• applicationRoles
• appMigration
• auditRecords
• avatars
• dashboards
• filters
• filterSharing
• groupAndUserPicker
• groups
• instanceInformation
• issues
• issueAttachments
• issueComments
• issueCustomFieldConfigurationApps
• issueCommentProperties
• issueFields
• issueFieldConfigurations
• issueCustomFieldContexts
• issueCustomFieldOptions
• issueCustomFieldOptionsApps
• issueCustomFieldValuesApps
• issueLinks
• issueLinkTypes
• issueNavigatorSettings
• issueNotificationSchemes
• issuePriorities
• issueProperties
• issueRemoteLinks
• issueResolutions
• issueSearch
• issueSecurityLevel
• issueSecuritySchemes
• issueTypes
• issueTypeSchemes
• issueTypeScreenSchemes
• issueTypeProperties
• issueVotes
• issueWatchers
• issueWorklogs
• issueWorklogProperties
• jiraExpressions
• jiraSettings
• jql
• jqlFunctionsApps
• labels
• licenseMetrics
• myself
• permissions
• permissionSchemes
• projects
• projectAvatars
• projectCategories
• projectComponents
• projectEmail
• projectFeatures
• projectKeyAndNameValidation
• projectPermissionSchemes
• projectProperties
• projectRoles
• projectRoleActors
• projectTypes
• projectVersions
• screens
• screenTabs
• screenTabFields
• screenSchemes
• serverInfo
• status
• tasks
• timeTracking
• uiModificationsApps
• users
• userProperties
• userSearch
• webhooks
• workflows
• workflowTransitionRules
• workflowSchemes
• workflowSchemeProjectAssociations
• workflowSchemeDrafts
• workflowStatuses
• workflowStatusCategories
• workflowTransitionProperties
• appProperties
• dynamicModules

Service Desk Cloud API group

• customer
• info
• insight
• knowledgeBase
• organizations
• request
• requestType
• serviceDesk

The name of the methods is the name of the endpoint in the group without spaces and in camelCase.

The parameters depend on the specific endpoint. For more information, see here.

Decreasing Webpack bundle size

If you use Webpack and need to reduce the size of the assembly, you can create your client with only the groups you use.

import { BaseClient } from 'jira.js';
import { Board } from 'jira.js/out/agile';
import { Groups } from 'jira.js/out/version2';
import { Issues } from 'jira.js/out/version3';

export class CustomJiraClient extends BaseClient {
  board = new Board(this);
  groups = new Groups(this);
  issues = new Issues(this);
}

Take a look at our other products

• Confluence.js - confluence.js is a powerful Node.JS / Browser module that allows you to interact with the Confluence API very easily
• Trello.js - JavaScript / TypeScript library for Node.JS and browsers to easily interact with Atlassian Trello API

License

Distributed under the MIT License. See LICENSE for more information.