Improved error resilience and clarity in handling Jira search operati…

…ons by introducing structured TypeScript type definitions and enhancing the searchJira function to return both search results and HTTP status codes

Signed-off-by: enaysaa [email protected]

Introduced TypeScript type definitions SearchJiraResponse and JiraQueryResults to represent Jira search responses and pagination details.
Updated the searchJira function to return search results as a SearchJiraResponse, incorporating the new types.
Enhanced error handling in the searchJira function by handling HTTP response errors and logging them appropriately.
The JiraQueryResults type outlines the structure of a paginated Jira search response, facilitating better data handling.
These changes streamline the Jira Dashboard plugin's codebase, improving error resilience and clarity in handling search operations.

.changeset/witty-jokes-hammer.md

@@ -0,0 +1,10 @@
+---
+'@axis-backstage/plugin-jira-dashboard-backend': major
+'@axis-backstage/plugin-jira-dashboard-common': minor
+---
+
+Introduced TypeScript type definitions SearchJiraResponse and JiraQueryResults to represent Jira search responses and pagination details.
+Updated the searchJira function to return search results as a SearchJiraResponse, incorporating the new types.
+The searchJira function now returns an object containing both the search results and the HTTP status code, improving error resilience and clarity in handling search operations.
+The JiraQueryResults type outlines the structure of a paginated Jira search response, facilitating better data handling.
+These changes streamline the Jira Dashboard plugin's codebase, improving error resilience and clarity in handling search operations.

plugins/jira-dashboard-backend/api-report.md

@@ -9,7 +9,7 @@ import { DiscoveryService } from '@backstage/backend-plugin-api';
 import express from 'express';
 import { HttpAuthService } from '@backstage/backend-plugin-api';
 import { IdentityService } from '@backstage/backend-plugin-api';
-import { Issue } from '@axis-backstage/plugin-jira-dashboard-common';
+import { JiraQueryResults } from '@axis-backstage/plugin-jira-dashboard-common';
 import { LoggerService } from '@backstage/backend-plugin-api';
 import { RootConfigService } from '@backstage/backend-plugin-api';
 import { TokenManagerService } from '@backstage/backend-plugin-api';
@@ -53,7 +53,7 @@ export const searchJira: (
   config: RootConfigService,
   jqlQuery: string,
   options: SearchOptions,
-) => Promise<Issue[]>;
+) => Promise<JiraQueryResults>;
 
 // @public
 export type SearchOptions = {

plugins/jira-dashboard-backend/src/api.ts

@@ -4,9 +4,11 @@ import {
   Filter,
   Issue,
   Project,
+  JiraQueryResults,
 } from '@axis-backstage/plugin-jira-dashboard-common';
 import { resolveJiraBaseUrl, resolveJiraToken } from './config';
 import { jqlQueryBuilder } from './queries';
+import { ResponseError } from '@backstage/errors';
 
 export const getProjectInfo = async (
   projectKey: string,
@@ -84,23 +86,23 @@ export type SearchOptions = {
 };
 
 /**
- * Search for Jira issues using JQL.
+ * Asynchronously searches for Jira issues using JQL.
  *
- * For more information about the available options see the API
- * documentation at:
+ * For more information about the available options, see the API documentation at:
  * https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issue-search/#api-rest-api-2-search-post
  *
- * @param config - A Backstage config
- * @param jqlQuery - A string containing the jql query.
- * @param options - Query options that will be passed on to the POST request.
- *
+ * @param config - The Backstage configuration object containing Jira base URL and token.
+ * @param jqlQuery - The JQL query string to search for Jira issues.
+ * @param options - Additional search options such as expand, fields, startAt, etc.
+ * @returns A promise that resolves to the Jira query results, including issues and total count.
+ * @throws An error if the search process fails.
  * @public
  */
 export const searchJira = async (
   config: RootConfigService,
   jqlQuery: string,
   options: SearchOptions,
-): Promise<Issue[]> => {
+): Promise<JiraQueryResults> => {
   const response = await fetch(`${resolveJiraBaseUrl(config)}search`, {
     method: 'POST',
     body: JSON.stringify({ jql: jqlQuery, ...options }),
@@ -109,8 +111,12 @@ export const searchJira = async (
       Accept: 'application/json',
       'Content-Type': 'application/json',
     },
-  }).then(resp => resp.json());
-  return response.issues;
+  });
+  if (!response.ok) {
+    throw await ResponseError.fromResponse(response);
+  }
+  const jsonResponse = await response.json();
+  return jsonResponse as JiraQueryResults;
 };
 
 export const getIssuesByComponent = async (

plugins/jira-dashboard-backend/src/service/service.ts

@@ -49,10 +49,10 @@ export const getJqlResponse = async (
 
   issuesResponse = (await cache.get(jql)) as Issue[];
 
-  if (issuesResponse) return issuesResponse as Issue[];
+  if (issuesResponse) return issuesResponse;
 
   try {
-    issuesResponse = await searchJira(config, jql, searchOptions);
+    issuesResponse = (await searchJira(config, jql, searchOptions)).issues;
     cache.set(jql, issuesResponse);
   } catch (err: any) {
     if (err.message !== 200) {

plugins/jira-dashboard-common/api-report.md

@@ -57,6 +57,19 @@ export type JiraDataResponse = {
   issues: Issue[];
 };
 
+// @public
+export type JiraQueryResults = {
+  expand: string;
+  names: object;
+  schema: object;
+  issues: Issue[];
+  total: number;
+  startAt: number;
+  maxResults: number;
+  warningMessages?: string[];
+  errorMessages?: string[];
+};
+
 // @public
 export type JiraResponse = {
   project: Project;

plugins/jira-dashboard-common/src/types.ts

@@ -78,3 +78,19 @@ export type JiraResponse = {
   project: Project;
   data: JiraDataResponse[];
 };
+
+/**
+ * Type definition for a paginated Jira search response
+ * @public
+ */
+export type JiraQueryResults = {
+  expand: string;
+  names: object;
+  schema: object;
+  issues: Issue[];
+  total: number;
+  startAt: number;
+  maxResults: number;
+  warningMessages?: string[];
+  errorMessages?: string[];
+};