Update Jira endpoint to v3

Update Jira query to return all issue fields, otherwise, no fields will
be returned.
Add ADFNode and utillty functions to format to text
Add optional filter function to filter Jira tickets
Make use of destructuring the Jira fields instead of repeatedly access
issue.field.<attribute>

Author: phong-phuong

.changeset/metal-llamas-shave.md

@@ -0,0 +1,11 @@
+---
+"@langchain/community": major
+---
+
+Update Jira document loader with updated v3 API jql endpoint
+
+Update Jira JQL query to specify fields, otherwise no fields will be returned
+
+Add option filter function
+
+Refactor to use object de-structuring of the issue fields

libs/langchain-community/src/document_loaders/web/jira.ts

@@ -122,7 +122,7 @@ export type JiraIssue = {
   fields: {
     assignee?: JiraUser;
     created: string;
-    description: string;
+    description: ADFNode;
     issuelinks: JiraIssueLink[];
     issuetype: JiraIssueType;
     labels?: string[];
@@ -151,6 +151,28 @@ export type JiraAPIResponse = {
   issues: JiraIssue[];
 };
 
+export interface ADFNode {
+  type: string;
+  text?: string;
+  content?: ADFNode[];
+}
+
+export interface ADFDocument extends ADFNode {
+  type: "doc";
+  version: number;
+  content: ADFNode[];
+}
+
+export function adfToText(adf: ADFNode | null | undefined): string {
+  if (!adf || !adf.content) return "";
+  const recur = (node: ADFNode): string => {
+    if (node.text) return node.text;
+    if (node.content) return node.content.map(recur).join("");
+    return "";
+  };
+  return recur(adf).trim();
+}
+
 /**
  * Interface representing the parameters for configuring the
  * JiraDocumentConverter.
@@ -194,88 +216,93 @@ export class JiraDocumentConverter {
   private formatIssueInfo({
     issue,
     host,
-  }: {
+    }: {
     issue: JiraIssue;
     host: string;
-  }): string {
+    }): string {
+    const {
+        project,
+        status,
+        priority,
+        issuetype,
+        creator,
+        labels,
+        created,
+        updated,
+        reporter,
+        assignee,
+        duedate,
+        timeestimate,
+        timespent,
+        resolutiondate,
+        description,
+        progress,
+        parent,
+        subtasks,
+        issuelinks,
+    } = issue.fields;
+
     let text = `Issue: ${this.formatMainIssueInfoText({ issue, host })}\n`;
-    text += `Project: ${issue.fields.project.name} (${issue.fields.project.key}, ID ${issue.fields.project.id})\n`;
-    text += `Status: ${issue.fields.status.name}\n`;
-    text += `Priority: ${issue.fields.priority.name}\n`;
-    text += `Type: ${issue.fields.issuetype.name}\n`;
-    text += `Creator: ${issue.fields.creator?.displayName}\n`;
-
-    if (issue.fields.labels && issue.fields.labels.length > 0) {
-      text += `Labels: ${issue.fields.labels.join(", ")}\n`;
+    text += `Project: ${project.name} (${project.key}, ID ${project.id})\n`;
+    text += `Status: ${status.name}\n`;
+    text += `Priority: ${priority.name}\n`;
+    text += `Type: ${issuetype.name}\n`;
+    text += `Creator: ${creator?.displayName}\n`;
+
+    if (labels?.length) {
+        text += `Labels: ${labels.join(", ")}\n`;
     }
 
-    text += `Created: ${issue.fields.created}\n`;
-    text += `Updated: ${issue.fields.updated}\n`;
+    text += `Created: ${created}\n`;
+    text += `Updated: ${updated}\n`;
 
-    if (issue.fields.reporter) {
-      text += `Reporter: ${issue.fields.reporter.displayName}\n`;
+    if (reporter) {
+        text += `Reporter: ${reporter.displayName}\n`;
     }
 
-    text += `Assignee: ${issue.fields.assignee?.displayName ?? "Unassigned"}\n`;
+    text += `Assignee: ${assignee?.displayName ?? "Unassigned"}\n`;
 
-    if (issue.fields.duedate) {
-      text += `Due Date: ${issue.fields.duedate}\n`;
+    if (duedate) {
+        text += `Due Date: ${duedate}\n`;
     }
-
-    if (issue.fields.timeestimate) {
-      text += `Time Estimate: ${issue.fields.timeestimate}\n`;
+    if (timeestimate) {
+        text += `Time Estimate: ${timeestimate}\n`;
     }
-
-    if (issue.fields.timespent) {
-      text += `Time Spent: ${issue.fields.timespent}\n`;
+    if (timespent) {
+        text += `Time Spent: ${timespent}\n`;
     }
-
-    if (issue.fields.resolutiondate) {
-      text += `Resolution Date: ${issue.fields.resolutiondate}\n`;
+    if (resolutiondate) {
+        text += `Resolution Date: ${resolutiondate}\n`;
     }
-
-    if (issue.fields.description) {
-      text += `Description: ${issue.fields.description}\n`;
+    if (description) {
+        text += `Description: ${adfToText(description)}\n`;
     }
-
-    if (issue.fields.progress?.percent) {
-      text += `Progress: ${issue.fields.progress.percent}%\n`;
+    if (progress?.percent) {
+        text += `Progress: ${progress.percent}%\n`;
     }
 
-    if (issue.fields.parent) {
-      text += `Parent Issue: ${this.formatMainIssueInfoText({
-        issue: issue.fields.parent,
-        host,
-      })}\n`;
+    if (parent) {
+        text += `Parent Issue: ${this.formatMainIssueInfoText({ issue: parent, host })}\n`;
     }
 
-    if (issue.fields.subtasks?.length > 0) {
-      text += `Subtasks:\n`;
-      issue.fields.subtasks.forEach((subtask) => {
-        text += `  - ${this.formatMainIssueInfoText({
-          issue: subtask,
-          host,
-        })}\n`;
-      });
+    if (subtasks?.length) {
+        text += `Subtasks:\n`;
+        subtasks.forEach(subtask => {
+        text += `  - ${this.formatMainIssueInfoText({ issue: subtask, host })}\n`;
+        });
     }
 
-    if (issue.fields.issuelinks?.length > 0) {
-      text += `Issue Links:\n`;
-      issue.fields.issuelinks.forEach((link) => {
+    if (issuelinks?.length) {
+        text += `Issue Links:\n`;
+        issuelinks.forEach(link => {
         text += `  - ${link.type.name}\n`;
         if (link.inwardIssue) {
-          text += `    - ${this.formatMainIssueInfoText({
-            issue: link.inwardIssue,
-            host,
-          })}\n`;
+            text += `    - ${this.formatMainIssueInfoText({ issue: link.inwardIssue, host })}\n`;
         }
         if (link.outwardIssue) {
-          text += `    - ${this.formatMainIssueInfoText({
-            issue: link.outwardIssue,
-            host,
-          })}\n`;
+            text += `    - ${this.formatMainIssueInfoText({ issue: link.outwardIssue, host })}\n`;
         }
-      });
+        });
     }
 
     return text;
@@ -321,10 +348,11 @@ export interface JiraProjectLoaderParams {
   personalAccessToken?: string;
   limitPerRequest?: number;
   createdAfter?: Date;
+  filterFn?: (issue: JiraIssue) => boolean;
 }
 
 const API_ENDPOINTS = {
-  SEARCH: "/rest/api/2/search",
+  SEARCH: "/rest/api/3/search/jql",
 };
 
 /**
@@ -343,6 +371,8 @@ export class JiraProjectLoader extends BaseDocumentLoader {
 
   private readonly createdAfter?: Date;
 
+  private readonly filterFn?: (issue: JiraIssue) => boolean;
+
   private readonly documentConverter: JiraDocumentConverter;
 
   private readonly personalAccessToken?: string;
@@ -355,6 +385,7 @@ export class JiraProjectLoader extends BaseDocumentLoader {
     limitPerRequest = 100,
     createdAfter,
     personalAccessToken,
+    filterFn,
   }: JiraProjectLoaderParams) {
     super();
     this.host = host;
@@ -365,6 +396,7 @@ export class JiraProjectLoader extends BaseDocumentLoader {
     this.createdAfter = createdAfter;
     this.documentConverter = new JiraDocumentConverter({ host, projectKey });
     this.personalAccessToken = personalAccessToken;
+    this.filterFn = filterFn;
   }
 
   private buildAuthorizationHeader(): string {
@@ -379,7 +411,13 @@ export class JiraProjectLoader extends BaseDocumentLoader {
   public async load(): Promise<Document[]> {
     try {
       const allJiraIssues = await this.loadAsIssues();
-      return this.documentConverter.convertToDocuments(allJiraIssues);
+      const filtered = allJiraIssues.filter(issue => {
+      if (this.filterFn) {
+        return this.filterFn(issue);
+      }
+      return true;
+    });  
+      return this.documentConverter.convertToDocuments(filtered);
     } catch (error) {
       console.error("Error:", error);
       return [];
@@ -416,19 +454,22 @@ export class JiraProjectLoader extends BaseDocumentLoader {
       try {
         const jqlProps = [
           `project=${this.projectKey}`,
-          ...(createdAfterAsString ? [`created>=${createdAfterAsString}`] : []),
+          ...(createdAfterAsString ? [`created>= "${createdAfterAsString}"`] : []),
         ];
+        const jql = `${jqlProps.join(" AND ")} ORDER BY created ASC, key ASC`;
+
         const params = new URLSearchParams({
-          jql: jqlProps.join(" AND "),
+          jql,
           startAt: `${startAt}`,
           maxResults: `${this.limitPerRequest}`,
+          fields: '*all',
         });
         const pageUrl = `${url}?${params}`;
 
         const options = {
           method: "GET",
           headers: {
-            Authorization: authorizationHeader,
+           Authorization: authorizationHeader,
             Accept: "application/json",
           },
         };
@@ -438,12 +479,22 @@ export class JiraProjectLoader extends BaseDocumentLoader {
 
         if (!data.issues || data.issues.length === 0) break;
 
-        yield data.issues;
+        const allIssues = [];
+        for (const issue of data.issues) {
+          allIssues.push(issue);
+        }
+
+        if (allIssues.length > 0) yield allIssues;
+
         startAt += this.limitPerRequest;
+
+        if (data.issues.length < this.limitPerRequest) break;
+
       } catch (error) {
-        console.error(error);
+        console.error("Error fetching Jira issues:", error);
         yield [];
+        break;
       }
     }
   }
-}
+}