@narthia/jira-client

A Jira API client with dual ESM/CJS support, designed for both standard Jira REST API and Atlassian Forge applications. This project is 100% written in TypeScript with comprehensive type definitions and zero runtime dependencies for standard usage.

Features

• 🚀 TypeScript First: Full TypeScript support with comprehensive type definitions
• 🔄 Dual Client Support: Works with both standard Jira REST API and Atlassian Forge
• 📦 Modern Packaging: ESM and CommonJS dual support
• 🛡️ Type Safe: Fully typed API responses and requests
• 📚 OpenAPI Generated: Type definitions and documentation are automatically generated from Jira's OpenAPI Schema to ensure accuracy and completeness
• ⚡ Zero Dependencies: No runtime dependencies for standard Jira REST API usage. @forge/api is an optional peer dependency required only for Forge applications

Installation

npm install @narthia/jira-client

Quick Start

Standard Jira REST API Client

// jiraClient.ts
import { JiraClient } from "@narthia/jira-client";

// Initialize the client once and reuse across your application
export const client = new JiraClient({
  type: "default",
  auth: {
    email: "[email protected]",
    apiToken: "your-api-token",
    baseUrl: "https://your-domain.atlassian.net"
  }
});

// some-file-name.ts
import { client } from "./jiraClient.ts";

const issue = await client.issues.getIssue({
  issueKeyOrId: "PROJ-123",
  fields: ["summary", "description", "status"]
});

if (issue.success) {
  console.log(issue.data.fields.summary);
}

Atlassian Forge Client

// jiraClient.ts
import { JiraClient } from "@narthia/jira-client";
import api from "@forge/api";

// Initialize the client once and reuse across your application
export const client = new JiraClient({
  type: "forge",
  auth: { api }
});

// some-file-name.ts
const issue = await client.issues.getIssue({
  issueKeyOrId: "PROJ-123",
  opts: { as: "app" } // by default its user
});

if (issue.success) {
  console.log(issue.data.fields.summary);
}

Error Handling

The client provides comprehensive error handling with strongly typed responses:

const issue = await client.issues.getIssue({
  issueKeyOrId: "PROJ-123"
});

if (issue.success) {
  // Handle successful response - data is type-safe and available when success is true
  console.log(issue.data.fields.summary);
} else {
  // Handle error
  console.error("Error:", issue.error);
  console.log("Status:", issue.status);
}

API Reference

Method Parameters

All client methods accept a structured options object with the following parameters:

• opts: Additional configuration options for the request, including:
  • as: For Forge applications, requests are executed as the "user" by default. Set to "app" to execute requests with application-level permissions instead of user-level permissions.
  • headers: An object containing custom HTTP headers to include in the request. All required authentication and content-type headers are automatically managed by the client. Use this option to add additional headers or override default headers for specific requests (e.g., { "X-Custom-Header": "value", "Accept": "application/json" }).

Example Usage

// Get an issue with path and query parameters
const issue = await client.issues.getIssue({
  issueKeyOrId: "PROJ-123",
  fields: ["summary", "description", "status"]
});

// Use 'as' in opts for Forge-specific options
// In Atlassian Forge applications, requests are executed as the user by default.
// To execute requests with application-level permissions instead of user-level permissions,
// pass opts: { as: "app" }.
// This is particularly useful for operations requiring elevated permissions or automated processes.
const issueForge = await client.issues.getIssue({
  issueKeyOrId: "PROJ-123",
  opts: { as: "app" }
});

// Add custom headers using opts.headers
const issueWithHeaders = await client.issues.getIssue({
  issueKeyOrId: "PROJ-123",
  opts: {
    headers: {
      "X-Custom-Header": "my-value"
    }
  }
});

Client Configuration

Default Jira Config

interface DefaultJiraConfig {
  type: "default";
  auth: {
    email: string;
    apiToken: string;
    baseUrl: string;
  };
}

Forge Jira Config

interface ForgeJiraConfig {
  type: "forge";
  auth: {
    api: ForgeAPI;
  };
}

Type Definitions

The package exports comprehensive TypeScript definitions for all Jira entities:

• Issue - Complete issue object with comprehensive field definitions
• User - User profile and account information
• Project - Project configuration and metadata
• Status - Workflow status and transition information
• IssueType - Issue type definitions and configurations
• And many more entity types...

Development Roadmap

Completed Features

• ✅ Jira Platform APIs - Comprehensive implementation of core Jira platform APIs with complete TypeScript support and type safety.
• ✅ Jira Service Management APIs - Comprehensive implementation of core Jira service management APIs with complete TypeScript support and type safety.
• ✅ Jira Software APIs - Comprehensive implementation of Jira Software-specific endpoints and advanced features with complete TypeScript support and type safety.

License

MIT License - see LICENSE file for details.

Changelog

See CHANGELOG.md for a list of changes and version history.

Security

For detailed security information, vulnerability reporting, and security best practices, please see our SECURITY.md file.

Network Access Disclosure

This package makes network requests to:

• Your configured Jira instance (via HTTPS)
• Atlassian Forge API (when used in Forge applications)

All network requests are made to authenticate with and interact with Jira APIs as intended.

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Repository