@shipfox/api-integration-jira 11.0.0 → 12.1.0

package/src/core/agent-tools-provider.ts

@@ -0,0 +1,175 @@
+import type {
+  AgentToolCatalogEntry,
+  AgentToolSession,
+  AgentToolsProvider,
+  IntegrationConnection,
+  OpenAgentToolsSessionInput,
+} from '@shipfox/api-integration-spi';
+import type {JiraAgentToolResponse, JiraAgentToolsClient} from '#api/client.js';
+import type {JiraTokenStore} from '#core/tokens.js';
+import {
+  JIRA_TOOL_OPERATIONS,
+  type JiraAgentToolRequiredScope,
+  jiraAgentToolCatalog,
+  jiraAgentToolSelectionCatalog,
+} from './agent-tools.js';
+import {JiraIntegrationProviderError} from './errors.js';
+
+type JiraIntegrationConnection = IntegrationConnection<'jira'>;
+
+export type JiraToolCallResult = {
+  isError?: boolean | undefined;
+  content: readonly {type: 'text'; text: string}[];
+  structuredContent?: Record<string, unknown> | undefined;
+};
+
+export interface JiraAgentToolsProviderOptions {
+  jira: Pick<JiraAgentToolsClient, 'request'>;
+  tokenStore: Pick<JiraTokenStore, 'getAccessToken'>;
+}
+
+export class JiraAgentToolsProvider
+  implements
+    AgentToolsProvider<
+      JiraIntegrationConnection,
+      JiraAgentToolRequiredScope,
+      unknown,
+      JiraToolCallResult
+    >
+{
+  constructor(private readonly options: JiraAgentToolsProviderOptions) {}
+
+  catalog() {
+    return jiraAgentToolCatalog;
+  }
+
+  selectionCatalog() {
+    return jiraAgentToolSelectionCatalog;
+  }
+
+  async openSession(
+    input: OpenAgentToolsSessionInput<
+      JiraIntegrationConnection,
+      JiraAgentToolRequiredScope,
+      unknown
+    >,
+  ): Promise<AgentToolSession<JiraToolCallResult>> {
+    const accessToken = await this.options.tokenStore.getAccessToken({
+      connectionId: input.connection.id,
+    });
+    const cloudId = input.connection.externalAccountId;
+
+    return {
+      call: async (call) => {
+        const tool = input.tools.find((candidate) => candidate.id === call.toolId);
+        if (!tool) return jiraToolError(`Unknown Jira tool: ${call.toolId}`);
+
+        const operation = JIRA_TOOL_OPERATIONS[call.toolId as keyof typeof JIRA_TOOL_OPERATIONS];
+        if (!operation) return jiraToolError(`Unknown Jira tool: ${call.toolId}`);
+
+        const missingParameter = missingRequiredParameter(tool, call.arguments);
+        if (missingParameter) {
+          return jiraToolError(`Missing required parameter: ${missingParameter}`);
+        }
+
+        let response: JiraAgentToolResponse;
+        try {
+          response = await this.options.jira.request({
+            accessToken,
+            cloudId,
+            method: operation.method,
+            path: operation.path(call.arguments),
+            ...(operation.query === undefined ? {} : {query: operation.query(call.arguments)}),
+            ...(operation.body === undefined ? {} : {body: operation.body(call.arguments)}),
+            operation: call.toolId,
+          });
+        } catch (error) {
+          if (error instanceof JiraIntegrationProviderError) {
+            return jiraToolError(error.message, {
+              code: error.reason,
+              retryAfterSeconds: error.retryAfterSeconds,
+            });
+          }
+          throw error;
+        }
+
+        if (response.status === 400 || response.status === 404) {
+          return jiraRequestError(
+            response.body,
+            response.status === 404 ? 'Jira resource was not found' : 'Jira request was rejected',
+          );
+        }
+        if (response.status < 200 || response.status >= 300) {
+          return jiraToolError(`Jira request returned HTTP ${response.status}`);
+        }
+        return jiraToolResult(response.body, response.status);
+      },
+      close: () => Promise.resolve(),
+    };
+  }
+}
+
+function missingRequiredParameter(
+  tool: AgentToolCatalogEntry<JiraAgentToolRequiredScope>,
+  args: Record<string, unknown>,
+): string | undefined {
+  const required = tool.inputSchema.required;
+  if (!Array.isArray(required)) return undefined;
+  return required.find(
+    (parameter) => typeof parameter === 'string' && args[parameter] === undefined,
+  );
+}
+
+function jiraToolResult(body: unknown, status: number): JiraToolCallResult {
+  const structuredContent = body === undefined ? {status} : isRecord(body) ? body : {result: body};
+  return {
+    content: [{type: 'text', text: JSON.stringify(structuredContent)}],
+    structuredContent,
+  };
+}
+
+function jiraRequestError(body: unknown, fallbackMessage: string): JiraToolCallResult {
+  return jiraToolError(jiraErrorMessage(body, fallbackMessage));
+}
+
+function jiraErrorMessage(body: unknown, fallbackMessage: string): string {
+  if (typeof body === 'string' && body.length > 0) return body;
+  if (!isRecord(body)) return fallbackMessage;
+
+  const errorMessages = body.errorMessages;
+  if (Array.isArray(errorMessages)) {
+    const message = errorMessages.filter((value): value is string => typeof value === 'string');
+    if (message.length > 0) return message.join('; ');
+  }
+  if (typeof body.message === 'string' && body.message.length > 0) return body.message;
+  const errors = body.errors;
+  if (isRecord(errors)) {
+    const messages = Object.entries(errors).filter(
+      (entry): entry is [string, string] => typeof entry[1] === 'string',
+    );
+    if (messages.length > 0)
+      return messages.map(([field, message]) => `${field}: ${message}`).join('; ');
+  }
+  return fallbackMessage;
+}
+
+function jiraToolError(
+  message: string,
+  options: {code?: string | undefined; retryAfterSeconds?: number | undefined} = {},
+): JiraToolCallResult {
+  const structuredContent = {
+    ...(options.code === undefined ? {} : {code: options.code}),
+    ...(options.retryAfterSeconds === undefined
+      ? {}
+      : {retryAfterSeconds: options.retryAfterSeconds}),
+  };
+  return {
+    isError: true,
+    content: [{type: 'text', text: message}],
+    ...(Object.keys(structuredContent).length === 0 ? {} : {structuredContent}),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/core/agent-tools.ts

@@ -0,0 +1,450 @@
+import type {
+  JiraAgentToolId,
+  JiraAgentToolRequiredScope,
+  JiraAgentToolCatalogEntry as JiraDtoAgentToolCatalogEntry,
+} from '@shipfox/api-integration-jira-dto';
+import type {
+  AgentToolCatalogEntry,
+  AgentToolJsonSchema,
+  AgentToolSelectionCatalog,
+  AgentToolSelector,
+} from '@shipfox/api-integration-spi';
+import type {JiraAgentToolHttpMethod, JiraAgentToolQueryValue} from '#api/client.js';
+
+export type JiraAgentToolCatalogEntry = JiraDtoAgentToolCatalogEntry;
+export type {JiraAgentToolId, JiraAgentToolRequiredScope};
+
+interface JiraAgentToolCatalogInput {
+  id: JiraAgentToolId;
+  description: string;
+  sensitivity: 'read' | 'write';
+  sensitive: boolean;
+  requiredScope: JiraAgentToolRequiredScope;
+  inputSchema: AgentToolJsonSchema;
+}
+
+const issueIdOrKeySchema = stringSchema('Jira issue ID or key, such as ENG-123');
+const projectIdOrKeySchema = stringSchema('Jira project ID or key, such as ENG');
+const fieldsSchema = recordSchema('Jira issue fields keyed by their REST API field name');
+const updateSchema = recordSchema('Jira issue field update operations');
+const fieldNamesSchema = arraySchema(stringSchema('Jira field name'));
+const propertiesSchema = arraySchema(stringSchema('Jira issue property key'));
+
+export const jiraAgentToolCatalog = [
+  tool({
+    id: 'get_issue',
+    description: 'Retrieve a Jira issue by its ID or key.',
+    sensitivity: 'read',
+    sensitive: false,
+    requiredScope: 'read',
+    inputSchema: objectSchema(
+      {
+        idOrKey: issueIdOrKeySchema,
+        fields: fieldNamesSchema,
+        fieldsByKeys: booleanSchema('Interpret fields by their keys instead of IDs'),
+        expand: stringSchema('Comma-separated Jira issue expansions'),
+        properties: propertiesSchema,
+        updateHistory: booleanSchema('Record this issue as viewed by the authorizing user'),
+      },
+      ['idOrKey'],
+    ),
+  }),
+  tool({
+    id: 'search_issues',
+    description: 'Search Jira issues with a JQL query.',
+    sensitivity: 'read',
+    sensitive: false,
+    requiredScope: 'read',
+    inputSchema: objectSchema(
+      {
+        jql: stringSchema('Jira Query Language expression'),
+        maxResults: integerSchema('Maximum number of issues to return'),
+        nextPageToken: stringSchema('Pagination token from a previous search'),
+        fields: fieldNamesSchema,
+        fieldsByKeys: booleanSchema('Interpret fields by their keys instead of IDs'),
+        expand: stringSchema('Comma-separated Jira issue expansions'),
+        properties: propertiesSchema,
+        reconcileIssues: arraySchema(integerSchema('Issue ID to reconcile for read-after-write')),
+      },
+      ['jql'],
+    ),
+  }),
+  tool({
+    id: 'get_issue_comments',
+    description: 'List the comments on a Jira issue.',
+    sensitivity: 'read',
+    sensitive: false,
+    requiredScope: 'read',
+    inputSchema: objectSchema(
+      {
+        idOrKey: issueIdOrKeySchema,
+        startAt: integerSchema('Zero-based comment offset'),
+        maxResults: integerSchema('Maximum number of comments to return'),
+        orderBy: stringSchema('Comment ordering expression'),
+        expand: stringSchema('Comma-separated Jira comment expansions'),
+      },
+      ['idOrKey'],
+    ),
+  }),
+  tool({
+    id: 'get_issue_transitions',
+    description: 'List the workflow transitions available for a Jira issue.',
+    sensitivity: 'read',
+    sensitive: false,
+    requiredScope: 'read',
+    inputSchema: objectSchema(
+      {
+        idOrKey: issueIdOrKeySchema,
+        expand: stringSchema('Comma-separated transition expansions, such as transitions.fields'),
+      },
+      ['idOrKey'],
+    ),
+  }),
+  tool({
+    id: 'get_project',
+    description: 'Retrieve a Jira project by its ID or key.',
+    sensitivity: 'read',
+    sensitive: false,
+    requiredScope: 'read',
+    inputSchema: objectSchema(
+      {
+        idOrKey: projectIdOrKeySchema,
+        expand: stringSchema('Comma-separated Jira project expansions'),
+        properties: propertiesSchema,
+      },
+      ['idOrKey'],
+    ),
+  }),
+  tool({
+    id: 'get_user',
+    description: 'Retrieve a Jira user by Atlassian account ID.',
+    sensitivity: 'read',
+    sensitive: false,
+    requiredScope: 'read',
+    inputSchema: objectSchema(
+      {
+        accountId: stringSchema('Atlassian account ID'),
+        expand: stringSchema('Comma-separated Jira user expansions'),
+      },
+      ['accountId'],
+    ),
+  }),
+  tool({
+    id: 'create_issue',
+    description:
+      'Create a Jira issue using Jira REST issue fields. If both a project key and project ID or both an issue type name and issue type ID are supplied, the ID takes precedence.',
+    sensitivity: 'write',
+    sensitive: false,
+    requiredScope: 'write',
+    inputSchema: objectSchema(
+      {
+        projectKey: stringSchema(
+          'Jira project key; projectId takes precedence if both are supplied',
+        ),
+        projectId: stringSchema('Jira project ID; takes precedence over projectKey'),
+        summary: stringSchema('Issue summary'),
+        issueType: stringSchema(
+          'Issue type name; issueTypeId takes precedence if both are supplied',
+        ),
+        issueTypeId: stringSchema('Issue type ID; takes precedence over issueType'),
+        assigneeAccountId: stringSchema('Atlassian account ID to assign'),
+        priority: stringSchema('Jira priority name'),
+        labels: arraySchema(stringSchema('Jira label')),
+        body: stringSchema('Plain-text issue description'),
+        fields: fieldsSchema,
+        update: updateSchema,
+      },
+      ['summary'],
+    ),
+  }),
+  tool({
+    id: 'update_issue',
+    description: 'Update a Jira issue using Jira REST issue fields.',
+    sensitivity: 'write',
+    sensitive: false,
+    requiredScope: 'write',
+    inputSchema: objectSchema(
+      {
+        idOrKey: issueIdOrKeySchema,
+        summary: stringSchema('Replacement issue summary'),
+        issueType: stringSchema(
+          'Replacement issue type name; issueTypeId takes precedence if both are supplied',
+        ),
+        issueTypeId: stringSchema('Replacement issue type ID; takes precedence over issueType'),
+        assigneeAccountId: stringSchema('Atlassian account ID to assign'),
+        priority: stringSchema('Replacement Jira priority name'),
+        labels: arraySchema(stringSchema('Replacement Jira labels')),
+        body: stringSchema('Plain-text replacement issue description'),
+        fields: fieldsSchema,
+        update: updateSchema,
+      },
+      ['idOrKey'],
+    ),
+  }),
+  tool({
+    id: 'add_comment',
+    description: 'Add a plain-text comment to a Jira issue.',
+    sensitivity: 'write',
+    sensitive: false,
+    requiredScope: 'write',
+    inputSchema: objectSchema(
+      {
+        idOrKey: issueIdOrKeySchema,
+        body: stringSchema('Plain-text comment body'),
+      },
+      ['idOrKey', 'body'],
+    ),
+  }),
+  tool({
+    id: 'transition_issue',
+    description: 'Move a Jira issue through a workflow transition.',
+    sensitivity: 'write',
+    sensitive: false,
+    requiredScope: 'write',
+    inputSchema: objectSchema(
+      {
+        idOrKey: issueIdOrKeySchema,
+        transitionId: stringSchema('Jira workflow transition ID'),
+        fields: fieldsSchema,
+        update: updateSchema,
+      },
+      ['idOrKey', 'transitionId'],
+    ),
+  }),
+  tool({
+    id: 'assign_issue',
+    description: 'Assign or unassign a Jira issue by Atlassian account ID.',
+    sensitivity: 'write',
+    sensitive: false,
+    requiredScope: 'write',
+    inputSchema: objectSchema(
+      {
+        idOrKey: issueIdOrKeySchema,
+        accountId: nullableStringSchema('Atlassian account ID, or null to unassign'),
+      },
+      ['idOrKey', 'accountId'],
+    ),
+  }),
+] as const satisfies readonly JiraAgentToolCatalogEntry[];
+
+export const jiraAgentToolSelectionCatalog =
+  buildJiraAgentToolSelectionCatalog(jiraAgentToolCatalog);
+
+export interface JiraToolOperation {
+  method: JiraAgentToolHttpMethod;
+  path: (args: Record<string, unknown>) => string;
+  query?: ((args: Record<string, unknown>) => Record<string, JiraAgentToolQueryValue>) | undefined;
+  body?: ((args: Record<string, unknown>) => unknown) | undefined;
+}
+
+export const JIRA_TOOL_OPERATIONS: Record<JiraAgentToolId, JiraToolOperation> = {
+  get_issue: {
+    method: 'GET',
+    path: (args) => issuePath(args),
+    query: (args) =>
+      definedArguments(args, ['fields', 'fieldsByKeys', 'expand', 'properties', 'updateHistory']),
+  },
+  search_issues: {
+    method: 'POST',
+    path: () => '/search/jql',
+    body: (args) =>
+      definedArguments(args, [
+        'jql',
+        'maxResults',
+        'nextPageToken',
+        'fields',
+        'fieldsByKeys',
+        'expand',
+        'properties',
+        'reconcileIssues',
+      ]),
+  },
+  get_issue_comments: {
+    method: 'GET',
+    path: (args) => issuePath(args, 'comment'),
+    query: (args) => definedArguments(args, ['startAt', 'maxResults', 'orderBy', 'expand']),
+  },
+  get_issue_transitions: {
+    method: 'GET',
+    path: (args) => issuePath(args, 'transitions'),
+    query: (args) => definedArguments(args, ['expand']),
+  },
+  get_project: {
+    method: 'GET',
+    path: (args) => `/project/${encodeURIComponent(stringArgument(args, 'idOrKey'))}`,
+    query: (args) => definedArguments(args, ['expand', 'properties']),
+  },
+  get_user: {
+    method: 'GET',
+    path: () => '/user',
+    query: (args) => definedArguments(args, ['accountId', 'expand']),
+  },
+  create_issue: {
+    method: 'POST',
+    path: () => '/issue',
+    body: (args) => issueWriteBody(args),
+  },
+  update_issue: {
+    method: 'PUT',
+    path: (args) => issuePath(args),
+    body: (args) => issueWriteBody(args),
+  },
+  add_comment: {
+    method: 'POST',
+    path: (args) => issuePath(args, 'comment'),
+    body: (args) => ({body: jiraPlainTextToAdf(stringArgument(args, 'body'))}),
+  },
+  transition_issue: {
+    method: 'POST',
+    path: (args) => issuePath(args, 'transitions'),
+    body: (args) => transitionBody(args),
+  },
+  assign_issue: {
+    method: 'PUT',
+    path: (args) => issuePath(args, 'assignee'),
+    body: (args) => ({accountId: args.accountId}),
+  },
+};
+
+export function jiraPlainTextToAdf(body: string): Record<string, unknown> {
+  return {
+    type: 'doc',
+    version: 1,
+    content: [
+      {
+        type: 'paragraph',
+        content: [{type: 'text', text: body}],
+      },
+    ],
+  };
+}
+
+function buildJiraAgentToolSelectionCatalog(
+  catalog: readonly AgentToolCatalogEntry<JiraAgentToolRequiredScope>[],
+): AgentToolSelectionCatalog {
+  return {
+    selectors: catalog.map(
+      (entry): AgentToolSelector => ({
+        token: entry.id,
+        kind: 'standalone',
+        sensitivity: entry.sensitivity,
+        sensitive: entry.sensitive,
+      }),
+    ),
+  };
+}
+
+function issuePath(args: Record<string, unknown>, suffix = ''): string {
+  return `/issue/${encodeURIComponent(stringArgument(args, 'idOrKey'))}${suffix ? `/${suffix}` : ''}`;
+}
+
+function issueWriteBody(args: Record<string, unknown>): Record<string, unknown> {
+  const body: Record<string, unknown> = {};
+  const fields = issueFields(args);
+  if (Object.keys(fields).length > 0) body.fields = fields;
+  if (isRecord(args.update)) body.update = args.update;
+  return body;
+}
+
+function issueFields(args: Record<string, unknown>): Record<string, unknown> {
+  const fields = isRecord(args.fields) ? {...args.fields} : {};
+  const projectKey = stringArgumentOrUndefined(args, 'projectKey');
+  const projectId = stringArgumentOrUndefined(args, 'projectId');
+  const summary = stringArgumentOrUndefined(args, 'summary');
+  const issueType = stringArgumentOrUndefined(args, 'issueType');
+  const issueTypeId = stringArgumentOrUndefined(args, 'issueTypeId');
+  const assigneeAccountId = args.assigneeAccountId;
+  const priority = stringArgumentOrUndefined(args, 'priority');
+
+  if (projectKey !== undefined) fields.project = {key: projectKey};
+  if (projectId !== undefined) fields.project = {id: projectId};
+  if (summary !== undefined) fields.summary = summary;
+  if (issueType !== undefined) fields.issuetype = {name: issueType};
+  if (issueTypeId !== undefined) fields.issuetype = {id: issueTypeId};
+  if (typeof assigneeAccountId === 'string') fields.assignee = {accountId: assigneeAccountId};
+  if (priority !== undefined) fields.priority = {name: priority};
+  if (Array.isArray(args.labels)) fields.labels = args.labels;
+  if (typeof args.body === 'string') fields.description = jiraPlainTextToAdf(args.body);
+
+  return fields;
+}
+
+function transitionBody(args: Record<string, unknown>): Record<string, unknown> {
+  const body: Record<string, unknown> = {
+    transition: {id: stringArgument(args, 'transitionId')},
+  };
+  const fields = isRecord(args.fields) ? args.fields : undefined;
+  if (fields !== undefined) body.fields = fields;
+  if (isRecord(args.update)) body.update = args.update;
+  return body;
+}
+
+function definedArguments(
+  args: Record<string, unknown>,
+  names: readonly string[],
+): Record<string, JiraAgentToolQueryValue> {
+  return Object.fromEntries(
+    names.map((name) => [name, args[name]] as const).filter(([, value]) => value !== undefined),
+  ) as Record<string, JiraAgentToolQueryValue>;
+}
+
+function stringArgument(args: Record<string, unknown>, name: string): string {
+  const value = args[name];
+  return typeof value === 'string' ? value : String(value ?? '');
+}
+
+function stringArgumentOrUndefined(
+  args: Record<string, unknown>,
+  name: string,
+): string | undefined {
+  const value = args[name];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function tool(input: JiraAgentToolCatalogInput): JiraAgentToolCatalogEntry {
+  return input;
+}
+
+function objectSchema(
+  properties: Record<string, AgentToolJsonSchema>,
+  required: string[] = [],
+): AgentToolJsonSchema {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    properties,
+    ...(required.length > 0 ? {required} : {}),
+  };
+}
+
+function recordSchema(description?: string): AgentToolJsonSchema {
+  return {
+    type: 'object',
+    additionalProperties: true,
+    ...(description === undefined ? {} : {description}),
+  };
+}
+
+function stringSchema(description?: string): AgentToolJsonSchema {
+  return {type: 'string', ...(description === undefined ? {} : {description})};
+}
+
+function nullableStringSchema(description?: string): AgentToolJsonSchema {
+  return {type: ['string', 'null'], ...(description === undefined ? {} : {description})};
+}
+
+function integerSchema(description?: string): AgentToolJsonSchema {
+  return {type: 'integer', ...(description === undefined ? {} : {description})};
+}
+
+function booleanSchema(description?: string): AgentToolJsonSchema {
+  return {type: 'boolean', ...(description === undefined ? {} : {description})};
+}
+
+function arraySchema(items: AgentToolJsonSchema): AgentToolJsonSchema {
+  return {type: 'array', items};
+}