Class: JiraProvider

Jira provider that connects to Jira Cloud instances via REST API v3.

Authenticates using email and API token, executes JQL queries to fetch issues, and maps them to roadmap cards.

Example

const provider = new JiraProvider({
  type: 'jira',
  options: {
    url: process.env.JIRA_URL,
    email: process.env.JIRA_EMAIL,
    apiToken: process.env.JIRA_API_TOKEN,
  },
});

Extends

• RoadmapProvider<JiraProviderConfig>

Constructors

new JiraProvider()

new JiraProvider(config): JiraProvider

Parameters

Parameter	Type
config	JiraProviderConfig

Returns

JiraProvider

Overrides

RoadmapProvider.constructor

Properties

Property	Modifier	Type	Description	Inherited from
config	readonly	JiraProviderConfig	Provider specific configuration object.	RoadmapProvider.config

Methods

createCard()

createCard(input): Promise<CreateCardResult>

Creates a new Jira issue.

Converts plain text description to ADF. If column is not 'Backlog', transitions the issue to the appropriate status. Only the first assignee is used (Jira limitation).

Parameters

Parameter	Type	Description
input	CreateCardInput	Card data (title, description, column, labels, assignees, issueType).

Returns

Promise<CreateCardResult>

CreateCardResult with success status and created card.

Example

const result = await provider.createCard({
  title: 'New Feature',
  description: 'Add user authentication',
  column: 'In Progress',
  labels: ['feature']
});

Overrides

RoadmapProvider.createCard

---

fetchCards()

fetchCards(): Promise<readonly RoadmapCard[]>

Fetches all Jira issues matching the configured JQL query.

Returns

Promise<readonly RoadmapCard[]>

Array of roadmap cards mapped from Jira issues.

Throws

Error if authentication fails or query is invalid.

Overrides

RoadmapProvider.fetchCards

---

fetchCardsByDateRange()

fetchCardsByDateRange(filter): Promise<readonly RoadmapCard[]>

Fetches Jira issues filtered by date range.

Supports filtering by 'created' or 'updated' fields (defaults to 'updated'). Accepts Date objects or ISO 8601 strings. Results are cached for 5 minutes.

Parameters

Parameter	Type	Description
filter	DateRangeFilter	Date range criteria (startDate, endDate, dateField).

Returns

Promise<readonly RoadmapCard[]>

Array of matching cards, or empty array on error.

Example

const cards = await provider.fetchCardsByDateRange({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
  dateField: 'updated'
});

Overrides

RoadmapProvider.fetchCardsByDateRange

---

getCard()

getCard(cardId): Promise<null | RoadmapCard>

Retrieves a single Jira issue by its key.

Parameters

Parameter	Type	Description
cardId	string	Jira issue key (e.g., 'PROJ-123').

Returns

Promise<null | RoadmapCard>

RoadmapCard if found, null if not found.

Throws

Error if authentication fails or network errors occur.

Example

const card = await provider.getCard('PROJ-123');
if (card) console.log(card.title);

Overrides

RoadmapProvider.getCard

---

getColumns()

getColumns(): Promise<readonly RoadmapColumn[]>

Returns standard Jira workflow columns (Backlog, In Progress, Done).

Returns

Promise<readonly RoadmapColumn[]>

Array of column definitions.

Overrides

RoadmapProvider.getColumns

---

getIssueTypes()

getIssueTypes(): Promise<readonly string[]>

Retrieves available issue types from Jira (excludes subtasks).

Results are cached for 5 minutes. Returns standard types on failure.

Returns

Promise<readonly string[]>

Array of issue type names (e.g., ['Task', 'Story', 'Bug', 'Epic']).

Overrides

RoadmapProvider.getIssueTypes

---

getLabels()

getLabels(): Promise<readonly string[]>

Retrieves available labels from Jira.

Results are cached for 5 minutes. Returns empty array on failure.

Returns

Promise<readonly string[]>

Array of label names.

Overrides

RoadmapProvider.getLabels

---

getProviderInfo()

getProviderInfo(): Promise<ProviderInfo>

Returns provider metadata and capabilities.

Returns

Promise<ProviderInfo>

Provider information including name, version, and capabilities.

Example

const info = await provider.getProviderInfo();
console.log(info.name); // 'Jira'

Overrides

RoadmapProvider.getProviderInfo

---

getStatusMapping()

getStatusMapping(): undefined | Record<string, null | string>

Returns the configured status-to-column mapping, if any.

Returns

undefined | Record<string, null | string>

Status mapping record or undefined if using defaults.

Overrides

RoadmapProvider.getStatusMapping

---

init()

init(): Promise<void>

Initializes the provider and verifies Jira connectivity.

Returns

Promise<void>

Throws

Error if configuration is invalid or authentication fails.

Overrides

RoadmapProvider.init

---

resolveColumn()

resolveColumn(status, guildMapping?): undefined | null | string

Resolves the target column for a given provider status, checking guild overrides first.

Parameters

Parameter	Type	Description
status	string	The provider status name to map.
guildMapping?	Record<string, null | string>	Optional guild-specific column mapping overrides.

Returns

undefined | null | string

The column name to map to, or null if the status should be tracked without a forum, or undefined if no mapping found (use default).

Remarks

This helper checks guild-specific column mappings first (runtime overrides), then falls back to provider-level mappings. Returns undefined if no mapping is found, indicating the provider should use its default mapping logic.

Example

const guildMapping = getColumnMapping(guildId);
const column = this.resolveColumn('In Progress', guildMapping);
// Returns 'In Progress', null, or undefined

Inherited from

RoadmapProvider.resolveColumn

---

updateCard()

updateCard(cardId, input): Promise<UpdateCardResult>

Updates an existing Jira issue (partial update).

Only provided fields are updated. If column changes, transitions the issue to the new status. Only the first assignee is used (Jira limitation).

Parameters

Parameter	Type	Description
cardId	string	Jira issue key (e.g., 'PROJ-123').
input	UpdateCardInput	Partial card data to update.

Returns

Promise<UpdateCardResult>

UpdateCardResult with success status and updated card.

Example

const result = await provider.updateCard('PROJ-123', { column: 'Done' });
console.log(result.success);

Overrides

RoadmapProvider.updateCard

---

validateConfig()

validateConfig(config): boolean

Validates the resolved Jira configuration, emitting structured log output for any failures.

Parameters

Parameter	Type	Description
config	JiraProviderConfig	Optional override used mainly for testing.

Returns

boolean

true when the configuration satisfies the minimum requirements.

Overrides

RoadmapProvider.validateConfig