Class: abstract RoadmapProvider<TConfig>

Base class for roadmap data providers (Jira, GitHub Projects, Linear).

Remarks

Extend this class to integrate external project management systems with the roadmap plugin. Implement the abstract methods to fetch cards, columns, and provider metadata.

Example

export class JiraRoadmapProvider extends RoadmapProvider<JiraProviderConfig> {
  public async fetchCards(): Promise<RoadmapCard[]> {
    // Fetch and map Jira issues to RoadmapCard
    return [];
  }

  public async getColumns() {
    return [{ id: 'todo', name: 'To Do', order: 0 }];
  }
}

Extended by

• JiraProvider

Type Parameters

Type Parameter	Default type
TConfig extends ProviderConfig	ProviderConfig

Constructors

new RoadmapProvider()

protected new RoadmapProvider<TConfig>(config): RoadmapProvider<TConfig>

Creates a new roadmap provider instance with the supplied configuration.

Parameters

Parameter	Type	Description
config	TConfig	Provider specific configuration object.

Returns

RoadmapProvider<TConfig>

Properties

Property	Modifier	Type	Description
config	readonly	TConfig	Provider specific configuration object.

Methods

createCard()

abstract createCard(input): Promise<CreateCardResult>

Creates a new card in the external provider system.

Parameters

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

Returns

Promise<CreateCardResult>

Result containing the created card and success status.

Throws

Authentication, validation, or network errors.

Example

public async createCard(input: CreateCardInput): Promise<CreateCardResult> {
  const issue = await this.client.createIssue({
    summary: input.title,
    description: input.description,
  });
  return { card: this.mapIssueToCard(issue), success: true };
}

---

fetchCards()

abstract fetchCards(): Promise<readonly RoadmapCard[]>

Fetches all roadmap cards from the provider.

Returns

Promise<readonly RoadmapCard[]>

Array of roadmap cards.

---

fetchCardsByDateRange()?

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

Optional method to fetch cards filtered by date range (useful for reporting and activity analysis).

Parameters

Parameter	Type	Description
filter	DateRangeFilter	Date range filter with optional startDate, endDate, and dateField.

Returns

Promise<readonly RoadmapCard[]>

Cards matching the date criteria, ordered by date descending (most recent first).

Example

public async fetchCardsByDateRange(filter: DateRangeFilter): Promise<readonly RoadmapCard[]> {
  const jql = this.buildDateRangeJql(filter);
  const issues = await this.searchIssues(jql);
  return issues.map(this.mapIssueToCard);
}

---

getCard()

abstract getCard(cardId): Promise<null | RoadmapCard>

Retrieves a single card by its provider-specific ID (e.g., Jira issue key 'PROJ-123').

Parameters

Parameter	Type	Description
cardId	string	Provider-specific identifier.

Returns

Promise<null | RoadmapCard>

Card if found, null if not found.

Throws

Authentication or network errors (not for missing cards).

Example

public async getCard(cardId: string): Promise<RoadmapCard | null> {
  try {
    const issue = await this.client.getIssue(cardId);
    return this.mapIssueToCard(issue);
  } catch (error) {
    if (error.status === 404) return null;
    throw error;
  }
}

---

getColumns()

abstract getColumns(): Promise<readonly RoadmapColumn[]>

Retrieves the available roadmap columns.

Returns

Promise<readonly RoadmapColumn[]>

Array of column definitions.

Example

public async getColumns() {
  return [
    { id: 'backlog', name: 'Backlog', order: 0, archived: false },
    { id: 'done', name: 'Done', order: 3, archived: true },
  ];
}

---

getIssueTypes()

abstract getIssueTypes(): Promise<readonly string[]>

Retrieves available issue types for card creation (e.g., 'Task', 'Story', 'Bug').

Returns

Promise<readonly string[]>

Array of issue type names.

Example

public async getIssueTypes(): Promise<readonly string[]> {
  return ['Task', 'Story', 'Bug', 'Epic'];
}

---

getLabels()

abstract getLabels(): Promise<readonly string[]>

Retrieves available labels for card categorization (e.g., 'bug', 'enhancement').

Returns

Promise<readonly string[]>

Array of label names.

Example

public async getLabels(): Promise<readonly string[]> {
  return ['bug', 'enhancement', 'feature'];
}

---

getProviderInfo()

abstract getProviderInfo(): Promise<ProviderInfo>

Returns provider metadata (name, version, capabilities) for diagnostics and logging.

Returns

Promise<ProviderInfo>

Provider information.

Example

public async getProviderInfo() {
  return {
    name: 'GitHub Projects',
    version: '0.1.0',
    capabilities: ['cards', 'columns'],
  };
}

---

getStatusMapping()?

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

Optional method to get the status-to-column mapping for this provider.

Returns

undefined | Record<string, null | string>

Record mapping provider status names to column names (or null for no forum). Returns undefined if no custom mapping is configured (uses default behavior).

Remarks

This method allows providers to expose their configured status mappings. If not implemented, the provider's default mapping logic is used.

Example

public getStatusMapping(): Record<string, string | null> | undefined {
  return this.config.options?.statusMapping;
}

---

init()

init(): Promise<void>

Optional initialization hook called before the first sync. Default implementation is a no-op.

Returns

Promise<void>

Example

public override async init() {
  await this.client.authenticate();
}

---

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

---

updateCard()

abstract updateCard(cardId, input): Promise<UpdateCardResult>

Updates an existing card (partial update - only provided fields are changed).

Parameters

Parameter	Type	Description
cardId	string	Provider-specific identifier.
input	UpdateCardInput	Partial card data to update.

Returns

Promise<UpdateCardResult>

Result containing the updated card and success status.

Throws

Authentication, validation, not found, or network errors.

Example

public async updateCard(cardId: string, input: UpdateCardInput): Promise<UpdateCardResult> {
  const fields: Record<string, unknown> = {};
  if (input.title) fields.summary = input.title;
  if (input.description) fields.description = input.description;

  await this.client.updateIssue(cardId, { fields });
  const card = await this.getCard(cardId);

  return { card: card!, success: true };
}

---

validateConfig()

validateConfig(_config): boolean

Validates provider-specific configuration. Default implementation returns true.

Parameters

Parameter	Type	Description
_config	TConfig	Configuration to validate (defaults to instance config).

Returns

boolean

Whether the configuration is valid.

Example

public override validateConfig(config = this.config) {
  return Boolean(config.options?.apiToken);
}