@shipfox/api-integration-jira 12.0.0 → 12.1.1

package/src/api/client.ts

@@ -6,6 +6,7 @@ import {JiraIntegrationProviderError} from '#core/errors.js';
 
 const JIRA_API_TIMEOUT_MS = 10_000;
 const SCOPE_SEPARATOR_RE = /[,\s]+/;
+const TRAILING_SLASHES_RE = /\/+$/;
 export const JIRA_DYNAMIC_WEBHOOK_EVENTS = jiraWebhookEventNames;
 export const JIRA_DYNAMIC_WEBHOOK_JQL = '';
 
@@ -31,6 +32,34 @@ export interface JiraDynamicWebhookRegistration {
   webhookId: number;
 }
 
+export type JiraAgentToolHttpMethod = 'GET' | 'POST' | 'PUT';
+
+export type JiraAgentToolQueryValue =
+  | string
+  | number
+  | boolean
+  | readonly (string | number)[]
+  | undefined;
+
+export interface JiraAgentToolRequest {
+  accessToken: string;
+  cloudId: string;
+  method: JiraAgentToolHttpMethod;
+  path: string;
+  query?: Record<string, JiraAgentToolQueryValue> | undefined;
+  body?: unknown;
+  operation?: string | undefined;
+}
+
+export interface JiraAgentToolResponse {
+  status: number;
+  body: unknown;
+}
+
+export interface JiraAgentToolsClient {
+  request(input: JiraAgentToolRequest): Promise<JiraAgentToolResponse>;
+}
+
 export interface JiraApiClient {
   exchangeAuthorizationCode(input: {code: string}): Promise<JiraAuthorization>;
   refreshAccessToken(input: {refreshToken: string}): Promise<JiraAuthorization>;
@@ -70,6 +99,8 @@ interface JiraDynamicWebhookRegistrationResponse {
   webhookRegistrationResult?: unknown;
 }
 
+const JIRA_REFRESH_TOKEN_TERMINAL_ERROR_CODES = new Set(['invalid_grant', 'unauthorized_client']);
+
 export function createJiraApiClient(): JiraApiClient {
   return {
     async exchangeAuthorizationCode(input) {
@@ -170,6 +201,67 @@ export function createJiraApiClient(): JiraApiClient {
   };
 }
 
+export function createJiraAgentToolsClient(): JiraAgentToolsClient {
+  return {request: requestJiraRest};
+}
+
+async function requestJiraRest(input: JiraAgentToolRequest): Promise<JiraAgentToolResponse> {
+  return await mapJiraError(input.operation ?? 'agent-tool', async () => {
+    try {
+      const response = await ky(jiraRestUrl(input.cloudId, input.path), {
+        method: input.method,
+        headers: {authorization: `Bearer ${input.accessToken}`},
+        ...(input.query === undefined ? {} : {searchParams: jiraQueryParams(input.query)}),
+        ...(input.body === undefined ? {} : {json: input.body}),
+        timeout: JIRA_API_TIMEOUT_MS,
+      });
+      return {status: response.status, body: await readJiraResponseBody(response)};
+    } catch (error) {
+      if (
+        error instanceof HTTPError &&
+        (error.response.status === 400 || error.response.status === 404)
+      ) {
+        return {
+          status: error.response.status,
+          body: await readJiraResponseBody(error.response),
+        };
+      }
+      throw error;
+    }
+  });
+}
+
+function jiraRestUrl(cloudId: string, path: string): string {
+  const baseUrl = config.JIRA_API_BASE_URL.replace(TRAILING_SLASHES_RE, '');
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  return `${baseUrl}/ex/jira/${encodeURIComponent(cloudId)}/rest/api/3${normalizedPath}`;
+}
+
+function jiraQueryParams(
+  query: Record<string, JiraAgentToolQueryValue>,
+): URLSearchParams | undefined {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) params.append(key, String(item));
+      continue;
+    }
+    params.set(key, String(value));
+  }
+  return params.size > 0 ? params : undefined;
+}
+
+async function readJiraResponseBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (text.length === 0) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
 function parseDynamicWebhookRegistration(
   body: JiraDynamicWebhookRegistrationResponse,
 ): JiraDynamicWebhookRegistration {
@@ -190,7 +282,21 @@ function parseDynamicWebhookRegistration(
     createdWebhookId?: unknown;
     errors?: unknown;
   };
-  if (errors !== undefined && (!Array.isArray(errors) || errors.length > 0)) {
+  if (errors !== undefined && !Array.isArray(errors)) {
+    throw malformed('Jira webhook registration returned errors');
+  }
+  if (Array.isArray(errors) && errors.length > 0) {
+    logger().warn(
+      {
+        operation: 'register-dynamic-webhook',
+        providerErrors: errors
+          .filter((error): error is string => typeof error === 'string')
+          .slice(0, 5)
+          .map((error) => error.slice(0, 500)),
+        providerErrorCount: errors.length,
+      },
+      'Jira dynamic webhook registration rejected',
+    );
     throw malformed('Jira webhook registration returned errors');
   }
   if (
@@ -272,6 +378,15 @@ export async function mapJiraError<T>(operation: string, request: () => Promise<
       if (status === 401 || status === 403) {
         throw new JiraIntegrationProviderError('access-denied', 'Jira request was rejected');
       }
+      if (status === 400 && operation === 'refresh-access-token') {
+        const errorCode = readJiraOAuthErrorCode(error.data);
+        if (errorCode && JIRA_REFRESH_TOKEN_TERMINAL_ERROR_CODES.has(errorCode)) {
+          throw new JiraIntegrationProviderError(
+            'access-denied',
+            'Jira refresh token was rejected; reconnect is required',
+          );
+        }
+      }
       throw malformed('Jira request was rejected');
     }
     if (error instanceof TimeoutError) {
@@ -290,6 +405,12 @@ function malformed(message: string): JiraIntegrationProviderError {
   return new JiraIntegrationProviderError('malformed-provider-response', message);
 }
 
+function readJiraOAuthErrorCode(data: unknown): string | undefined {
+  if (!data || typeof data !== 'object') return undefined;
+  const errorCode = (data as {error?: unknown}).error;
+  return typeof errorCode === 'string' ? errorCode : undefined;
+}
+
 function retryAfterSeconds(headers: Headers): number | undefined {
   const value = headers.get('retry-after');
   if (!value) return undefined;

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

@@ -0,0 +1,299 @@
+import type {IntegrationConnection} from '@shipfox/api-integration-spi';
+import type {JiraAgentToolsClient} from '#api/client.js';
+import {
+  type JiraAgentToolId,
+  jiraAgentToolCatalog,
+  jiraAgentToolSelectionCatalog,
+  jiraPlainTextToAdf,
+} from '#core/agent-tools.js';
+import {JiraAgentToolsProvider} from '#core/agent-tools-provider.js';
+import {JiraIntegrationProviderError} from '#core/errors.js';
+
+function jiraConnection(
+  overrides: Partial<IntegrationConnection<'jira'>> = {},
+): IntegrationConnection<'jira'> {
+  const now = new Date();
+  return {
+    id: 'jira-connection-1',
+    workspaceId: 'workspace-1',
+    provider: 'jira',
+    externalAccountId: 'cloud-1',
+    slug: 'jira-acme',
+    displayName: 'Jira Acme',
+    lifecycleStatus: 'active',
+    createdAt: now,
+    updatedAt: now,
+    ...overrides,
+  };
+}
+
+function catalogTool(id: JiraAgentToolId) {
+  const tool = jiraAgentToolCatalog.find((candidate) => candidate.id === id);
+  if (!tool) throw new Error(`Unknown test tool: ${id}`);
+  return tool;
+}
+
+function providerOptions(
+  request: JiraAgentToolsClient['request'] = async () => ({status: 200, body: {ok: true}}),
+) {
+  return {
+    jira: {request: vi.fn(request)},
+    tokenStore: {getAccessToken: vi.fn().mockResolvedValue('access-token')},
+  };
+}
+
+async function openSession(
+  options: ReturnType<typeof providerOptions>,
+  toolIds: JiraAgentToolId[],
+  connection = jiraConnection(),
+) {
+  const provider = new JiraAgentToolsProvider(options);
+  return await provider.openSession({
+    connection,
+    tools: toolIds.map(catalogTool),
+    scope: {provider: 'jira'},
+  });
+}
+
+describe('JiraAgentToolsProvider', () => {
+  it('returns the Jira agent tools catalogs', () => {
+    const provider = new JiraAgentToolsProvider(providerOptions());
+
+    expect(provider.catalog()).toBe(jiraAgentToolCatalog);
+    expect(provider.selectionCatalog()).toBe(jiraAgentToolSelectionCatalog);
+    expect(provider.catalog().map((tool) => [tool.id, tool.sensitivity, tool.sensitive])).toEqual([
+      ['get_issue', 'read', false],
+      ['search_issues', 'read', false],
+      ['get_issue_comments', 'read', false],
+      ['get_issue_transitions', 'read', false],
+      ['get_project', 'read', false],
+      ['get_user', 'read', false],
+      ['create_issue', 'write', false],
+      ['update_issue', 'write', false],
+      ['add_comment', 'write', false],
+      ['transition_issue', 'write', false],
+      ['assign_issue', 'write', false],
+    ]);
+  });
+
+  it('reads the stored token before opening a session', async () => {
+    const options = providerOptions();
+    const provider = new JiraAgentToolsProvider(options);
+
+    await provider.openSession({
+      connection: jiraConnection({id: 'jira-connection-7'}),
+      tools: [],
+      scope: {provider: 'jira'},
+    });
+
+    expect(options.tokenStore.getAccessToken).toHaveBeenCalledWith({
+      connectionId: 'jira-connection-7',
+    });
+  });
+
+  it('dispatches a read request with the cloud id and returns structured content', async () => {
+    const body = {id: '1004', key: 'ENG-1004', fields: {summary: 'Jira tools'}};
+    const options = providerOptions(async () => ({status: 200, body}));
+    const session = await openSession(options, ['get_issue']);
+
+    const result = await session.call({
+      toolId: 'get_issue',
+      arguments: {idOrKey: 'ENG-1004', fields: ['summary']},
+    });
+
+    expect(options.jira.request).toHaveBeenCalledWith({
+      accessToken: 'access-token',
+      cloudId: 'cloud-1',
+      method: 'GET',
+      path: '/issue/ENG-1004',
+      query: {fields: ['summary']},
+      operation: 'get_issue',
+    });
+    expect(result).toEqual({
+      content: [{type: 'text', text: JSON.stringify(body)}],
+      structuredContent: body,
+    });
+  });
+
+  it('wraps add-comment text in the minimal Jira ADF document', async () => {
+    const options = providerOptions();
+    const session = await openSession(options, ['add_comment']);
+
+    await session.call({
+      toolId: 'add_comment',
+      arguments: {idOrKey: 'ENG-1004', body: 'The adapter is ready.'},
+    });
+
+    expect(options.jira.request).toHaveBeenCalledWith({
+      accessToken: 'access-token',
+      cloudId: 'cloud-1',
+      method: 'POST',
+      path: '/issue/ENG-1004/comment',
+      body: {body: jiraPlainTextToAdf('The adapter is ready.')},
+      operation: 'add_comment',
+    });
+  });
+
+  it('wraps create and update issue descriptions in ADF', async () => {
+    const options = providerOptions();
+    const createSession = await openSession(options, ['create_issue']);
+    const updateSession = await openSession(options, ['update_issue']);
+
+    await createSession.call({
+      toolId: 'create_issue',
+      arguments: {
+        projectKey: 'ENG',
+        summary: 'New issue',
+        issueType: 'Task',
+        body: 'A plain-text description',
+      },
+    });
+    await updateSession.call({
+      toolId: 'update_issue',
+      arguments: {idOrKey: 'ENG-1004', body: 'A replacement description'},
+    });
+
+    expect(options.jira.request).toHaveBeenNthCalledWith(1, {
+      accessToken: 'access-token',
+      cloudId: 'cloud-1',
+      method: 'POST',
+      path: '/issue',
+      body: {
+        fields: {
+          project: {key: 'ENG'},
+          summary: 'New issue',
+          issuetype: {name: 'Task'},
+          description: jiraPlainTextToAdf('A plain-text description'),
+        },
+      },
+      operation: 'create_issue',
+    });
+    expect(options.jira.request).toHaveBeenNthCalledWith(2, {
+      accessToken: 'access-token',
+      cloudId: 'cloud-1',
+      method: 'PUT',
+      path: '/issue/ENG-1004',
+      body: {fields: {description: jiraPlainTextToAdf('A replacement description')}},
+      operation: 'update_issue',
+    });
+  });
+
+  it('maps provider rate limits and preserves Retry-After details', async () => {
+    const options = providerOptions(() =>
+      Promise.reject(new JiraIntegrationProviderError('rate-limited', 'Try again later', 19)),
+    );
+    const session = await openSession(options, ['search_issues']);
+
+    const result = await session.call({
+      toolId: 'search_issues',
+      arguments: {jql: 'project = ENG'},
+    });
+
+    expect(result).toMatchObject({
+      isError: true,
+      content: [{type: 'text', text: 'Try again later'}],
+      structuredContent: {code: 'rate-limited', retryAfterSeconds: 19},
+    });
+  });
+
+  it('maps Jira authorization failures to access-denied', async () => {
+    const options = providerOptions(() =>
+      Promise.reject(
+        new JiraIntegrationProviderError('access-denied', 'Jira request was rejected'),
+      ),
+    );
+    const session = await openSession(options, ['get_project']);
+
+    const result = await session.call({
+      toolId: 'get_project',
+      arguments: {idOrKey: 'ENG'},
+    });
+
+    expect(result).toMatchObject({
+      isError: true,
+      content: [{type: 'text', text: 'Jira request was rejected'}],
+      structuredContent: {code: 'access-denied'},
+    });
+  });
+
+  it('returns Jira resource errors as tool errors', async () => {
+    const options = providerOptions(async () => ({
+      status: 404,
+      body: {errorMessages: ['Issue does not exist']},
+    }));
+    const session = await openSession(options, ['get_issue']);
+
+    const result = await session.call({
+      toolId: 'get_issue',
+      arguments: {idOrKey: 'ENG-404'},
+    });
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Issue does not exist'}],
+    });
+  });
+
+  it('returns Jira validation details for a bad request', async () => {
+    const options = providerOptions(async () => ({
+      status: 400,
+      body: {errorMessages: ['The JQL query is invalid']},
+    }));
+    const session = await openSession(options, ['search_issues']);
+
+    const result = await session.call({
+      toolId: 'search_issues',
+      arguments: {jql: 'not valid'},
+    });
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'The JQL query is invalid'}],
+    });
+  });
+
+  it('reports successful empty Jira responses with their HTTP status', async () => {
+    const options = providerOptions(async () => ({status: 204, body: undefined}));
+    const session = await openSession(options, ['assign_issue']);
+
+    const result = await session.call({
+      toolId: 'assign_issue',
+      arguments: {idOrKey: 'ENG-1004', accountId: null},
+    });
+
+    expect(result).toEqual({
+      content: [{type: 'text', text: JSON.stringify({status: 204})}],
+      structuredContent: {status: 204},
+    });
+  });
+
+  it('rejects calls for unselected tools and missing required arguments', async () => {
+    const options = providerOptions();
+    const session = await openSession(options, ['get_issue']);
+
+    await expect(
+      session.call({toolId: 'add_comment', arguments: {idOrKey: 'ENG-1004', body: 'Comment'}}),
+    ).resolves.toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Unknown Jira tool: add_comment'}],
+    });
+    await expect(session.call({toolId: 'get_issue', arguments: {}})).resolves.toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Missing required parameter: idOrKey'}],
+    });
+    expect(options.jira.request).not.toHaveBeenCalled();
+  });
+
+  it('rejects create calls that omit the summary', async () => {
+    const options = providerOptions();
+    const session = await openSession(options, ['create_issue']);
+
+    const result = await session.call({toolId: 'create_issue', arguments: {}});
+
+    expect(result).toEqual({
+      isError: true,
+      content: [{type: 'text', text: 'Missing required parameter: summary'}],
+    });
+    expect(options.jira.request).not.toHaveBeenCalled();
+  });
+});

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);
+}