🌐 English · Русский

jira.js — клиент Jira REST API для Node.js, TypeScript и браузеров

Библиотека на JavaScript / TypeScript для Node.js и браузеров для работы с API Atlassian Jira

О библиотеке

Jira.js — это мощная, готовая к продакшену TypeScript-библиотека для Node.js и браузеров, обеспечивающая удобное взаимодействие с API Atlassian Jira Cloud. Этот npm-пакет предоставляет полную поддержку:

• Jira Cloud REST API v2/v3 — полное покрытие платформенного API
• Jira Agile Cloud API — управление спринтами, досками и бэклогами
• Jira Service Desk Cloud API — операции service desk

Ключевые возможности

• ✅ Типобезопасность: полная поддержка TypeScript с исчерпывающими определениями типов и IntelliSense
• ✅ На промисах: понятный async/await-интерфейс для каждого метода API
• ✅ Поддержка tree-shaking: оптимизируйте размер бандла, импортируя только то, что нужно (идеально для браузерных приложений)
• ✅ Универсальность: работает в Node.js (v20+) и современных браузерах с полной поддержкой ESM/CJS
• ✅ Полное покрытие: почти 100% Jira Cloud REST API v2/v3, Agile и Service Desk API
• ✅ Хорошая документация: подробные JSDoc, справочник по API и примеры кода
• ✅ Современный стек: написана на TypeScript, поддерживает ES Modules и CommonJS
• ✅ Активная поддержка: регулярные обновления с новыми возможностями Jira API и исправлениями ошибок
• ✅ Готовность к продакшену: используется тысячами разработчиков в продакшене

Идеально подходит для создания интеграций с Jira, инструментов автоматизации, вебхуков, CI/CD-пайплайнов, кастомных приложений Jira и браузерных инструментов управления Jira.

Содержание

• Начало работы
• Установка
• Быстрый пример
• Документация
• Использование
• Аутентификация
  • Email и API-токен
  • OAuth 2.0
  • JWT (Atlassian Connect)
• Обработка ошибок
• Структура API
• Tree-shaking
• Другие продукты
• Лицензия

Начало работы

Установка

Установите npm-пакет Jira.js с помощью предпочитаемого менеджера пакетов. Требуется Node.js 20.0.0 или новее.

# Через npm
npm install jira.js

# Через yarn
yarn add jira.js

# Через pnpm
pnpm add jira.js

Пользователям TypeScript: определения типов уже включены — отдельный пакет @types не нужен!

Быстрый пример

Начните работу с Jira.js менее чем за 5 минут. В этом примере показано, как создать задачу в Jira с помощью TypeScript-клиента:

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', // Создайте его: 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();

Документация

📚 Полный справочник по API, руководства и примеры доступны по адресу: https://mrrefactoring.github.io/jira.js/

Документация включает: - Полный справочник по API для всех эндпоинтов - Примеры на TypeScript и фрагменты кода - Руководства по аутентификации - Паттерны обработки ошибок - Лучшие практики и советы

Поддерживаемые API

Jira.js предоставляет полную поддержку всех основных API Jira Cloud:

• Jira Platform REST API v2: устаревшие эндпоинты API для проектов, задач, пользователей и не только
• Jira Platform REST API v3: современный API с расширенными возможностями и улучшенной производительностью
• Jira Software (Agile) API: управление спринтами, доски, бэклоги и agile-процессы
• Jira Service Desk API: операции service desk, управление клиентами и обработка запросов

Все API полностью типизированы с помощью определений TypeScript, что делает разработку быстрее и безопаснее.

Использование

Аутентификация

Email и API-токен

1. Создайте API-токен: https://id.atlassian.com/manage-profile/security/api-tokens
2. Настройте клиент:

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

OAuth 2.0

jira.js поддерживает полный поток Atlassian OAuth 2.0 (3LO). Простейшая настройка использует статический access-токен:

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

Полный поток с автоматическим обновлением и определением cloudId. Передайте учётные данные для обновления — и клиент будет обновлять access-токен по истечении срока действия (а также при 401), сохранять ротируемый refresh-токен через onTokenRefresh и направлять запросы через API-шлюз (https://api.atlassian.com/ex/jira/{cloudId}), так что host не требуется. clientSecret и обновление токенов — только на стороне сервера.

const client = new Version3Client({
  // без `host` — cloudId определяется автоматически (передайте `siteUrl` или `cloudId`, чтобы зафиксировать его)
  authentication: {
    oauth2: {
      accessToken: 'CURRENT_ACCESS_TOKEN',
      refreshToken: 'CURRENT_REFRESH_TOKEN',
      clientId: 'YOUR_CLIENT_ID',
      clientSecret: 'YOUR_CLIENT_SECRET',
      expiresAt: Date.now() + 3600 * 1000, // необязательно; миллисекунды эпохи
      onTokenRefresh: async ({ accessToken, refreshToken, expiresAt }) => {
        await saveTokens({ accessToken, refreshToken, expiresAt }); // сохраните ротируемые токены
      },
    },
  },
});

jira.js также экспортирует stateless-хелперы для потока с кодом авторизации — generateAuthorizationUrl, exchangeAuthorizationCode, refreshOAuth2Token, getAccessibleResources. См. пошаговое руководство по OAuth 2.0.

JWT (Atlassian Connect)

Для приложений Atlassian Connect аутентификация выполняется через JWT, формируемый для каждого запроса и подписываемый общим секретом (shared secret) вашего приложения. Это серверный поток — общий секрет никогда не должен попадать в браузер.

Примечание: Для Atlassian Connect наступает конец поддержки (Q4 2026), и новые приватные приложения больше нельзя установить через URL дескриптора. JWT-аутентификация здесь предназначена для существующих установок приложений Connect.

• issuer: ключ вашего приложения — поле key в дескрипторе atlassian-connect.json.
• secret: значение sharedSecret, которое ваше приложение получает в теле lifecycle-вебхука installed во время рукопожатия при установке. Храните его отдельно для каждого тенанта.
• expiryTimeSeconds (необязательно): время жизни токена в секундах (по умолчанию 180, т.е. 3 минуты).

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    jwt: {
      issuer: 'YOUR_APP_KEY',
      secret: 'YOUR_SHARED_SECRET',
      expiryTimeSeconds: 180, // необязательно
    },
  },
});

Для каждого запроса генерируется новый JWT с хешем строки запроса (qsh), привязанным к методу и URL этого запроса. О том, как создать приложение Connect и получить issuer и secret, см. пошаговое руководство по настройке.

Обработка ошибок

Ошибки делятся на категории: - HttpException: сервер ответил ошибкой (включает разобранные детали ошибки) - AxiosError: проблемы сети или конфигурации (например, таймауты)

Пример обработки:

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

Доступ к эндпоинтам осуществляется по схеме client.<group>.<method>:

// Получить все проекты
const projects = await client.projects.searchProjects();

// Создать спринт
const sprint = await client.sprint.createSprint({ name: 'Q4 Sprint' });

Доступные группы API:

🔽 Agile Cloud API

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

🔽 Core REST API (v2/v3)

• api
• announcementBanner
• appDataPolicy
• applicationRoles
• appMigration
• auditRecords
• avatars
• classificationLevels
• dashboards
• filters
• [fieldSchemes](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-field-schemes/#api-group-fi