Jira.js

<div align="center"> <img alt="Jira.js logo" src="https://bad37fb3-cb50-4e0b-9035-a3e09e8afb3b.selstorage.ru/jira.js%2Flogo.svg"/>

<a href="https://www.npmjs.com/package/jira.js" target="_blank" rel="noopener noreferrer"><img alt="NPM version" src="https://img.shields.io/npm/v/jira.js.svg?maxAge=3600&style=flat-square" /></a> <a href="https://www.npmjs.com/package/jira.js" target="_blank" rel="noopener noreferrer"><img alt="NPM downloads per month" src="https://img.shields.io/npm/dm/jira.js.svg?maxAge=3600&style=flat-square" /></a> <a href="https://github.com/MrRefactoring/jira.js" target="_blank" rel="noopener noreferrer"><img alt="build status" src="https://img.shields.io/github/actions/workflow/status/mrrefactoring/jira.js/.github/workflows/ci.yaml?branch=master&style=flat-square"></a> <a href="https://github.com/mrrefactoring/jira.js/blob/develop/LICENSE" target="_blank" rel="noopener noreferrer"><img alt="license" src="https://img.shields.io/github/license/mrrefactoring/jira.js?color=green&style=flat-square"/></a> <a href="https://www.typescriptlang.org/" target="_blank" rel="noopener noreferrer"><img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-Ready-blue?style=flat-square&logo=typescript" /></a> <a href="https://nodejs.org/" target="_blank" rel="noopener noreferrer"><img alt="Node.js" src="https://img.shields.io/badge/Node.js-20%2B-green?style=flat-square&logo=node.js" /></a>

<span>JavaScript / TypeScript library for Node.js and browsers to interact with Atlassian Jira APIs</span>

</div>

About

Jira.js is a powerful, production-ready Node.js and browser-compatible TypeScript library that provides seamless interaction with Atlassian Jira Cloud APIs. This npm package offers comprehensive support for:

• Jira Cloud REST API v2/v3 - Complete platform API coverage
• Jira Agile Cloud API - Sprint, board, and backlog management
• Jira Service Desk Cloud API - Service desk operations

Key Features

• ✅ Type-Safe: Full TypeScript support with comprehensive type definitions and IntelliSense
• ✅ Tree-Shakable: Optimize bundle size by importing only what you need (perfect for browser apps)
• ✅ Universal: Works in Node.js (v20+) and modern browsers with full ESM/CJS support
• ✅ Complete Coverage: Nearly 100% of Jira Cloud REST API v2/v3, Agile, and Service Desk APIs
• ✅ Well Documented: Extensive JSDoc, API reference, and code examples
• ✅ Modern Stack: Built with TypeScript, supports ES Modules and CommonJS
• ✅ Actively Maintained: Regular updates with new Jira API features and bug fixes
• ✅ Production Ready: Used by thousands of developers in production environments

Perfect for building Jira integrations, automation tools, webhooks, CI/CD pipelines, custom Jira applications, and browser-based Jira management tools.

Table of Contents

• Getting Started
  • Installation
  • Quick Example
• Documentation
• Usage
  • Authentication
    • Email and API Token
    • OAuth 2.0
  • Error Handling
  • API Structure
• Tree Shaking
• Other Products
• License

Getting Started

Installation

Install the Jira.js npm package using your preferred package manager. Requires Node.js 20.0.0 or newer.

# Using npm
npm install jira.js

# Using yarn
yarn add jira.js

# Using pnpm
pnpm add jira.js

TypeScript users: Type definitions are included - no additional @types package needed!

Quick Example

Get started with Jira.js in under 5 minutes. This example shows how to create a Jira issue using the TypeScript client:

import { Version3Client } from 'jira.js';

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'your@email.com',
      apiToken: 'YOUR_API_TOKEN', // Create one: https://id.atlassian.com/manage-profile/security/api-tokens
    },
  },
});

async function createIssue() {
  const project = await client.projects.getProject({ projectIdOrKey: 'Your project id or key' });

  const newIssue = await client.issues.createIssue({
    fields: {
      summary: 'Hello Jira.js!',
      issuetype: { name: 'Task' },
      project: { key: project.key },
    },
  });

  console.log(`Issue created: ${newIssue.id}`);
}

createIssue();

Documentation

📚 Full API reference, guides, and examples available at: https://mrrefactoring.github.io/jira.js/

The documentation includes:

• Complete API reference for all endpoints
• TypeScript examples and code samples
• Authentication guides
• Error handling patterns
• Best practices and tips

Supported APIs

Jira.js provides comprehensive support for all major Jira Cloud APIs:

• Jira Platform REST API v2: Legacy API endpoints for projects, issues, users, and more
• Jira Platform REST API v3: Modern API with enhanced features and improved performance
• Jira Software (Agile) API: Sprint management, boards, backlogs, and agile workflows
• Jira Service Desk API: Service desk operations, customer management, and request handling

All APIs are fully typed with TypeScript definitions, making development faster and safer.

Usage

Authentication

Email and API Token

1. Create an API token: https://id.atlassian.com/manage-profile/security/api-tokens
2. Configure the client:

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: { email: 'YOUR@EMAIL.ORG', apiToken: 'YOUR_API_TOKEN' },
  },
});

OAuth 2.0

Only authorization code grants are supported. Implement your own token acquisition flow using Atlassian's OAuth 2.0 documentation.

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

Error Handling

Errors are categorized as:

• HttpException: Server responded with an error (includes parsed error details)
• AxiosError: Network/configuration issues (e.g., timeouts)

Example handling:

try {
  await client.issues.getIssue({ issueIdOrKey: 'INVALID-123' });
} catch (error) {
  if (error instanceof HttpException) {
    console.error('Server error:', error.message);
    console.debug('Response headers:', error.cause.response?.headers);
  } else if (error instanceof AxiosError) {
    console.error('Network error:', error.code);
  } else {
    console.error('Unexpected error:', error);
  }
}

API Structure

Access endpoints using the client.<group>.<method> pattern:

// Get all projects
const projects = await client.projects.searchProjects();

// Create a sprint
const sprint = await client.sprint.createSprint({ name: 'Q4 Sprint' });

Available API groups:

<details> <summary>🔽 Agile Cloud API</summary>

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

</details> <details> <summary>🔽 Core REST API (v2/v3)</summary>

• api
• announcementBanner
• appDataPolicy
• applicationRoles
• appMigration
• auditRecords
• [avatars](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-avatars/#api-